1 // Copyright (C) 2022 Beken Corporation 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 #pragma once 16 17 #include <modules/wifi_types.h> 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /* @brief Overview about this API header 24 * 25 */ 26 27 /** 28 * @brief WiFi APIs Version 2.0 29 * @defgroup bk_api_wifi_v2 New WiFi API group 30 * @{ 31 */ 32 33 /** 34 * @brief This API initializes the WiFi driver, e.g. creating task for supplicant, allocating 35 * resource for low level WiFi driver etc. 36 * 37 * Usage example: 38 * 39 * wifi_init_config_t init_config = WIFI_DEFAULT_INIT_CONFIG; 40 * BK_LOG_ON_ERR(bk_wifi_init(&init_config); 41 * 42 * @attention 1. This API is the 1st API that should be called before any other WiFi API can be called. 43 * @attention 2. Make sure the reserved field in config is zero, otherwise you may encounter 44 * compatibility issue in future if more config fields are added. 45 * 46 * @return 47 * - BK_OK: succeed 48 * - others: other errors. 49 */ 50 bk_err_t bk_wifi_init(const wifi_init_config_t *init_config); 51 52 /** 53 * @brief Deinit the BK WiFi driver 54 * 55 * This API free all resources related to WiFi. 56 * 57 * @attention 1. This API is not ready yet, will support in future release. 58 * 59 * @return 60 * - BK_OK: succeed 61 * - BK_ERR_NOT_SUPPORT: The API is not supported yet. 62 * - others: other errors. 63 */ 64 bk_err_t bk_wifi_deinit(void); 65 66 /** 67 * @brief Start the BK STA 68 * 69 * This API init the resoure specific to BK STA, e.g. init STA specific globals, init 70 * the supplicant and STA specific WiFi driver etc. 71 * 72 * @attention 1. Make sure the bk_wifi_sta_set_config() are succeedful before calling this API. 73 * @attention 2. This API connect the BK STA to the configured AP automatically. 74 * @attention 3. If the BK STA is already started, this API ignores the request and returns BK_OK. 75 * if you want to restart the BK STA, call bk_wifi_sta_stop() first and then call 76 * this API. 77 * @attention 4. TODO description about fast connection 78 * 79 * @return 80 * - BK_OK: succeed 81 * - BK_ERR_WIFI_STA_NOT_CONFIG: the BK STA is not configured. 82 * - BK_ERR_WIFI_MONITOR_IP: the BK STA can't be started because monitor is started. 83 * - others: other errors. 84 */ 85 bk_err_t bk_wifi_sta_start(void); 86 87 /** 88 * @brief Stop the BK STA 89 * 90 * @attention This API causes the BK STA disconnect from the AP, it similar as 91 * bk_wifi_sta_disconnect(), but this API may free resource. 92 * 93 * @return 94 * - BK_OK: succeed 95 * - BK_FAIL: fail 96 */ 97 bk_err_t bk_wifi_sta_stop(void); 98 99 /** 100 * @brief Stop the pure scan operation 101 * 102 * @attention This API causes the BK STA disconnect from the AP, it similar as 103 * bk_wifi_sta_disconnect(), but this API may free resource. 104 * 105 * @return 106 * - BK_OK: succeed 107 * - BK_FAIL: fail 108 */ 109 bk_err_t bk_wifi_scan_stop(void); 110 111 /** 112 * @brief Config the BK STA 113 * 114 * This API configures the basic configurations of the BK STA, it should be called 115 * before we call bk_wifi_sta_start() to start the BK STA. It can also be used to 116 * update the configuration after the BK STA is started. 117 * 118 * Usage example: 119 * 120 * 121 * os_strncpy(sta_config.ssid, "ssid", WIFI_SSID_STR_LEN); 122 * os_strncpy(sta_config.password, "password"); 123 * //more initialization here 124 * BK_LOG_ON_ERR(bk_wifi_sta_set_config(&sta_config)); 125 * 126 * @attention 1. Don't call this API when the monitor is in-progress 127 * @attention 2. If STA is already connected to AP, this API cases BK STA reconnects the AP. 128 * @attention 3. Make sure the reserved fields in sta_config is zero, otherwise you may 129 * encounter compatibility issue in future if more config fields are added. 130 * @attention 4. Auto reconnect max count and timeout can be set. When user app receives 131 * EVENT_WIFI_STA_DISCONNECTED event, it's user app's responsibility to 132 * reconnect to AP manually. Max count and timeout set to zero to let 133 * supplicant automatically handles connection without user app's interaction. 134 * 135 * @param sta_config the STA configuration 136 * @return 137 * - BK_OK: succeed 138 * - BK_ERR_STA_NOT_STARTED: the STA is not started, call bk_wifi_sta_start() first. 139 * - BK_ERR_NULL_PARAM: parameter config is NULL. 140 * - BK_ERR_WIFI_RESERVED_FIELD: the reserved field of config is not 0. 141 * - others: other errors 142 */ 143 bk_err_t bk_wifi_sta_set_config(const wifi_sta_config_t *sta_config); 144 145 /** 146 * @brief Get the configuration of the BK STA. 147 * 148 * @param sta_config store the BK STA configuration 149 * 150 * @return 151 * - BK_OK: succeed 152 * - BK_ERR_NULL_PARAM: the parameter config is NULL. 153 * - BK_ERR_WIFI_STA_NOT_CONFIG: STA is not configured yet. 154 * - others: other errors 155 */ 156 bk_err_t bk_wifi_sta_get_config(wifi_sta_config_t *sta_config); 157 158 /** 159 * @brief Get the WiFi station state of the BK STA. 160 * 161 * @attention the difference between this API and bk_wifi_sta_get_link_status() is 162 * - This API gets the actual WiFi STA link status and reason code 163 - If sta is idle or connected, reason code will be WIFI_REASON_MAX 164 * 165 * @param state store the WiFi station state of the BK STA 166 * 167 * @return 168 * - BK_OK: succeed 169 * - BK_ERR_NULL_PARAM: the parameter config is NULL. 170 * - others: other errors 171 */ 172 bk_err_t bk_wifi_sta_get_linkstate_with_reason(wifi_linkstate_reason_t *info); 173 174 /** 175 * @brief Get the WiFi link info of the BK STA. 176 * 177 * Get the actual WiFi link status of the BK STA. 178 * 179 * @attention the difference between this API and bk_wifi_sta_get_config() is 180 * - This API gets the actual STA link info while the later gets the configured value 181 * - This API can get more info of the link, such as RSSI, WiFi link status, AID etc. 182 * - The AID is only valid if @link_status->state is WIFI_LINK_CONNECTED. 183 * 184 * @param link_status store the WiFi link status of the BK STA 185 * 186 * @return 187 * - BK_OK: succeed 188 * - BK_ERR_NULL_PARAM: the parameter link_info is NULL. 189 * - BK_ERR_WIFI_DRIVER: WiFi low level driver has failure. 190 * - BK_ERR_WIFI_NO_MEM: Not enough memory 191 * - others: other errors 192 */ 193 bk_err_t bk_wifi_sta_get_link_status(wifi_link_status_t *link_status); 194 195 /** 196 * @brief Connect the BK STA to the AP. 197 * 198 * @attention 1. Make sure STA is started by bk_wifi_sta_start() before calling this API. 199 * @attention 2. Don't call this API when the monitor is in-progress 200 * @attention 3. If STA is already connected to AP, this API reconnects the BK STA. 201 * @attention 4. TODO - multiple same SSID connect??? 202 * 203 * @return 204 * - BK_OK: succeed 205 * - BK_ERR_WIFI_STA_NOT_STARTED: the STA is not started, call bk_wifi_sta_start() first. 206 * - BK_ERR_WIFI_MONITOR_IP: the API is not allowed because monitor is in-progress. 207 * - others: other failures. 208 */ 209 bk_err_t bk_wifi_sta_connect(void); 210 211 /** 212 * @brief Disconnect the WiFi connection of the BK STA 213 * 214 * @attention TODO - add description about disconnect event! 215 * 216 * @return 217 * - BK_OK: succeed 218 * - others: other failures. 219 */ 220 bk_err_t bk_wifi_sta_disconnect(void); 221 222 /** 223 * @brief Start a scan 224 * 225 * This API notifies the WiFi driver to start a scan, the event EVENT_WIFI_SCAN_DONE will 226 * be raised if the scan is completed. General steps to use this API: 227 * - prepare the scan done event callback, the callback can call bk_wifi_scan_get_result() 228 * to get the scan result and then call bk_wifi_scan_free_result() to free the resource. 229 * - call bk_event_register_cb(EVENT_MOD_WIFI, EVENT_WIFI_SCAN_DONE, ...) to register 230 * scan done event callback. 231 * - call this API to trigger this the scan. 232 * 233 * Usage example: 234 * 235 * //Define your scan done handler 236 * int scan_done_handler(void *arg, event_module_t event_module, int event_id, void *event_data) 237 * { 238 * wifi_scan_result_t scan_result = {0}; 239 * 240 * BK_LOG_ON_ERR(bk_wifi_scan_get_result(&scan_result)); 241 * bk_wifi_scan_dump_result(&scan_result); 242 * bk_wifi_scan_free_result(&scan_result); 243 * 244 * return BK_OK; 245 * } 246 * 247 * //Start the scan 248 * wifi_scan_config_t config = {0}; 249 * 250 * BK_LOG_ON_ERR(bk_event_register_cb(EVENT_MOD_WIFI, EVENT_WIFI_SCAN_DONE, scan_done_handler, NULL)); 251 * BK_LOG_ON_ERR(bk_wifi_scan_start(&scan_config)); 252 * 253 * @attention 1. This API triggers an active scan on all channels (TODO double check) 254 * @attention 2. Pass NULL scan_config to scan all APs, otherwise scan the SSID specified in scan_config.ssid 255 * @attention 3. Make sure the reserved fields in scan_config is zero, otherwise you may 256 * encounter compatibility issue in future if more config fields are added. 257 * @attention 4. TODO scan result limits??? 258 * 259 * @param scan_config the configuration of scan 260 * 261 * @return 262 * - BK_OK: succeed 263 * - BK_ERR_WIFI_STA_NOT_STARTED: the STA is not started, call bk_wifi_sta_start() first. 264 * - BK_ERR_WIFI_MONITOR_IP: the API is not allowed because monitor is in-progress. 265 * - others: other failures. 266 */ 267 bk_err_t bk_wifi_scan_start(const wifi_scan_config_t *scan_config); 268 269 /** 270 * @brief Get the scan result 271 * 272 * Usage example: 273 * 274 * wifi_scan_result_t scan_result = {0}; 275 * 276 * BK_LOG_ON_ERR(bk_wifi_scan_get_result(&scan_result)); 277 * bk_wifi_scan_free_result(&scan_result); 278 * 279 * @attention 1. The caller don't need to allocate memory for scan_result->aps, this API will 280 * allocate the memory for scan_result->aps according to the actual found AP number. 281 * @attention 2. Don't forget to call bk_wifi_scan_free_result(&scan_result) to free the 282 * the resource allocated in this API, otherwise memory leak. 283 * 284 * @param scan_result store the scan result 285 * 286 * @return 287 * - BK_OK: succeed 288 * - BK_ERR_NULL_PARAM: NULL scan_result 289 * - BK_ERR_NO_MEM: out of memory 290 * - others: other failures 291 */ 292 bk_err_t bk_wifi_scan_get_result(wifi_scan_result_t *scan_result); 293 294 /** 295 * @brief Dump the scan result 296 * 297 * @param scan_result The scan result to be dumped. 298 * 299 * @return 300 * - BK_OK: succeed 301 * - BK_ERR_PARAM: invalid scan result 302 */ 303 bk_err_t bk_wifi_scan_dump_result(const wifi_scan_result_t *scan_result); 304 305 /** 306 * @brief Free the scan result 307 * 308 * @attention This API free scan_result->aps which allocated in bk_wifi_scan_get_result(), 309 * it doesn't free scan_result. So if scan_result is allocated by the caller, 310 * the caller need to free it. 311 * 312 * @param scan_result The scan result to be freed. 313 * 314 * @return 315 * - BK_OK: always succeed 316 */ 317 void bk_wifi_scan_free_result(wifi_scan_result_t *scan_result); 318 319 320 /** 321 * @brief Add/Update/Del STA's Vendor Specific IE **before** connect to AP. 322 * 323 * @attention If you want to add vsie when sta starts, just initialize wifi_sta_config_t 324 * when call bk_wifi_sta_set_config(). 325 * 326 * @param buf vsie buf 327 * @param len vsie buf len 328 * 329 * @return 330 * - BK_OK: succeed 331 * - others: other errors 332 */ 333 bk_err_t bk_wifi_sta_add_vendor_ie(uint8_t frame, uint8_t *vsie, uint8_t len); 334 bk_err_t bk_wifi_sta_update_vendor_ie(uint8_t frame, uint8_t *vsie, uint8_t len); 335 bk_err_t bk_wifi_sta_del_vendor_ie(uint8_t frame); 336 337 /** 338 * @brief Start the BK AP 339 * 340 * This API init the resoure specific to BK AP, e.g. init BK AP specific globals, init 341 * the hostapd and AP specific WiFi driver etc. 342 * 343 * If the BK AP is already started, this API ignores the request and returns BK_OK, we can 344 * call bk_wifi_ap_stop() to stop BK AP first and then call bk_wifi_ap_start() to restart it. 345 * 346 * **Restart** AP Usage example: 347 * 348 * BK_LOG_ON_ERR(bk_wifi_ap_stop()); 349 * BK_LOG_ON_ERR(bk_wifi_ap_start()); 350 * 351 * @attention 1. Don't call this API when the monitor is in-progress 352 * @attention 2. If bk_wifi_ap_set_config() is not called, this API start the AP with 353 * default value, normally you should configure the AP first before calling 354 * this API. 355 * 356 * @return 357 * - BK_OK: succeed 358 * - BK_ERR_WIFI_AP_NOT_CONFIGURED: the WiFi AP is not configured, call bk_wifi_ap_set_config() first. 359 * - others: other errors 360 */ 361 bk_err_t bk_wifi_ap_start(void); 362 363 /** 364 * @brief Stop the BK AP 365 * 366 * @return 367 * - BK_OK: succeed 368 * - BK_WIFI_NOT_INIT: the WiFi is not initialized, call bk_wifi_init() first. 369 * - others: other errors 370 */ 371 bk_err_t bk_wifi_ap_stop(void); 372 373 /** 374 * @brief Config the BK AP 375 * 376 * Usage example: 377 * 378 * wifi_ap_config_t ap_config = WIFI_DEFAULT_AP_CONFIG(); 379 * 380 * os_strncpy(ap_config.ssid, "ssid", WIFI_SSID_STR_LEN); 381 * os_strncpy(ap_config.password, "password", WIFI_PASSWORD_LEN); 382 * BK_LOG_ON_ERR(bk_wifi_ap_set_config(&ap_config)); 383 * 384 * @attention 1. Make sure the reserved field in config is zero, otherwise you may 385 * encounter compatibility issue in future if more config fields are added. 386 * 387 * @param ap_config the AP configuration 388 * 389 * @return 390 * - BK_OK: succeed 391 * - BK_ERR_NULL_PARAM: the ap_config is NULL. 392 * - others: other errors 393 */ 394 bk_err_t bk_wifi_ap_set_config(const wifi_ap_config_t *ap_config); 395 396 /** 397 * @brief Get the configuration of the BK AP. 398 * 399 * @param ap_config store the configuration of BK AP 400 * 401 * @return 402 * - BK_OK: succeed 403 * - BK_ERR_NULL_PARAM: the parameter config is NULL. 404 * - others: other errors 405 */ 406 bk_err_t bk_wifi_ap_get_config(wifi_ap_config_t *ap_config); 407 408 409 /** 410 * @brief Get the STAs connected to BK AP. 411 * 412 * @attention Free stas->sta after usage. 413 * 414 * @param stas store the STA list in BK AP 415 * 416 * @return 417 * - BK_OK: succeed 418 * - others: other errors 419 */ 420 bk_err_t bk_wifi_ap_get_sta_list(wlan_ap_stas_t *stas); 421 422 /** 423 * @brief Calculate softap's Pmk when softap is starts. 424 * 425 * @param ssid softap's ssid 426 * @param pwd softap's pwd 427 * @param pmk softap's pmk 428 * 429 * @return 430 * - BK_OK: succeed 431 * - others: other errors 432 */ 433 bk_err_t bk_wifi_calculate_pmk(const char *ssid, const char *pwd, char *pmk); 434 435 /** 436 * @brief Add softap's Vendor Specific IE when softap is running. 437 * 438 * @attention If you want to add vsie when softap starts, just initialize wifi_ap_config_t 439 * when call bk_wifi_ap_start(). 440 * 441 * @param buf vsie buf 442 * @param len vsie buf len 443 * 444 * @return 445 * - BK_OK: succeed 446 * - others: other errors 447 */ 448 bk_err_t bk_wifi_ap_add_vendor_ie(void *buf, uint8_t len); 449 450 /** 451 * @brief Delete softap's Vendor Specific IE when softap is running. 452 * 453 * @attention If you want to add vsie when softap starts, just initialize wifi_ap_config_t 454 * when call bk_wifi_ap_start(). 455 * 456 * @return 457 * - BK_OK: succeed 458 * - others: other errors 459 */ 460 bk_err_t bk_wifi_ap_del_vendor_ie(void); 461 462 /** 463 * @brief Start the monitor 464 * 465 * @attention 1. When monitor mode is enabled, the scan will not work and 466 * bk_wifi_scan_start() returns BK_ERR_WIFI_MONITOR_IP. 467 * @attention 2. When monitor mode is enabled, the STA connect will not work 468 * and bk_wifi_sta_connect() returns BK_ERR_WIFI_MONITOR_IP. 469 * 470 * @return 471 * - BK_OK: succeed 472 * - others: other errors 473 */ 474 bk_err_t bk_wifi_monitor_start(void); 475 476 477 /** 478 * @brief Stop the monitor 479 * 480 * @return 481 * - BK_OK: succeed 482 * - others: other errors 483 */ 484 bk_err_t bk_wifi_monitor_stop(void); 485 486 /** 487 * @brief Configure the monitor 488 * 489 * @param monitor_config the configuration of monitor 490 * 491 * @return 492 * - BK_OK: succeed 493 * - others: other errors 494 */ 495 bk_err_t bk_wifi_monitor_set_config(const wifi_monitor_config_t *monitor_config); 496 497 /** 498 * @brief Get the configuration of the monitor 499 * 500 * @param monitor_config store the configuration of monitor 501 * 502 * @return 503 * - BK_OK: succeed 504 * - others: other errors 505 */ 506 bk_err_t bk_wifi_monitor_get_config(wifi_monitor_config_t *monitor_config); 507 508 /** 509 * @brief Register the user callback of monitor 510 * 511 * @param monitor_cb monitor callback 512 * 513 * @return 514 * - BK_OK: succeed 515 * - others: other errors 516 */ 517 bk_err_t bk_wifi_monitor_register_cb(const wifi_monitor_cb_t monitor_cb); 518 519 /** 520 * @brief Set monitor channel 521 * 522 * @attention 1. Currently we only support HT20, chan->second should always be 0. 523 * @attention 2. This API is only used for settting monitor channel, NOT for other purpose. 524 * @attention 3. This API directly change the hardware channel, it may impacts BK STA/AP if 525 * the STA or AP interface is started. TODO describe details of the impact. 526 * @attention 4. The channel range can be set is from channel 1 to channel 14, 527 * 528 * @param chan channel of monitor 529 * 530 * @return 531 * - BK_OK: succeed 532 * - others: other errors 533 */ 534 bk_err_t bk_wifi_monitor_set_channel(const wifi_channel_t *chan); 535 536 /** 537 * @brief twt set up 538 * @param setup_type suggest/demand 539 * @param mantissa wake_int_mantissa 540 * @param min_twt min_twt_wake_dur 541 * @return 542 * - BK_OK: succeed 543 * - others: other errors 544 */ 545 bk_err_t bk_wifi_twt_setup(uint8_t setup_type, uint16_t mantissa, uint8_t min_twt); 546 547 /** 548 * @brief twt tear down 549 * 550 * @return 551 * - BK_OK: succeed 552 * - others: other errors 553 */ 554 bk_err_t bk_wifi_twt_teardown(void); 555 556 /** 557 * @brief Set the filter configuration 558 * 559 * The filter is used to configure what kind of management packets can be received 560 * by the filter callback registered by bk_wifi_filter_register_cb(). 561 * 562 * Per the WiFi receiving data path, the management frames are firstly received by 563 * WiFi hardware, then the hardware relays them to WiFi software (WiFi driver). Normally 564 * the hardware receives all management frames in the air, however it don't 565 * relay all of them to WiFi driver (WiFi software), it only relays management frames 566 * necessary to STA or AP or scan or monitor, depends on which interface or function are 567 * enabled. In other word, WiFi driver only receives management frames necessary to them 568 * from hardware. 569 * 570 * When no filter callback is registered, all management frame processing is ended 571 * in WiFi driver unless the filter callback is registered. 572 * 573 * If filter callback is register and if filter_config.rx_all_default_mgmt is set to 1, 574 * then all the management frames received by WiFi driver are relayed to the filter 575 * callback. **Notified that the default management frame types can be received depends 576 * on whether STA or AP or scan or monitor are enabled or not, e.g. when only STA is 577 * enabled, the WiFi driver needs to handle PROBE response, but don't need to handle PROBE 578 * request, so the WiFi driver only receive PROBE response from WiFi hardware**. 579 * 580 * Here is summary about default management frame received by WiFi: 581 * Condition | Default management frame 582 * ----------------|------------------------------------------------------------------- 583 * STA connected | Management frames sent by the connected AP, such as beacon etc. 584 * AP started | Management frames sent by connected STA and probe request etc. 585 * Scan starting | Probe response and beacon frames of all APs. 586 * Monitor started| All kind of management frames 587 * 588 * How about if the filter callback wants to receive more management frame types, 589 * e.g. want to receive PROBE request when only STA is enabled. We can set 590 * filter_config->rx_probe_req to receive PROBE response no matter whether AP is enabled 591 * or NOT. 592 * 593 * Usage example: 594 * 595 * // Only receive management frame default received by WiFi driver 596 * // Equal to the case when bk_wifi_filter_set_config() is not called 597 * wifi_filter_config_t filter_config = WIFI_DEFAULT_FILTER_CONFIG(); 598 * BK_LOG_ON_ERR(bk_wifi_filter_set_config(&filter_config); 599 * 600 * // Receive all beacon and management frames default received by WiFi driver 601 * filter_config.rx_all_beacon = 1; 602 * BK_LOG_ON_ERR(bk_wifi_filter_set_config(&filter_config); 603 * 604 * // Only receive all beacon 605 * filter_config.rx_all_beacon = 1; 606 * filter_config.rx_all_default_mgmt = 0; 607 * BK_LOG_ON_ERR(bk_wifi_filter_set_config(&filter_config); 608 * 609 * @attention 1. If this API is not called, the default filter is to relay all 610 * mamangement frames received by WiFi driver to the filter callback. 611 * @attention 2. If STA is enabled, the WiFi driver only receives beacon from the 612 * connected AP, if scan is enabled or filter_config->rx_all_beacon 613 * is set, the WiFi driver receives beacons of all APs. 614 * 615 * @param filter_config configuration of filter 616 * 617 * @return 618 * - BK_OK: succeed 619 * - others: other errors 620 */ 621 bk_err_t bk_wifi_filter_set_config(const wifi_filter_config_t *filter_config); 622 623 /** 624 * @brief Get the filter configuration 625 * 626 * @param filter_config store configuration of filter 627 * 628 * @return 629 * - BK_OK: succeed 630 * - others: other errors 631 */ 632 bk_err_t bk_wifi_filter_get_config(wifi_filter_config_t *filter_config); 633 634 /** 635 * @brief Register the filter user callback 636 * 637 * @attention 1. If the monitor is enabled, the management packets received by filter 638 * callback can also be received by monitor callback. If this is not what 639 * we want, we can disable filter when enabling monitor, or disable monitor 640 * when enabling filter. 641 * @attention 2. During WiFi scan, the filter also works. 642 * @attention 3. Pass NULL callback or set all fields of filter_config to 0 to disable the 643 * filter. 644 * @attention 4. The memory used to hold the frame buffer and frame_info will be freed 645 * immediately when the callback is returned, so don't relay them to other 646 * task. Make a copy of them and then relay to other task if necessary. 647 * @attention 5. Don't do too much work in the filter callback because it's called in 648 * WiFi driver core thread, otherwise it may impact the WiFi performance. 649 * 650 * @param filter_cb the filter user callback 651 * 652 * @return 653 * - BK_OK: succeed 654 * - others: other errors 655 */ 656 bk_err_t bk_wifi_filter_register_cb(const wifi_filter_cb_t filter_cb); 657 658 /** 659 * @brief Get the MAC of BK STA 660 * 661 * @attention 1. The AP's MAC is derived from the base MAC of the system. 662 * @attention 2. If you want to change the MAC of AP, call bk_set_mac() to set 663 * the base MAC of the system. 664 * 665 * @param mac store the MAC of BK STA 666 * 667 * @return 668 * - BK_OK: succeed 669 * - others: other errors 670 */ 671 672 bk_err_t bk_wifi_sta_get_mac(uint8_t *mac); 673 674 /** 675 * @brief Get the MAC of BK AP 676 * 677 * @attention 1. The AP's MAC is derived from the base MAC of the system. 678 * @attention 2. If you want to change the MAC of AP, call bk_set_mac() to set 679 * the base MAC of the system. 680 * 681 * @param mac store the MAC of BK AP 682 * 683 * @return 684 * - BK_OK: succeed 685 * - others: other errors 686 */ 687 bk_err_t bk_wifi_ap_get_mac(uint8_t *mac); 688 689 /** 690 * @brief Send raw 802.11 frame 691 * 692 * @attention 1. This API can be used in WiFi station, softap, or monitor mode. 693 * @attention 2. Only support to send non-QoS frame. 694 * @attention 3. The frame sequence will be overwritten by WiFi driver. 695 * @attention 4. The API doesn't check the correctness of the raw frame, the 696 * caller need to guarantee the correctness of the frame. 697 * 698 * @param buffer raw 802.11 frame 699 * @param len the length of the 802.11 frame 700 * 701 * @return 702 * - kNoErr: succeed 703 * - otherwise: fail 704 */ 705 bk_err_t bk_wifi_send_raw(uint8_t *buffer, int len); 706 707 /** 708 * @brief configure country info 709 * 710 * @attention 1. The default country is {.cc="CN", .schan=1, .nchan=13, policy=WIFI_COUNTRY_POLICY_AUTO} 711 * @attention 2. When the country policy is WIFI_COUNTRY_POLICY_AUTO, the country info of the AP to which 712 * the station is connected is used. E.g. if the configured country info is {.cc="USA", .schan=1, .nchan=11} 713 * and the country info of the AP to which the station is connected is {.cc="JP", .schan=1, .nchan=14} 714 * then the country info that will be used is {.cc="JP", .schan=1, .nchan=14}. If the station disconnected 715 * from the AP the country info is set back back to the country info of the station automatically, 716 * {.cc="USA", .schan=1, .nchan=11} in the example. 717 * @attention 3. When the country policy is WIFI_COUNTRY_POLICY_MANUAL, always use the configured country info. 718 * @attention 4. When the country info is changed because of configuration or because the station connects to a different 719 * external AP, the country IE in probe response/beacon of the soft-AP is changed also. 720 * @attention 5. The country configuration is not stored into flash 721 * @attention 6. This API doesn't validate the per-country rules, it's up to the user to fill in all fields according to 722 * local regulations. 723 * 724 * @param country the configured country info 725 * 726 * @return 727 * - BK_OK: succeed 728 * - BK_ERR_WIFI_NOT_INIT: WiFi is not initialized 729 * - BK_ERR_PARAM: invalid argument 730 */ 731 bk_err_t bk_wifi_set_country(const wifi_country_t *country); 732 733 /** 734 * @brief get the current country info 735 * 736 * @param country country info 737 * 738 * @return 739 * - BK_OK: succeed 740 * - BK_ERR_WIFI_NOT_INIT: WiFi is not initialized 741 * - BK_ERR_PARAM: invalid argument 742 */ 743 bk_err_t bk_wifi_get_country(wifi_country_t *country); 744 745 /** 746 * @brief enable wifi sta power management 747 * 748 * @return 749 * - BK_OK: on succeed 750 * - others: real error, used for future. 751 */ 752 bk_err_t bk_wifi_sta_pm_enable(void); 753 754 /** 755 * @brief disable wifi sta power management 756 * 757 * @return 758 * - BK_OK: on succeed 759 * - others: real error, used for future. 760 */ 761 bk_err_t bk_wifi_sta_pm_disable(void); 762 763 /** 764 * @brief get current channel ID 765 * 766 * @param basically range from 1~13 767 * 768 * @return 769 * - BK_OK: on succeed 770 * - others: real error, used for future. 771 */ 772 bk_err_t bk_wifi_get_channel(void); 773 774 /** 775 * @brief Set Wi-Fi MAC addresses. 776 * 777 * The given MAC address will become the station MAC address.The AP MAC address 778 * (i.e BSSID) will be the same MAC address but with the local bit set. 779 * 780 * @param mac system mac 781 782 * @usage example: 783 * mac c8478cxxyyzz 784 * txevm -e 2 //if needed 785 * 786 * @return 787 788 * - BK_OK: on succeed 789 * - others: real error, used for future. 790 * 791 * @note on some platforms the change of MAC address can only take effect after reboot. 792 */ 793 bk_err_t bk_wifi_set_mac_address(char *mac); 794 795 /** 796 * @brief Get Wi-Fi Calibration status. 797 * 798 * @return 799 * - BK_OK: on succeed 800 * - others: real error, used for future. 801 */ 802 bk_err_t bk_wifi_manual_cal_rfcali_status(void); 803 804 /** 805 * @brief Register a cb of probe request for ap. 806 * 807 * @param cb callback function of probe request to register 808 * 809 */ 810 bk_err_t bk_wifi_ap_vif_probe_req_frame_cb_register(void *cb); 811 812 /** 813 * @brief Set listen interval. 814 * 815 * @param any value is acceptable,but 1, 3, 10 is recommended. 816 * 817 * @return 818 * -BK_OK: on success 819 * -others:real error, used for future. 820 * 821 */ 822 bk_err_t bk_wifi_send_listen_interval_req(uint8_t interval); 823 824 /** 825 * @brief Get wifi statistic info. 826 * 827 * @param get wifi info from fw 828 * 829 * @return 830 * -BK_OK: on success 831 * -others:real error, used for future. 832 */ 833 bk_err_t bk_wifi_get_statistic_info(wifi_statistics_info_t *wifiinfo); 834 835 /** 836 * @} 837 */ 838 839 #ifdef __cplusplus 840 } 841 #endif 842