1 // Copyright 2015-2016 Espressif Systems (Shanghai) PTE LTD 2 // 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 /* 16 * All the APIs declared here are internal only APIs, it can only be used by 17 * espressif internal modules, such as SSC, LWIP, TCPIP adapter etc, espressif 18 * customers are not recommended to use them. 19 * 20 * If someone really want to use specified APIs declared in here, please contact 21 * espressif AE/developer to make sure you know the limitations or risk of 22 * the API, otherwise you may get unexpected behavior!!! 23 * 24 */ 25 26 27 #ifndef __ESP_WIFI_INTERNAL_H__ 28 #define __ESP_WIFI_INTERNAL_H__ 29 30 #include <stdint.h> 31 #include <stdbool.h> 32 #include "esp_osal/esp_osal.h" 33 #include "esp_osal/queue.h" 34 #include "sys/queue.h" 35 #include "esp_err.h" 36 #include "esp_wifi_types.h" 37 #include "esp_event.h" 38 #include "esp_wifi.h" 39 #include "esp_smartconfig.h" 40 #include "wifi_types.h" 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 typedef struct { 47 QueueHandle_t handle; /**< FreeRTOS queue handler */ 48 void *storage; /**< storage for FreeRTOS queue */ 49 } wifi_static_queue_t; 50 51 /** 52 * @brief WiFi log level 53 * 54 */ 55 typedef enum { 56 WIFI_LOG_NONE = 0, 57 WIFI_LOG_ERROR , /*enabled by default*/ 58 WIFI_LOG_WARNING, /*enabled by default*/ 59 WIFI_LOG_INFO, /*enabled by default*/ 60 WIFI_LOG_DEBUG, /*can be set in menuconfig*/ 61 WIFI_LOG_VERBOSE, /*can be set in menuconfig*/ 62 } wifi_log_level_t; 63 64 /** 65 * @brief WiFi log module definition 66 * 67 */ 68 typedef enum { 69 WIFI_LOG_MODULE_ALL = 0, /*all log modules */ 70 WIFI_LOG_MODULE_WIFI, /*logs related to WiFi*/ 71 WIFI_LOG_MODULE_COEX, /*logs related to WiFi and BT(or BLE) coexist*/ 72 WIFI_LOG_MODULE_MESH, /*logs related to Mesh*/ 73 } wifi_log_module_t; 74 75 /** 76 * @brief WiFi log submodule definition 77 * 78 */ 79 #define WIFI_LOG_SUBMODULE_ALL (0) /*all log submodules*/ 80 #define WIFI_LOG_SUBMODULE_INIT (1) /*logs related to initialization*/ 81 #define WIFI_LOG_SUBMODULE_IOCTL (1<<1) /*logs related to API calling*/ 82 #define WIFI_LOG_SUBMODULE_CONN (1<<2) /*logs related to connecting*/ 83 #define WIFI_LOG_SUBMODULE_SCAN (1<<3) /*logs related to scaning*/ 84 85 86 /** 87 * @brief Initialize Wi-Fi Driver 88 * Alloc resource for WiFi driver, such as WiFi control structure, RX/TX buffer, 89 * WiFi NVS structure among others. 90 * 91 * For the most part, you need not call this function directly. It gets called 92 * from esp_wifi_init(). 93 * 94 * This function may be called, if you only need to initialize the Wi-Fi driver 95 * without having to use the network stack on top. 96 * 97 * @param config provide WiFi init configuration 98 * 99 * @return 100 * - ESP_OK: succeed 101 * - ESP_ERR_NO_MEM: out of memory 102 * - others: refer to error code esp_err.h 103 */ 104 esp_err_t esp_wifi_init_internal(const wifi_init_config_t *config); 105 106 /** 107 * @brief Deinitialize Wi-Fi Driver 108 * Free resource for WiFi driver, such as WiFi control structure, RX/TX buffer, 109 * WiFi NVS structure among others. 110 * 111 * For the most part, you need not call this function directly. It gets called 112 * from esp_wifi_deinit(). 113 * 114 * This function may be called, if you call esp_wifi_init_internal to initialize 115 * WiFi driver. 116 * 117 * @return 118 * - ESP_OK: succeed 119 * - others: refer to error code esp_err.h 120 */ 121 esp_err_t esp_wifi_deinit_internal(void); 122 123 /** 124 * @brief free the rx buffer which allocated by wifi driver 125 * 126 * @param void* buffer: rx buffer pointer 127 */ 128 void esp_wifi_internal_free_rx_buffer(void* buffer); 129 130 /** 131 * @brief transmit the buffer via wifi driver 132 * 133 * This API makes a copy of the input buffer and then forwards the buffer 134 * copy to WiFi driver. 135 * 136 * @param wifi_interface_t wifi_if : wifi interface id 137 * @param void *buffer : the buffer to be tansmit 138 * @param uint16_t len : the length of buffer 139 * 140 * @return 141 * - ESP_OK : Successfully transmit the buffer to wifi driver 142 * - ESP_ERR_NO_MEM: out of memory 143 * - ESP_ERR_WIFI_ARG: invalid argument 144 * - ESP_ERR_WIFI_IF : WiFi interface is invalid 145 * - ESP_ERR_WIFI_CONN : WiFi interface is not created, e.g. send the data to STA while WiFi mode is AP mode 146 * - ESP_ERR_WIFI_NOT_STARTED : WiFi is not started 147 * - ESP_ERR_WIFI_STATE : WiFi internal state is not ready, e.g. WiFi is not started 148 * - ESP_ERR_WIFI_NOT_ASSOC : WiFi is not associated 149 * - ESP_ERR_WIFI_TX_DISALLOW : WiFi TX is disallowed, e.g. WiFi hasn't pass the authentication 150 * - ESP_ERR_WIFI_POST : caller fails to post event to WiFi task 151 */ 152 int esp_wifi_internal_tx(wifi_interface_t wifi_if, void *buffer, uint16_t len); 153 154 /** 155 * @brief The net stack buffer reference counter callback function 156 * 157 */ 158 typedef void (*wifi_netstack_buf_ref_cb_t)(void *netstack_buf); 159 160 /** 161 * @brief The net stack buffer free callback function 162 * 163 */ 164 typedef void (*wifi_netstack_buf_free_cb_t)(void *netstack_buf); 165 166 /** 167 * @brief transmit the buffer by reference via wifi driver 168 * 169 * This API firstly increases the reference counter of the input buffer and 170 * then forwards the buffer to WiFi driver. The WiFi driver will free the buffer 171 * after processing it. Use esp_wifi_internal_tx() if the uplayer buffer doesn't 172 * supports reference counter. 173 * 174 * @param wifi_if : wifi interface id 175 * @param buffer : the buffer to be tansmit 176 * @param len : the length of buffer 177 * @param netstack_buf : the netstack buffer related to bufffer 178 * 179 * @return 180 * - ESP_OK : Successfully transmit the buffer to wifi driver 181 * - ESP_ERR_NO_MEM: out of memory 182 * - ESP_ERR_WIFI_ARG: invalid argument 183 * - ESP_ERR_WIFI_IF : WiFi interface is invalid 184 * - ESP_ERR_WIFI_CONN : WiFi interface is not created, e.g. send the data to STA while WiFi mode is AP mode 185 * - ESP_ERR_WIFI_NOT_STARTED : WiFi is not started 186 * - ESP_ERR_WIFI_STATE : WiFi internal state is not ready, e.g. WiFi is not started 187 * - ESP_ERR_WIFI_NOT_ASSOC : WiFi is not associated 188 * - ESP_ERR_WIFI_TX_DISALLOW : WiFi TX is disallowed, e.g. WiFi hasn't pass the authentication 189 * - ESP_ERR_WIFI_POST : caller fails to post event to WiFi task 190 */ 191 esp_err_t esp_wifi_internal_tx_by_ref(wifi_interface_t ifx, void *buffer, size_t len, void *netstack_buf); 192 193 /** 194 * @brief Initialize WAPI function when wpa_supplicant initialize. 195 * 196 * This API is privately used, be careful not open to external applicantion. 197 * 198 * @return 199 * - ESP_OK : succeed 200 * - ESP_ERR_WAPI_INTERNAL : Internal error 201 */ 202 esp_err_t esp_wifi_internal_wapi_init(void); 203 204 /** 205 * @brief De-initialize WAPI function when wpa_supplicant de-initialize. 206 * 207 * This API is privately used, be careful not open to external applicantion. 208 * 209 * @return 210 * - ESP_OK : succeed 211 */ 212 esp_err_t esp_wifi_internal_wapi_deinit(void); 213 214 /** 215 * @brief register the net stack buffer reference increasing and free callback 216 * 217 * @param ref : net stack buffer reference callback 218 * @param free: net stack buffer free callback 219 * 220 * @return 221 * - ESP_OK : Successfully transmit the buffer to wifi driver 222 * - others : failed to register the callback 223 */ 224 esp_err_t esp_wifi_internal_reg_netstack_buf_cb(wifi_netstack_buf_ref_cb_t ref, wifi_netstack_buf_free_cb_t free); 225 226 227 /** 228 * @brief The WiFi RX callback function 229 * 230 * Each time the WiFi need to forward the packets to high layer, the callback function will be called 231 */ 232 typedef esp_err_t (*wifi_rxcb_t)(void *buffer, uint16_t len, void *eb); 233 234 /** 235 * @brief Set the WiFi RX callback 236 * 237 * @attention 1. Currently we support only one RX callback for each interface 238 * 239 * @param wifi_interface_t ifx : interface 240 * @param wifi_rxcb_t fn : WiFi RX callback 241 * 242 * @return 243 * - ESP_OK : succeed 244 * - others : fail 245 */ 246 esp_err_t esp_wifi_internal_reg_rxcb(wifi_interface_t ifx, wifi_rxcb_t fn); 247 248 /** 249 * @brief Notify WIFI driver that the station got ip successfully 250 * 251 * @return 252 * - ESP_OK : succeed 253 * - others : fail 254 */ 255 esp_err_t esp_wifi_internal_set_sta_ip(void); 256 257 /** 258 * @brief enable or disable transmitting WiFi MAC frame with fixed rate 259 * 260 * @attention 1. If fixed rate is enabled, both management and data frame are transmitted with fixed rate 261 * @attention 2. Make sure that the receiver is able to receive the frame with the fixed rate if you want the frame to be received 262 * 263 * @param ifx : wifi interface 264 * @param en : false - disable, true - enable 265 * @param rate : PHY rate 266 * 267 * @return 268 * - ERR_OK : succeed 269 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 270 * - ESP_ERR_WIFI_NOT_STARTED: WiFi was not started by esp_wifi_start 271 * - ESP_ERR_WIFI_IF : invalid WiFi interface 272 * - ESP_ERR_INVALID_ARG : invalid rate 273 * - ESP_ERR_NOT_SUPPORTED : do not support to set fixed rate if TX AMPDU is enabled 274 */ 275 esp_err_t esp_wifi_internal_set_fix_rate(wifi_interface_t ifx, bool en, wifi_phy_rate_t rate); 276 277 /** 278 * @brief Start SmartConfig, config ESP device to connect AP. You need to broadcast information by phone APP. 279 * Device sniffer special packets from the air that containing SSID and password of target AP. 280 * 281 * @attention 1. This API can be called in station or softAP-station mode. 282 * @attention 2. Can not call esp_smartconfig_start twice before it finish, please call 283 * esp_smartconfig_stop first. 284 * 285 * @param config pointer to smartconfig start configure structure 286 * 287 * @return 288 * - ESP_OK: succeed 289 * - others: fail 290 */ 291 esp_err_t esp_smartconfig_internal_start(const smartconfig_start_config_t *config); 292 293 /** 294 * @brief Stop SmartConfig, free the buffer taken by esp_smartconfig_start. 295 * 296 * @attention Whether connect to AP succeed or not, this API should be called to free 297 * memory taken by smartconfig_start. 298 * 299 * @return 300 * - ESP_OK: succeed 301 * - others: fail 302 */ 303 esp_err_t esp_smartconfig_internal_stop(void); 304 305 /** 306 * @brief Check the MD5 values of the OS adapter header files in IDF and WiFi library 307 * 308 * @attention 1. It is used for internal CI version check 309 * 310 * @return 311 * - ESP_OK : succeed 312 * - ESP_WIFI_INVALID_ARG : MD5 check fail 313 */ 314 esp_err_t esp_wifi_internal_osi_funcs_md5_check(const char *md5); 315 316 /** 317 * @brief Check the MD5 values of the crypto types header files in IDF and WiFi library 318 * 319 * @attention 1. It is used for internal CI version check 320 * 321 * @return 322 * - ESP_OK : succeed 323 * - ESP_WIFI_INVALID_ARG : MD5 check fail 324 */ 325 esp_err_t esp_wifi_internal_crypto_funcs_md5_check(const char *md5); 326 327 /** 328 * @brief Check the MD5 values of the esp_wifi_types.h in IDF and WiFi library 329 * 330 * @attention 1. It is used for internal CI version check 331 * 332 * @return 333 * - ESP_OK : succeed 334 * - ESP_WIFI_INVALID_ARG : MD5 check fail 335 */ 336 esp_err_t esp_wifi_internal_wifi_type_md5_check(const char *md5); 337 338 /** 339 * @brief Check the MD5 values of the esp_wifi.h in IDF and WiFi library 340 * 341 * @attention 1. It is used for internal CI version check 342 * 343 * @return 344 * - ESP_OK : succeed 345 * - ESP_WIFI_INVALID_ARG : MD5 check fail 346 */ 347 esp_err_t esp_wifi_internal_esp_wifi_md5_check(const char *md5); 348 349 /** 350 * @brief Allocate a chunk of memory for WiFi driver 351 * 352 * @attention This API is not used for DMA memory allocation. 353 * 354 * @param size_t size : Size, in bytes, of the amount of memory to allocate 355 * 356 * @return A pointer to the memory allocated on success, NULL on failure 357 */ 358 void *wifi_malloc( size_t size ); 359 360 /** 361 * @brief Reallocate a chunk of memory for WiFi driver 362 * 363 * @attention This API is not used for DMA memory allocation. 364 * 365 * @param void * ptr : Pointer to previously allocated memory, or NULL for a new allocation. 366 * @param size_t size : Size, in bytes, of the amount of memory to allocate 367 * 368 * @return A pointer to the memory allocated on success, NULL on failure 369 */ 370 void *wifi_realloc( void *ptr, size_t size ); 371 372 /** 373 * @brief Callocate memory for WiFi driver 374 * 375 * @attention This API is not used for DMA memory allocation. 376 * 377 * @param size_t n : Number of continuing chunks of memory to allocate 378 * @param size_t size : Size, in bytes, of the amount of memory to allocate 379 * 380 * @return A pointer to the memory allocated on success, NULL on failure 381 */ 382 void *wifi_calloc( size_t n, size_t size ); 383 384 /** 385 * @brief Update WiFi MAC time 386 * 387 * @param uint32_t time_delta : time duration since the WiFi/BT common clock is disabled 388 * 389 * @return Always returns ESP_OK 390 */ 391 typedef esp_err_t (* wifi_mac_time_update_cb_t)( uint32_t time_delta ); 392 393 /** 394 * @brief Update WiFi MAC time 395 * 396 * @param uint32_t time_delta : time duration since the WiFi/BT common clock is disabled 397 * 398 * @return Always returns ESP_OK 399 */ 400 esp_err_t esp_wifi_internal_update_mac_time( uint32_t time_delta ); 401 402 /** 403 * @brief Set current WiFi log level 404 * 405 * @param level Log level. 406 * 407 * @return 408 * - ESP_OK: succeed 409 * - ESP_FAIL: level is invalid 410 */ 411 esp_err_t esp_wifi_internal_set_log_level(wifi_log_level_t level); 412 413 /** 414 * @brief Set current log module and submodule 415 * 416 * @param module Log module 417 * @param submodule Log submodule 418 * @param enable enable or disable 419 * If module == 0 && enable == 0, all log modules are disabled. 420 * If module == 0 && enable == 1, all log modules are enabled. 421 * If submodule == 0 && enable == 0, all log submodules are disabled. 422 * If submodule == 0 && enable == 1, all log submodules are enabled. 423 * 424 * @return 425 * - ESP_OK: succeed 426 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 427 * - ESP_ERR_WIFI_ARG: invalid argument 428 */ 429 esp_err_t esp_wifi_internal_set_log_mod(wifi_log_module_t module, uint32_t submodule, bool enable); 430 431 /** 432 * @brief Get current WiFi log info 433 * 434 * @param log_level the return log level. 435 * @param log_mod the return log module and submodule 436 * 437 * @return 438 * - ESP_OK: succeed 439 */ 440 esp_err_t esp_wifi_internal_get_log(wifi_log_level_t *log_level, uint32_t *log_mod); 441 442 /** 443 * @brief A general API to set/get WiFi internal configuration, it's for debug only 444 * 445 * @param cmd : ioctl command type 446 * @param cfg : configuration for the command 447 * 448 * @return 449 * - ESP_OK: succeed 450 * - others: failed 451 */ 452 esp_err_t esp_wifi_internal_ioctl(int cmd, wifi_ioctl_config_t *cfg); 453 454 /** 455 * @brief Get the user-configured channel info 456 * 457 * @param ifx : WiFi interface 458 * @param primary : store the configured primary channel 459 * @param second : store the configured second channel 460 * 461 * @return 462 * - ESP_OK: succeed 463 */ 464 esp_err_t esp_wifi_internal_get_config_channel(wifi_interface_t ifx, uint8_t *primary, uint8_t *second); 465 466 /** 467 * @brief Get the negotiated channel info after WiFi connection established 468 * 469 * @param ifx : WiFi interface 470 * @param aid : the connection number when a STA connects to the softAP 471 * @param primary : store the negotiated primary channel 472 * @param second : store the negotiated second channel 473 * @attention the aid param is only works when the ESP32 in softAP/softAP+STA mode 474 * 475 * @return 476 * - ESP_OK: succeed 477 */ 478 esp_err_t esp_wifi_internal_get_negotiated_channel(wifi_interface_t ifx, uint8_t aid, uint8_t *primary, uint8_t *second); 479 480 /** 481 * @brief Get the negotiated bandwidth info after WiFi connection established 482 * 483 * @param ifx : WiFi interface 484 * @param bw : store the negotiated bandwidth 485 * 486 * @return 487 * - ESP_OK: succeed 488 */ 489 esp_err_t esp_wifi_internal_get_negotiated_bandwidth(wifi_interface_t ifx, uint8_t aid, uint8_t *bw); 490 491 #if SOC_WIFI_HW_TSF 492 /** 493 * @brief Check if WiFi TSF is active 494 * 495 * @return 496 * - true: Active 497 * - false: Not active 498 */ 499 bool esp_wifi_internal_is_tsf_active(void); 500 501 /** 502 * @brief Update WIFI light sleep wake ahead time 503 * 504 */ 505 void esp_wifi_internal_update_light_sleep_wake_ahead_time(uint32_t); 506 #endif 507 508 #if CONFIG_MAC_BB_PD 509 /** 510 * @brief Enable or disable powering down MAC and baseband when Wi-Fi is sleeping. 511 * 512 * @param enable : enable or disable 513 * 514 * @return 515 * - ESP_OK: succeed 516 */ 517 esp_err_t esp_wifi_internal_set_mac_sleep(bool enable); 518 519 /** 520 * @brief mac bb sleep. 521 */ 522 void pm_mac_sleep(void); 523 524 /** 525 * @brief mac bb wakeup. 526 */ 527 void pm_mac_wakeup(void); 528 #endif 529 530 /** 531 * @breif TxDone callback function type. Should be registered using esp_wifi_set_tx_done_cb() 532 * 533 * @param ifidx The interface id that the tx callback has been triggered from 534 * @param data Pointer to the data transmitted 535 * @param data_len Length of the data transmitted 536 * @param txStatus True:if the data was transmitted sucessfully False: if data transmission failed 537 */ 538 typedef void (* wifi_tx_done_cb_t)(uint8_t ifidx, uint8_t *data, uint16_t *data_len, bool txStatus); 539 540 /** 541 * @brief Register the txDone callback function of type wifi_tx_done_cb_t 542 * 543 * @param cb The callback function 544 * 545 * @return 546 * - ESP_OK: succeed 547 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 548 * - ESP_ERR_WIFI_NOT_STARTED: WiFi is not started by esp_wifi_start 549 */ 550 esp_err_t esp_wifi_set_tx_done_cb(wifi_tx_done_cb_t cb); 551 552 /** 553 * @brief Set device spp amsdu attributes 554 * 555 * @param ifx: WiFi interface 556 * @param spp_cap: spp amsdu capable 557 * @param spp_req: spp amsdu require 558 * 559 * @return 560 * - ESP_OK: succeed 561 * - ESP_ERR_WIFI_NOT_INIT: WiFi is not initialized by esp_wifi_init 562 * - ESP_ERR_WIFI_IF : invalid WiFi interface 563 */ 564 esp_err_t esp_wifi_internal_set_spp_amsdu(wifi_interface_t ifidx, bool spp_cap, bool spp_req); 565 566 /** 567 * @brief Update WIFI light sleep default parameters 568 * 569 * @param min_freq_mhz: minimum frequency of DFS 570 * @param max_freq_mhz: maximum frequency of DFS 571 */ 572 void esp_wifi_internal_update_light_sleep_default_params(int min_freq_mhz, int max_freq_mhz); 573 574 /** 575 * @brief Set the delay time for wifi to enter the sleep state when light sleep 576 * 577 * @param return_to_sleep_delay: minimum timeout time for waiting to receive 578 * data, when no data is received during the timeout period, 579 * the wifi enters the sleep process. 580 */ 581 void esp_wifi_set_sleep_delay_time(uint32_t return_to_sleep_delay); 582 583 /** 584 * @brief Set wifi keep alive time 585 * 586 * @param keep_alive_time: keep alive time 587 */ 588 void esp_wifi_set_keep_alive_time(uint32_t keep_alive_time); 589 590 #ifdef __cplusplus 591 } 592 #endif 593 594 #endif /* __ESP_WIFI_H__ */ 595