1 /* 2 * Copyright (c) 2024 Nordic Semiconductor ASA 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 /** @file 8 * 9 * @addtogroup nrf_wifi_api FMAC API 10 * @{ 11 * 12 * @brief Header containing declarations for utility functions for 13 * FMAC IF Layer of the Wi-Fi driver. 14 */ 15 16 #ifndef __FMAC_STRUCTS_H__ 17 #define __FMAC_STRUCTS_H__ 18 19 #include "osal_api.h" 20 #include "host_rpu_umac_if.h" 21 #include "common/fmac_structs_common.h" 22 23 #define MAX_PEERS 5 24 #define MAX_SW_PEERS (MAX_PEERS + 1) 25 #define NRF_WIFI_AC_TWT_PRIORITY_EMERGENCY 0xFF 26 #define NRF_WIFI_MAGIC_NUM_RAWTX 0x12345678 27 28 29 /** 30 * @brief WLAN access categories. 31 * 32 */ 33 enum nrf_wifi_fmac_ac { 34 /** Background access category. */ 35 NRF_WIFI_FMAC_AC_BK, 36 /** Best-effort access category. */ 37 NRF_WIFI_FMAC_AC_BE, 38 /** Video access category. */ 39 NRF_WIFI_FMAC_AC_VI, 40 /** Voice access category. */ 41 NRF_WIFI_FMAC_AC_VO, 42 /** Multicast access category. */ 43 NRF_WIFI_FMAC_AC_MC, 44 /** Maximum number of WLAN access categories. */ 45 NRF_WIFI_FMAC_AC_MAX 46 }; 47 48 49 /** 50 * @brief The operational state of an interface. 51 * 52 */ 53 enum nrf_wifi_fmac_if_op_state { 54 /** Interface is non-operational. */ 55 NRF_WIFI_FMAC_IF_OP_STATE_DOWN, 56 /** Interface is operational. */ 57 NRF_WIFI_FMAC_IF_OP_STATE_UP, 58 /** Invalid value. Used for error checks. */ 59 NRF_WIFI_FMAC_IF_OP_STATE_INVALID 60 }; 61 62 63 /** 64 * @brief The carrier state of an interface. 65 * 66 */ 67 enum nrf_wifi_fmac_if_carr_state { 68 /** Interface is not ready. */ 69 NRF_WIFI_FMAC_IF_CARR_STATE_OFF, 70 /** Interface is ready. */ 71 NRF_WIFI_FMAC_IF_CARR_STATE_ON, 72 /** Invalid value. Used for error checks. */ 73 NRF_WIFI_FMAC_IF_CARR_STATE_INVALID 74 }; 75 76 #if defined(NRF70_RAW_DATA_RX) || defined(NRF70_PROMISC_DATA_RX) 77 /** 78 * @brief Structure to hold raw rx packet information. 79 * 80 * This structure holds the information to be sent to higher 81 * layers on receive of a raw frame. 82 */ 83 struct raw_rx_pkt_header { 84 /** Frequency on which this packet received. */ 85 unsigned short frequency; 86 /** Signal strength of received packet. */ 87 signed short signal; 88 /** Received packet type */ 89 unsigned char rate_flags; 90 /** Data rate of the packet (MCS or Legacy). */ 91 unsigned char rate; 92 }; 93 #endif /* NRF70_RAW_DATA_RX || NRF70_PROMISC_DATA_RX */ 94 95 /** 96 * @brief Callback functions to be invoked by UMAC IF layer when a particular event occurs. 97 * 98 * This structure contains function pointers to all the callback functions that 99 * the UMAC IF layer needs to invoke for various events. 100 */ 101 struct nrf_wifi_fmac_callbk_fns { 102 /** Callback function to be called when RPU recovery is required. */ 103 void (*rpu_recovery_callbk_fn)(void *os_vif_ctx, 104 void *event_data, 105 unsigned int event_len); 106 107 /** Callback function to be called when a scan is started. */ 108 void (*scan_start_callbk_fn)(void *os_vif_ctx, 109 struct nrf_wifi_umac_event_trigger_scan *scan_start_event, 110 unsigned int event_len); 111 112 /** Callback function to be called when a scan is done. */ 113 void (*scan_done_callbk_fn)(void *os_vif_ctx, 114 struct nrf_wifi_umac_event_trigger_scan *scan_done_event, 115 unsigned int event_len); 116 117 /** Callback function to be called when a scan is aborted. */ 118 void (*scan_abort_callbk_fn)(void *os_vif_ctx, 119 struct nrf_wifi_umac_event_trigger_scan *scan_done_event, 120 unsigned int event_len); 121 122 /** Callback function to be called when a scan result is received. */ 123 void (*scan_res_callbk_fn)(void *os_vif_ctx, 124 struct nrf_wifi_umac_event_new_scan_results *scan_res, 125 unsigned int event_len, 126 bool more_res); 127 128 /** Callback function to be called when a display scan result is received. */ 129 void (*disp_scan_res_callbk_fn)(void *os_vif_ctx, 130 struct nrf_wifi_umac_event_new_scan_display_results *scan_res, 131 unsigned int event_len, 132 bool more_res); 133 134 #if defined(WIFI_MGMT_RAW_SCAN_RESULTS) || defined(__DOXYGEN__) 135 /** Callback function to be called when a beacon/probe response is received. */ 136 void (*rx_bcn_prb_resp_callbk_fn)(void *os_vif_ctx, 137 void *frm, 138 unsigned short frequency, 139 signed short signal); 140 #endif /* WIFI_MGMT_RAW_SCAN_RESULTS */ 141 142 /** Callback function to be called when a get regulatory response is received. */ 143 void (*event_get_reg)(void *if_priv, 144 struct nrf_wifi_reg *get_reg, 145 unsigned int event_len); 146 #if defined(NRF70_STA_MODE) || defined(__DOXYGEN__) 147 /** Callback function to be called when an interface association state changes. */ 148 enum nrf_wifi_status (*if_carr_state_chg_callbk_fn)(void *os_vif_ctx, 149 enum nrf_wifi_fmac_if_carr_state cs); 150 151 /** Callback function to be called when a frame is received. */ 152 void (*rx_frm_callbk_fn)(void *os_vif_ctx, 153 void *frm); 154 155 /** Callback function to be called when an authentication response is received. */ 156 void (*auth_resp_callbk_fn)(void *os_vif_ctx, 157 struct nrf_wifi_umac_event_mlme *auth_resp_event, 158 unsigned int event_len); 159 160 /** Callback function to be called when an association response is received. */ 161 void (*assoc_resp_callbk_fn)(void *os_vif_ctx, 162 struct nrf_wifi_umac_event_mlme *assoc_resp_event, 163 unsigned int event_len); 164 165 /** Callback function to be called when a deauthentication frame is received. */ 166 void (*deauth_callbk_fn)(void *os_vif_ctx, 167 struct nrf_wifi_umac_event_mlme *deauth_event, 168 unsigned int event_len); 169 170 /** Callback function to be called when a disassociation frame is received. */ 171 void (*disassoc_callbk_fn)(void *os_vif_ctx, 172 struct nrf_wifi_umac_event_mlme *disassoc_event, 173 unsigned int event_len); 174 175 /** Callback function to be called when a management frame is received. */ 176 void (*mgmt_rx_callbk_fn)(void *os_vif_ctx, 177 struct nrf_wifi_umac_event_mlme *mgmt_rx_event, 178 unsigned int event_len); 179 180 /** Callback function to be called when an unprotected management frame is received. */ 181 void (*unprot_mlme_mgmt_rx_callbk_fn)(void *os_vif_ctx, 182 struct nrf_wifi_umac_event_mlme *unprot_mlme_event, 183 unsigned int event_len); 184 185 /** Callback function to be called when a get TX power response is received. */ 186 void (*tx_pwr_get_callbk_fn)(void *os_vif_ctx, 187 struct nrf_wifi_umac_event_get_tx_power *info, 188 unsigned int event_len); 189 190 /** Callback function to be called when a get channel response is received. */ 191 void (*chnl_get_callbk_fn)(void *os_vif_ctx, 192 struct nrf_wifi_umac_event_get_channel *info, 193 unsigned int event_len); 194 195 /** Callback function to be called when a cookie response is received. */ 196 void (*cookie_rsp_callbk_fn)(void *os_vif_ctx, 197 struct nrf_wifi_umac_event_cookie_rsp *cookie_rsp, 198 unsigned int event_len); 199 200 /** Callback function to be called when a TX status is received. */ 201 void (*tx_status_callbk_fn)(void *os_vif_ctx, 202 struct nrf_wifi_umac_event_mlme *tx_status_event, 203 unsigned int event_len); 204 205 /** Callback function to be called when a set interface response is received. */ 206 void (*set_if_callbk_fn)(void *os_vif_ctx, 207 struct nrf_wifi_umac_event_set_interface *set_if_event, 208 unsigned int event_len); 209 210 /** Callback function to be called when a remain on channel response is received. */ 211 void (*roc_callbk_fn)(void *os_vif_ctx, 212 struct nrf_wifi_event_remain_on_channel *roc_event, 213 unsigned int event_len); 214 215 /** Callback function to be called when a remain on channel cancel response is received. */ 216 void (*roc_cancel_callbk_fn)(void *os_vif_ctx, 217 struct nrf_wifi_event_remain_on_channel *roc_cancel_event, 218 unsigned int event_len); 219 220 /** Callback function to be called when a get station response is received. */ 221 void (*get_station_callbk_fn)(void *os_vif_ctx, 222 struct nrf_wifi_umac_event_new_station *info, 223 unsigned int event_len); 224 225 /** Callback function to be called when a get interface response is received. */ 226 void (*get_interface_callbk_fn)(void *os_vif_ctx, 227 struct nrf_wifi_interface_info *info, 228 unsigned int event_len); 229 230 /** Callback function to be called when a management TX status is received. */ 231 void (*mgmt_tx_status)(void *if_priv, 232 struct nrf_wifi_umac_event_mlme *mlme_event, 233 unsigned int event_len); 234 235 /** Callback function to be called when a TWT configuration response is received. */ 236 void (*twt_config_callbk_fn)(void *if_priv, 237 struct nrf_wifi_umac_cmd_config_twt *twt_config_event_info, 238 unsigned int event_len); 239 240 /** Callback function to be called when a TWT teardown response is received. */ 241 void (*twt_teardown_callbk_fn)(void *if_priv, 242 struct nrf_wifi_umac_cmd_teardown_twt *twt_teardown_event_info, 243 unsigned int event_len); 244 245 /** Callback function to be called when a get wiphy response is received. */ 246 void (*event_get_wiphy)(void *if_priv, 247 struct nrf_wifi_event_get_wiphy *get_wiphy, 248 unsigned int event_len); 249 250 /** Callback function to be called when a TWT sleep response is received. */ 251 void (*twt_sleep_callbk_fn)(void *if_priv, 252 struct nrf_wifi_umac_event_twt_sleep *twt_sleep_event_info, 253 unsigned int event_len); 254 255 /** Callback function to be called when a get power save information 256 * response is received. 257 */ 258 void (*event_get_ps_info)(void *if_priv, 259 struct nrf_wifi_umac_event_power_save_info *get_ps_config, 260 unsigned int event_len); 261 262 /** Callback function to be called when a get connection info response is received. */ 263 void (*get_conn_info_callbk_fn)(void *os_vif_ctx, 264 struct nrf_wifi_umac_event_conn_info *info, 265 unsigned int event_len); 266 267 /** Callback function to be called when rssi is to be processed from the received frame. */ 268 void (*process_rssi_from_rx)(void *os_vif_ctx, 269 signed short signal); 270 #endif /* NRF70_STA_MODE */ 271 #if defined(NRF70_RAW_DATA_RX) || defined(NRF70_PROMISC_DATA_RX) 272 void (*sniffer_callbk_fn)(void *os_vif_ctx, 273 void *frm, 274 struct raw_rx_pkt_header *, 275 bool pkt_free); 276 #endif /* NRF70_RAW_DATA_RX || NRF70_PROMISC_DATA_RX */ 277 void (*reg_change_callbk_fn)(void *os_vif_ctx, 278 struct nrf_wifi_event_regulatory_change *reg_change, 279 unsigned int event_len); 280 }; 281 282 #if defined(NRF70_STA_MODE) || defined(__DOXYGEN__) 283 /** 284 * @brief The TWT sleep state of device. 285 * 286 */ 287 enum nrf_wifi_fmac_twt_state { 288 /** RPU in TWT sleep state. */ 289 NRF_WIFI_FMAC_TWT_STATE_SLEEP, 290 /** RPU in TWT awake state. */ 291 NRF_WIFI_FMAC_TWT_STATE_AWAKE 292 }; 293 294 /** 295 * @brief Structure to hold peer context information. 296 * 297 * This structure holds context information for a peer that the RPU is 298 * connected with. 299 */ 300 struct peers_info { 301 /** Peer ID. */ 302 int peer_id; 303 /** VIF index. */ 304 unsigned char if_idx; 305 /** Power save state. */ 306 unsigned char ps_state; 307 /** Legacy or HT/VHT/HE. */ 308 unsigned char is_legacy; 309 /** QoS supported. */ 310 unsigned char qos_supported; 311 /** Pending queue bitmap. */ 312 unsigned char pend_q_bmp __NRF_WIFI_ALIGN_4; 313 /** Receiver address, this is programmed to nRF70, so, should be aligned to 4. */ 314 unsigned char ra_addr[NRF_WIFI_ETH_ADDR_LEN] __NRF_WIFI_ALIGN_4; 315 /** Pairwise cipher. */ 316 unsigned int pairwise_cipher; 317 /** 802.11 power save token count. */ 318 int ps_token_count; 319 }; 320 321 /** 322 * @brief Structure to hold transmit path context information. 323 * 324 */ 325 struct tx_config { 326 /** Lock used to make code portions in the TX path atomic. */ 327 void *tx_lock; 328 /** Context information about peers that the RPU firmware is connected to. */ 329 struct peers_info peers[MAX_SW_PEERS]; 330 /** Coalesce count of TX frames. */ 331 unsigned int *send_pkt_coalesce_count_p; 332 /** per-peer/per-AC Queue for frames waiting to be passed to the RPU firmware for TX. */ 333 void *data_pending_txq[MAX_SW_PEERS][NRF_WIFI_FMAC_AC_MAX]; 334 /** Queue for peers which have woken up from 802.11 power save. */ 335 void *wakeup_client_q; 336 /** Used to store tx descs(buff pool ids). */ 337 unsigned long *buf_pool_bmp_p; 338 /** TX descriptors which have been queued to the RPU firmware. */ 339 unsigned int outstanding_descs[NRF_WIFI_FMAC_AC_MAX]; 340 /** Peer who will be get the next opportunity for TX. */ 341 unsigned int curr_peer_opp[NRF_WIFI_FMAC_AC_MAX]; 342 /** Access category which will get the next spare descriptor. */ 343 unsigned int next_spare_desc_ac; 344 /** Frame context information. */ 345 struct tx_pkt_info *pkt_info_p; 346 /** Map for the spare descriptor queues 347 * - First four bits : Spare desc1 queue number, 348 * - Second four bits: Spare desc2 queue number. 349 */ 350 unsigned int spare_desc_queue_map; 351 #if defined(NRF70_TX_DONE_WQ_ENABLED) || defined(__DOXYGEN__) 352 /** Queue for TX done tasklet. */ 353 void *tx_done_tasklet_event_q; 354 #endif /* NRF70_TX_DONE_WQ_ENABLED */ 355 }; 356 #endif /* NRF70_STA_MODE */ 357 358 /** 359 * @brief Structure to hold context information for the UMAC IF layer. 360 * 361 * This structure maintains the context information necessary for the 362 * operation of the UMAC IF layer. 363 */ 364 struct nrf_wifi_sys_fmac_priv { 365 /** Callback functions to be called on various events. */ 366 struct nrf_wifi_fmac_callbk_fns callbk_fns; 367 /** Data path configuration parameters. */ 368 struct nrf_wifi_data_config_params data_config; 369 /** RX buffer pool configuration data. */ 370 struct rx_buf_pool_params rx_buf_pools[MAX_NUM_OF_RX_QUEUES]; 371 /** Starting RX descriptor number for a RX buffer pool. */ 372 unsigned int rx_desc[MAX_NUM_OF_RX_QUEUES]; 373 /** Maximum number of host buffers needed for RX frames. */ 374 unsigned int num_rx_bufs; 375 #if defined(NRF70_STA_MODE) 376 /** Maximum number of tokens available for TX. */ 377 unsigned char num_tx_tokens; 378 /** Maximum number of TX tokens available reserved per AC. */ 379 unsigned char num_tx_tokens_per_ac; 380 /** Number of spare tokens (common to all ACs) available for TX. */ 381 unsigned char num_tx_tokens_spare; 382 /** Maximum supported AMPDU length per token. */ 383 unsigned int max_ampdu_len_per_token; 384 /** Available (remaining) AMPDU length per token. */ 385 unsigned int avail_ampdu_len_per_token; 386 #endif /* NRF70_STA_MODE */ 387 }; 388 389 #ifdef NRF70_RAW_DATA_TX 390 391 /** 392 * @brief Transmit modes for raw packets. 393 * 394 */ 395 enum nrf_wifi_fmac_rawtx_mode { 396 /** Legacy mode. */ 397 NRF_WIFI_FMAC_RAWTX_MODE_LEGACY, 398 /** HT mode. */ 399 NRF_WIFI_FMAC_RAWTX_MODE_HT, 400 /** VHT mode. */ 401 NRF_WIFI_FMAC_RAWTX_MODE_VHT, 402 /** HE SU mode. */ 403 NRF_WIFI_FMAC_RAWTX_MODE_HE_SU, 404 /** HE ER SU mode. */ 405 NRF_WIFI_FMAC_RAWTX_MODE_HE_ER_SU, 406 /** HE TB mode. */ 407 NRF_WIFI_FMAC_RAWTX_MODE_HE_TB, 408 /** Throughput max. */ 409 NRF_WIFI_FMAC_RAWTX_MODE_MAX 410 }; 411 412 /** 413 * @brief Structure to hold raw tx packet information. 414 * 415 * This structure holds the information sent by higher 416 * layers to transmit a raw frame. 417 */ 418 struct raw_tx_pkt_header { 419 /** magic number to identify a raw packet. */ 420 unsigned int magic_num; 421 /** Data rate at which packet is to be transmitted. */ 422 unsigned char data_rate; 423 /** Packet length. */ 424 unsigned short packet_length; 425 /** Mode describing if packet is VHT, HT, HE or Legacy @ref nrf_wifi_fmac_mode. */ 426 unsigned char tx_mode; 427 /** Wi-Fi access category mapping for packet @ref nrf_wifi_fmac_ac. */ 428 unsigned char queue; 429 /** Flag indicating raw packet transmission. */ 430 unsigned char raw_tx_flag; 431 }; 432 433 /** 434 * @brief Structure to hold raw packet transmit statistics. 435 * 436 * This structure holds the raw packet 437 * transmit statistics. 438 */ 439 struct raw_tx_stats { 440 /** Total number of raw packets sent. */ 441 unsigned int raw_pkts_sent; 442 /** Count of successful raw packets sent. */ 443 unsigned int raw_pkt_send_failure; 444 /** Count of un-successful raw packets sent. */ 445 unsigned int raw_pkt_send_success; 446 }; 447 #endif /* NRF70_RAW_DATA_TX */ 448 449 /** 450 * @brief Structure to hold per device context information for the UMAC IF layer. 451 * 452 * This structure maintains the context information necessary for 453 * a single instance of a FullMAC-based RPU. 454 */ 455 struct nrf_wifi_sys_fmac_dev_ctx { 456 /** Array of pointers to virtual interfaces created on this device. */ 457 struct nrf_wifi_fmac_vif_ctx *vif_ctx[MAX_NUM_VIFS]; 458 #if defined(NRF70_RX_WQ_ENABLED) 459 /** Tasklet for RX. */ 460 void *rx_tasklet; 461 /** Queue for RX tasklet. */ 462 void *rx_tasklet_event_q; 463 #endif /* NRF70_RX_WQ_ENABLED */ 464 /** Host statistics. */ 465 struct rpu_host_stats host_stats; 466 /** Number of interfaces in STA mode. */ 467 unsigned char num_sta; 468 /** Number of interfaces in AP mode. */ 469 unsigned char num_ap; 470 /** Queue for storing mapping info of RX buffers. */ 471 struct nrf_wifi_fmac_buf_map_info *rx_buf_info; 472 #if defined(NRF70_STA_MODE) 473 /** Queue for storing mapping info of TX buffers. */ 474 struct nrf_wifi_fmac_buf_map_info *tx_buf_info; 475 /** Context information related to TX path. */ 476 struct tx_config tx_config; 477 /** TWT state of the RPU. */ 478 enum nrf_wifi_fmac_twt_state twt_sleep_status; 479 #if defined(NRF70_TX_DONE_WQ_ENABLED) 480 /** Tasklet for TX done. */ 481 void *tx_done_tasklet; 482 #endif /* NRF70_TX_DONE_WQ_ENABLED */ 483 #endif /* NRF70_STA_MODE */ 484 #ifdef NRF70_RAW_DATA_TX 485 struct raw_tx_pkt_header raw_tx_config; 486 struct raw_tx_stats raw_pkt_stats; 487 #endif /* NRF70_RAW_DATA_TX */ 488 }; 489 490 /** 491 * @brief Structure to hold per VIF context information for the UMAC IF layer. 492 * 493 * This structure maintains the context information necessary for 494 * a single instance of an VIF. 495 */ 496 struct nrf_wifi_fmac_vif_ctx { 497 /** Handle to the FMAC IF abstraction layer. */ 498 struct nrf_wifi_fmac_dev_ctx *fmac_dev_ctx; 499 /** Handle to the OS abstraction layer. */ 500 void *os_vif_ctx; 501 /** MAC address of the VIF. */ 502 char mac_addr[NRF_WIFI_ETH_ADDR_LEN]; 503 /** Groupwise cipher being used on this VIF. */ 504 int groupwise_cipher; 505 /** Interface flags related to this VIF. */ 506 bool ifflags; 507 /** Interface type of this VIF. */ 508 int if_type; 509 /** BSSID of the AP to which this VIF is connected (applicable only in STA mode). */ 510 unsigned char bssid[NRF_WIFI_ETH_ADDR_LEN]; 511 /** Mode setting for the current VIF */ 512 unsigned char mode; 513 #if defined(NRF70_RAW_DATA_TX) || defined(NRF70_RAW_DATA_RX) 514 /** Channel setting for the current VIF */ 515 unsigned char channel; 516 /** TX injection mode setting */ 517 bool txinjection_mode; 518 #endif /* NRF70_RAW_DATA_TX || NRF70_RAW_DATA_RX */ 519 #if defined(NRF70_RAW_DATA_RX) || defined(NRF70_PROMISC_DATA_RX) 520 /** Filter setting for Monitor and Promiscuous modes */ 521 unsigned char packet_filter; 522 #endif /* NRF70_RAW_DATA_RX || NRF70_PROMISC_DATA_RX */ 523 #ifdef NRF70_PROMISC_DATA_RX 524 /** Promiscuous mode setting */ 525 bool promisc_mode; 526 #endif /* NRF70_PROMISC_DATA_RX */ 527 }; 528 529 /** 530 * @brief Structure to hold TX/RX buffer pool configuration data. 531 * 532 */ 533 struct nrf_wifi_fmac_buf_map_info { 534 /** Flag indicating whether the buffer is mapped or not. */ 535 bool mapped; 536 /** The number of words in the buffer. */ 537 unsigned long nwb; 538 }; 539 540 541 /** 542 * @brief - Structure to hold per device host and firmware statistics. 543 * 544 */ 545 struct rpu_sys_op_stats { 546 /** Host statistics. */ 547 struct rpu_host_stats host; 548 /** Firmware statistics. */ 549 struct rpu_sys_fw_stats fw; 550 }; 551 552 /** 553 * @} 554 */ 555 #endif /* __FMAC_STRUCTS_H__ */ 556
