1 /* 2 * Copyright (c) 2021 Chipsea Technologies (Shenzhen) Corp., Ltd. All rights reserved. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 #ifndef _WIFI_HOST_WPA_H 16 #define _WIFI_HOST_WPA_H 17 18 #include "wifi_host.h" 19 20 /** 21 * WPA events.\n 22 * Events are generated by a WPA task be calling @ref fhost_wpa_send_event. 23 * They are then processed by the function @ref fhost_wpa_event_process and the callbacks 24 * registered with @ref fhost_wpa_cb_register 25 */ 26 enum fhost_wpa_event { 27 /** 28 * - desc: WPA task ends 29 * - data_type: int 30 * - data_value: contains wpa task exit code 31 */ 32 FHOST_WPA_EXIT = 1, 33 /** 34 * - desc: WPA started (i.e. initialization was sucessful) 35 * - data_type: int 36 * - data_value: contains UDP control port 37 */ 38 FHOST_WPA_STARTED, 39 /** 40 * - desc: Connection to an Access Point is completed 41 * - data_type: None 42 * - data_value: None 43 */ 44 FHOST_WPA_CONNECTED, 45 /** 46 * - desc: Connection to an Access Point is terminated 47 * - data_type: None 48 * - data_value: None 49 */ 50 FHOST_WPA_DISCONNECTED, 51 FHOST_WPA_LAST, 52 }; 53 54 /** 55 * wpa_supplicant state.\n 56 * The WPA task FSM looks like: 57 * @verbatim 58 +---------+ +---------------+ +-----------+ 59 | STOPPED | <----> | NOT_CONNECTED | <----> | CONNECTED | 60 +---------+ +---------------+ +-----------+ 61 @endverbatim 62 */ 63 enum fhost_wpa_state 64 { 65 /// wpa_supplicant is not running 66 FHOST_WPA_STATE_STOPPED, 67 /// wpa_supplicant is running but not connected 68 FHOST_WPA_STATE_NOT_CONNECTED, 69 /// wpa_supplicant is running and connected 70 FHOST_WPA_STATE_CONNECTED, 71 }; 72 73 /** 74 * Configuration of wpa_supplicant task 75 */ 76 struct fhost_wpa_config { 77 /** 78 * Name of the interface 79 */ 80 char iface_name[NET_AL_MAX_IFNAME]; 81 /** 82 * Index, at FHOST level, of the interface 83 */ 84 int fhost_vif_idx; 85 /** 86 * Pointer to a configuration buffer (may be null) 87 */ 88 char *iface_conf_buffer; 89 /** 90 * Name of the control interface: 91 * - NULL for no control interface 92 * - UDP for control interface via UDP socket 93 */ 94 char *ctrl_itf; 95 }; 96 97 /// WPA event message callback type 98 typedef void (*fhost_wpa_cb_t) (int fhost_vif_idx, enum fhost_wpa_event event, 99 void *event_params, void *arg); 100 101 /** 102 **************************************************************************************** 103 * @brief Init global variables used by fhost_wpa_xxxx functions 104 **************************************************************************************** 105 */ 106 void fhost_wpa_init(void); 107 108 /** 109 **************************************************************************************** 110 * @brief Start wpa_supplicant task for an interface 111 * 112 * This function is blocking until wpa_supplicant task is fully initialized (or an error 113 * is returned during task initialization). 114 * Only one wpa supplicant task can be started per interface. 115 * @note If the AP configuration is already known @ref fhost_wpa_create_network can be 116 * used instead. 117 * 118 * @param[in] fhost_vif_idx Index of the FHOST interface 119 * @param[in] config wpa_supplicant configuration (May be NULL, not yet supported) 120 * 121 * @return 0 if wpa_supplicant has been successfully initialized and !=0 otherwise. 122 **************************************************************************************** 123 */ 124 int fhost_wpa_start(int fhost_vif_idx, char *config); 125 126 /** 127 **************************************************************************************** 128 * @brief End wpa_supplicant task for an interface 129 * 130 * This function is blocking until wpa_supplicant task is deleted. 131 * 132 * @param[in] fhost_vif_idx Index of the FHOST interface 133 * 134 * @return 0 if wpa_supplicant has been successfully closed and !=0 otherwise. 135 **************************************************************************************** 136 */ 137 int fhost_wpa_end(int fhost_vif_idx); 138 139 /** 140 **************************************************************************************** 141 * @brief Retrieve the wpa task state 142 * 143 * @param[in] fhost_vif_idx Index of the FHOST interface 144 * 145 * @return current wpa_supplicant state for the interface 146 **************************************************************************************** 147 */ 148 enum fhost_wpa_state fhost_wpa_get_state(int fhost_vif_idx); 149 150 /** 151 **************************************************************************************** 152 * @brief Register a callback for a set of WPA events 153 * 154 * The callback will be called with the registered argument as WPA task emits one of the 155 * event in @p events bit-field. 156 * Up to @ref FHOST_WPA_EVENT_CB_CNT callbacks can be registered for one interface. 157 * 158 * @note Currently there is no synchronization between callback registration and event 159 * processing and it is assumed that cb will be registered before WPA task can emit any 160 * of the events. 161 * 162 * @note Callbacks are called in the context of the WPA task so is cannot block upon WPA 163 * task (e.g. it cannot send WPA command). 164 * 165 * @param[in] fhost_vif_idx Index of the FHOST interface 166 * @param[in] events Bit-field of events associated to the callback. 167 * @param[in] cb_func Callback function 168 * @param[in] cb_arg Callback function private argument 169 * 170 * @return 0 if callback has been successfully registered and !=0 otherwise. 171 **************************************************************************************** 172 */ 173 int fhost_wpa_cb_register(int fhost_vif_idx, int events, fhost_wpa_cb_t cb_func, void *cb_arg); 174 175 /** 176 **************************************************************************************** 177 * @brief Unregister a callback for WPA events 178 * 179 * Does nothing if callback wasn't previously registered. 180 * 181 * @param[in] fhost_vif_idx Index of the FHOST interface 182 * @param[in] cb_func Callback functions 183 * 184 * @return 0 if callback has been successfully unregistered and !=0 otherwise. 185 **************************************************************************************** 186 */ 187 int fhost_wpa_cb_unregister(int fhost_vif_idx, fhost_wpa_cb_t cb_func); 188 189 /** 190 **************************************************************************************** 191 * @brief Send a WPA event to the control task 192 * 193 * Emit a WPA event. This should only be used by a WPA task, and the event will be 194 * processed in the context of the calling task. 195 * @note For now, parameters are only 32bits and then passed as the address. 196 * 197 * @param[in] event WPA event id 198 * @param[in] param Event parameters 199 * @param[in] param_len Length, in bytes, of the parameters 200 * @param[in] fhost_vif_idx Index of the FHOST interface 201 * 202 * @return 0 on success and != 0 if error occured. 203 **************************************************************************************** 204 */ 205 int fhost_wpa_send_event(enum fhost_wpa_event event, void *param, int param_len, int fhost_vif_idx); 206 207 /** 208 **************************************************************************************** 209 * @brief Send command to the wpa_supplicant task associated and retrieve the response 210 * 211 * This function is blocking until the command is executed by wpa_supplicant. 212 * If no wpa_supplicant has been started for the requested interface or if it has been 213 * started without ctrl interface this function immediately returns an error. 214 * 215 * A timeout of @p timeout_ms is set for the response, meaning that if wpa_supplicant 216 * doesn't respond before the function will return an error. 217 * 218 * The response is truncated to fit inside the provided buffer, and if response is not 219 * needed the parameter @p resp can be NULL. In any case (i.e. even if no response buffer 220 * is provided) if the response starts with the string "FAIL" the functions returns 1. 221 * 222 * @param[in] fhost_vif_idx Index of the FHOST interface. 223 * @param[in] resp_buf Buffer to retrieve the response. 224 * @param[in,out] resp_buf_len Size, in bytes, of the response buffer. 225 * If no error is reported, it is updated with the size 226 * actually written in the response buffer. 227 * @param[in] timeout_ms Timeout, in ms, allowed to the wpa_supplicant task to 228 * execute the command (<0 means wait forever). 229 * @param[in] fmt Command to send to the wpa_supplicant task. The command 230 * is first formatted using optional parameters. 231 * 232 * @return <0 if an error occurred (invalid parameter, timeout, ...), 1 if the response 233 * starts with "FAIL" and 0 otherwise. 234 **************************************************************************************** 235 */ 236 int fhost_wpa_execute_cmd(int fhost_vif_idx, char *resp_buf, int *resp_buf_len, 237 int timeout_ms, const char *fmt, ...); 238 239 /** 240 **************************************************************************************** 241 * @brief Start wpa_supplicant and create a network configuration. 242 * 243 * This function should be used instead of @ref fhost_wpa_start to start the 244 * wpa_supplicant with a network already configured. 245 * The network configuration is a string in which each token separated by a ';' is used 246 * as parameter to 'SET_NETWORK' command. 247 * If @p enable is true then the function is blocking until connection to the network. 248 * (see @ref fhost_wpa_enable_network for details) 249 * 250 * @param[in] fhost_vif_idx Index of the FHOST interface. 251 * @param[in] net_cfg Network configuration. 252 * @param[in] enable Whether network should be enabled. 253 * @param[in] timeout_ms Timeout, in ms, passed to @ref fhost_wpa_enable_network if 254 * @p enable is true. 255 * 256 * @return 0 on success, <0 if error occurred. 257 **************************************************************************************** 258 */ 259 int fhost_wpa_create_network(int fhost_vif_idx, char *net_cfg, bool enable, int timeout_ms); 260 261 /** 262 **************************************************************************************** 263 * @brief Enable a wpa_supplicant network 264 * 265 * Enabling a network means that wpa_supplicant will try to connect to the AP configured 266 * in this network. 267 * The function is blocking until the connection to the network is completed (or timeout 268 * is reached). 269 * If @p timeout_ms is <0 then the function won't timeout and if it is 0 then the function 270 * returns immediately after enabling the network with 0 exit code. 271 * The network must have been created with @ref fhost_wpa_create_network first. 272 * 273 * @param[in] fhost_vif_idx Index of the FHOST interface. 274 * @param[in] timeout_ms Timeout, in ms, until connection is considered as failed. 275 * (<0 wait forever, 0 don't wait) 276 * 277 * @return 0 on success, <0 if error occurred. 278 **************************************************************************************** 279 */ 280 int fhost_wpa_enable_network(int fhost_vif_idx, int timeout_ms); 281 282 /** 283 **************************************************************************************** 284 * @brief Disable a wpa_supplicant network 285 * 286 * Disabling a network means that wpa_supplicant will disconnect from the AP and will no 287 * longer try to connect. 288 * The function is blocking until the connection to the network is completed. 289 * The network must have been created with @ref fhost_wpa_create_network first. 290 * 291 * @param[in] fhost_vif_idx Index of the FHOST interface. 292 * 293 * @return 0 on success, <0 if error occurred. 294 **************************************************************************************** 295 */ 296 int fhost_wpa_disable_network(int fhost_vif_idx); 297 298 int fhost_wpa_set_mgmt_rx_filter(int fhost_vif_idx, uint32_t filter); 299 int fhost_wpa_disconnect_network(int fhost_vif_idx); 300 int fhost_wpa_reconnect_network(int fhost_vif_idx, int timeout_ms); 301 int fhost_wpa_stop_ap(int fhost_vif_idx); 302 int fhost_wpa_disassociate_sta(int fhost_vif_idx, struct mac_addr *macaddr); 303 int fhost_wpa_wps(int fhost_vif_idx, bool enable, int timeout_ms); 304 int fhost_wpa_switch_channel(int fhost_vif_idx, uint32_t frequency); 305 306 int fhost_bss_flush(int fhost_vif_idx); 307 308 void wpas_data_save(void); 309 void wpas_data_restore(void); 310 311 #endif // _WIFI_HOST_WPA_H 312