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