1 #include "wifi_hal.h" 2 3 #ifndef __WIFI_HAL_LOGGER_H 4 #define __WIFI_HAL_LOGGER_H 5 6 #ifdef __cplusplus 7 extern "C" 8 { 9 #endif /* __cplusplus */ 10 11 #define LOGGER_MAJOR_VERSION 1 12 #define LOGGER_MINOR_VERSION 0 13 #define LOGGER_MICRO_VERSION 0 14 15 16 17 /** 18 * WiFi logger life cycle is as follow: 19 * 20 * - At initialization time, framework will call wifi_get_ring_buffers_status 21 * so as to obtain the names and list of supported buffers. 22 * - When WiFi operation start framework will call wifi_start_logging 23 * so as to trigger log collection. 24 * - Developper UI will provide an option to the user, so as it can set the verbose level 25 * of individual buffer as reported by wifi_get_ring_buffers_status. 26 * - During wifi operations, driver will periodically report per ring data to framework 27 * by invoking the on_ring_buffer_data call back. 28 * - when capturing a bug report, framework will indicate to driver that all the data 29 * has to be uploaded, urgently, by calling wifi_get_ring_data. 30 * 31 * The data uploaded by driver will be stored by framework in separate files, with one stream 32 * of file per ring. 33 * Framework will store the files in pcapng format, allowing for easy merging and parsing 34 * with network analyzer tools. 35 */ 36 37 38 typedef int wifi_ring_buffer_id; 39 40 #define PER_PACKET_ENTRY_FLAGS_DIRECTION_TX 1 // 0: TX, 1: RX 41 #define PER_PACKET_ENTRY_FLAGS_TX_SUCCESS 2 // whether packet was transmitted or 42 // received/decrypted successfully 43 #define PER_PACKET_ENTRY_FLAGS_80211_HEADER 4 // has full 802.11 header, else has 802.3 header 44 #define PER_PACKET_ENTRY_FLAGS_PROTECTED 8 // whether packet was encrypted 45 46 typedef struct { 47 u8 flags; 48 u8 tid; // transmit or received tid 49 u16 MCS; // modulation and bandwidth 50 u8 rssi; // TX: RSSI of ACK for that packet 51 // RX: RSSI of packet 52 u8 num_retries; // number of attempted retries 53 u16 last_transmit_rate; // last transmit rate in .5 mbps 54 u16 link_layer_transmit_sequence; // transmit/reeive sequence for that MPDU packet 55 u64 firmware_entry_timestamp; // TX: firmware timestamp (us) when packet is queued within 56 // firmware buffer for SDIO/HSIC or into PCIe buffer 57 // RX: firmware receive timestamp 58 u64 start_contention_timestamp; // firmware timestamp (us) when packet start contending for the 59 // medium for the first time, at head of its AC queue, 60 // or as part of an MPDU or A-MPDU. This timestamp is 61 // not updated for each retry, only the first transmit attempt. 62 u64 transmit_success_timestamp; // fimrware timestamp (us) when packet is successfully 63 // transmitted or aborted because it has exhausted 64 // its maximum number of retries. 65 u8 data[0]; // packet data. The length of packet data is determined by the entry_size field of 66 // the wifi_ring_buffer_entry structure. It is expected that first bytes of the 67 // packet, or packet headers only (up to TCP or RTP/UDP headers) 68 // will be copied into the ring 69 } __attribute__((packed)) wifi_ring_per_packet_status_entry; 70 71 72 /* Below events refer to the wifi_connectivity_event ring and shall be supported */ 73 #define WIFI_EVENT_ASSOCIATION_REQUESTED 0 // driver receives association command from kernel 74 #define WIFI_EVENT_AUTH_COMPLETE 1 75 #define WIFI_EVENT_ASSOC_COMPLETE 2 76 #define WIFI_EVENT_FW_AUTH_STARTED 3 // fw event indicating auth frames are sent 77 #define WIFI_EVENT_FW_ASSOC_STARTED 4 // fw event indicating assoc frames are sent 78 #define WIFI_EVENT_FW_RE_ASSOC_STARTED 5 // fw event indicating reassoc frames are sent 79 #define WIFI_EVENT_DRIVER_SCAN_REQUESTED 6 80 #define WIFI_EVENT_DRIVER_SCAN_RESULT_FOUND 7 81 #define WIFI_EVENT_DRIVER_SCAN_COMPLETE 8 82 #define WIFI_EVENT_G_SCAN_STARTED 9 83 #define WIFI_EVENT_G_SCAN_COMPLETE 10 84 #define WIFI_EVENT_DISASSOCIATION_REQUESTED 11 85 #define WIFI_EVENT_RE_ASSOCIATION_REQUESTED 12 86 #define WIFI_EVENT_ROAM_REQUESTED 13 87 #define WIFI_EVENT_BEACON_RECEIVED 14 // received beacon from AP (event enabled 88 // only in verbose mode) 89 #define WIFI_EVENT_ROAM_SCAN_STARTED 15 // firmware has triggered a roam scan (not g-scan) 90 #define WIFI_EVENT_ROAM_SCAN_COMPLETE 16 // firmware has completed a roam scan (not g-scan) 91 #define WIFI_EVENT_ROAM_SEARCH_STARTED 17 // firmware has started searching for roam 92 // candidates (with reason =xx) 93 #define WIFI_EVENT_ROAM_SEARCH_STOPPED 18 // firmware has stopped searching for roam 94 // candidates (with reason =xx) 95 #define WIFI_EVENT_CHANNEL_SWITCH_ANOUNCEMENT 20 // received channel switch anouncement from AP 96 #define WIFI_EVENT_FW_EAPOL_FRAME_TRANSMIT_START 21 // fw start transmit eapol frame, with 97 // EAPOL index 1-4 98 #define WIFI_EVENT_FW_EAPOL_FRAME_TRANSMIT_STOP 22 // fw gives up eapol frame, with rate, 99 // success/failure and number retries 100 #define WIFI_EVENT_DRIVER_EAPOL_FRAME_TRANSMIT_REQUESTED 23 // kernel queue EAPOL for transmission 101 // in driver with EAPOL index 1-4 102 #define WIFI_EVENT_FW_EAPOL_FRAME_RECEIVED 24 // with rate, regardless of the fact that 103 // EAPOL frame is accepted or rejected by fw 104 #define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has 105 // received EAPOL frame and will queue it up 106 // to wpa_supplicant 107 #define WIFI_EVENT_BLOCK_ACK_NEGOTIATION_COMPLETE 27 // with success/failure, parameters 108 #define WIFI_EVENT_BT_COEX_BT_SCO_START 28 109 #define WIFI_EVENT_BT_COEX_BT_SCO_STOP 29 110 #define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc., when BT starts transmiting 111 // twice per BT slot 112 #define WIFI_EVENT_BT_COEX_BT_SCAN_STOP 31 113 #define WIFI_EVENT_BT_COEX_BT_HID_START 32 114 #define WIFI_EVENT_BT_COEX_BT_HID_STOP 33 115 #define WIFI_EVENT_ROAM_AUTH_STARTED 34 // fw sends auth frame in roaming to next candidate 116 #define WIFI_EVENT_ROAM_AUTH_COMPLETE 35 // fw receive auth confirm from ap 117 #define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in 118 // roaming to next candidate 119 #define WIFI_EVENT_ROAM_ASSOC_COMPLETE 37 // firmware receive assoc/reassoc confirm from ap 120 #define WIFI_EVENT_G_SCAN_STOP 38 // firmware sends stop G_SCAN 121 #define WIFI_EVENT_G_SCAN_CYCLE_STARTED 39 // firmware indicates G_SCAN scan cycle started 122 #define WIFI_EVENT_G_SCAN_CYCLE_COMPLETED 40 // firmware indicates G_SCAN scan cycle completed 123 #define WIFI_EVENT_G_SCAN_BUCKET_STARTED 41 // firmware indicates G_SCAN scan start 124 // for a particular bucket 125 #define WIFI_EVENT_G_SCAN_BUCKET_COMPLETED 42 // firmware indicates G_SCAN scan completed for 126 // for a particular bucket 127 #define WIFI_EVENT_G_SCAN_RESULTS_AVAILABLE 43 // Event received from firmware about G_SCAN scan 128 // results being available 129 #define WIFI_EVENT_G_SCAN_CAPABILITIES 44 // Event received from firmware with G_SCAN 130 // capabilities 131 #define WIFI_EVENT_ROAM_CANDIDATE_FOUND 45 // Event received from firmware when eligible 132 // candidate is found 133 #define WIFI_EVENT_ROAM_SCAN_CONFIG 46 // Event received from firmware when roam scan 134 // configuration gets enabled or disabled 135 #define WIFI_EVENT_AUTH_TIMEOUT 47 // firmware/driver timed out authentication 136 #define WIFI_EVENT_ASSOC_TIMEOUT 48 // firmware/driver timed out association 137 #define WIFI_EVENT_MEM_ALLOC_FAILURE 49 // firmware/driver encountered allocation failure 138 #define WIFI_EVENT_DRIVER_PNO_ADD 50 // driver added a PNO network in firmware 139 #define WIFI_EVENT_DRIVER_PNO_REMOVE 51 // driver removed a PNO network in firmware 140 #define WIFI_EVENT_DRIVER_PNO_NETWORK_FOUND 52 // driver received PNO networks 141 // found indication from firmware 142 #define WIFI_EVENT_DRIVER_PNO_SCAN_REQUESTED 53 // driver triggered a scan for PNO networks 143 #define WIFI_EVENT_DRIVER_PNO_SCAN_RESULT_FOUND 54 // driver received scan results 144 // of PNO networks 145 #define WIFI_EVENT_DRIVER_PNO_SCAN_COMPLETE 55 // driver updated scan results from 146 // PNO networks to cfg80211 147 148 /** 149 * Parameters of wifi logger events are TLVs 150 * Event parameters tags are defined as: 151 */ 152 #define WIFI_TAG_VENDOR_SPECIFIC 0 // take a byte stream as parameter 153 #define WIFI_TAG_BSSID 1 // takes a 6 bytes MAC address as parameter 154 #define WIFI_TAG_ADDR 2 // takes a 6 bytes MAC address as parameter 155 #define WIFI_TAG_SSID 3 // takes a 32 bytes SSID address as parameter 156 #define WIFI_TAG_STATUS 4 // takes an integer as parameter 157 #define WIFI_TAG_CHANNEL_SPEC 5 // takes one or more wifi_channel_spec as parameter 158 #define WIFI_TAG_WAKE_LOCK_EVENT 6 // takes a wake_lock_event struct as parameter 159 #define WIFI_TAG_ADDR1 7 // takes a 6 bytes MAC address as parameter 160 #define WIFI_TAG_ADDR2 8 // takes a 6 bytes MAC address as parameter 161 #define WIFI_TAG_ADDR3 9 // takes a 6 bytes MAC address as parameter 162 #define WIFI_TAG_ADDR4 10 // takes a 6 bytes MAC address as parameter 163 #define WIFI_TAG_TSF 11 // take a 64 bits TSF value as parameter 164 #define WIFI_TAG_IE 12 // take one or more specific 802.11 IEs parameter, 165 // IEs are in turn indicated in TLV format as per 166 // 802.11 spec 167 #define WIFI_TAG_INTERFACE 13 // take interface name as parameter 168 #define WIFI_TAG_REASON_CODE 14 // take a reason code as per 802.11 as parameter 169 #define WIFI_TAG_RATE_MBPS 15 // take a wifi rate in 0.5 mbps 170 #define WIFI_TAG_REQUEST_ID 16 // take an integer as parameter 171 #define WIFI_TAG_BUCKET_ID 17 // take an integer as parameter 172 #define WIFI_TAG_GSCAN_PARAMS 18 // takes a wifi_scan_cmd_params struct as parameter 173 #define WIFI_TAG_GSCAN_CAPABILITIES 19 // takes a wifi_gscan_capabilities struct as parameter 174 #define WIFI_TAG_SCAN_ID 20 // take an integer as parameter 175 #define WIFI_TAG_RSSI 21 // take an integer as parameter 176 #define WIFI_TAG_CHANNEL 22 // take an integer as parameter 177 #define WIFI_TAG_LINK_ID 23 // take an integer as parameter 178 #define WIFI_TAG_LINK_ROLE 24 // take an integer as parameter 179 #define WIFI_TAG_LINK_STATE 25 // take an integer as parameter 180 #define WIFI_TAG_LINK_TYPE 26 // take an integer as parameter 181 #define WIFI_TAG_TSCO 27 // take an integer as parameter 182 #define WIFI_TAG_RSCO 28 // take an integer as parameter 183 #define WIFI_TAG_EAPOL_MESSAGE_TYPE 29 // take an integer as parameter 184 // M1-1, M2-2, M3-3, M4-4 185 186 typedef struct { 187 u16 tag; 188 u16 length; // length of value 189 u8 value[0]; 190 } __attribute__((packed)) tlv_log; 191 192 typedef struct { 193 u16 event; 194 tlv_log tlvs[0]; // separate parameter structure per event to be provided and optional data 195 // the event_data is expected to include an official android part, with some 196 // parameter as transmit rate, num retries, num scan result found etc... 197 // as well, event_data can include a vendor proprietary part which is 198 // understood by the developer only. 199 } __attribute__((packed)) wifi_ring_buffer_driver_connectivity_event; 200 201 202 /** 203 * Ring buffer name for power events ring. note that power event are extremely frequents 204 * and thus should be stored in their own ring/file so as not to clobber connectivity events. 205 */ 206 typedef struct { 207 int status; // 0 taken, 1 released 208 int reason; // reason why this wake lock is taken 209 char name[0]; // null terminated 210 } __attribute__((packed)) wake_lock_event; 211 212 typedef struct { 213 u16 event; 214 tlv_log tlvs[0]; 215 } __attribute__((packed)) wifi_power_event; 216 217 218 /** 219 * This structure represent a logger entry within a ring buffer. 220 * Wifi driver are responsible to manage the ring buffer and write the debug 221 * information into those rings. 222 * 223 * In general, the debug entries can be used to store meaningful 802.11 information (SME, MLME, 224 * connection and packet statistics) as well as vendor proprietary data that is specific to a 225 * specific driver or chipset. 226 * Binary entries can be used so as to store packet data or vendor specific information and 227 * will be treated as blobs of data by android. 228 * 229 * A user land process will be started by framework so as to periodically retrieve the 230 * data logged by drivers into their ring buffer, store the data into log files and include 231 * the logs into android bugreports. 232 */ 233 enum { 234 RING_BUFFER_ENTRY_FLAGS_HAS_BINARY = (1 << (0)), // set for binary entries 235 RING_BUFFER_ENTRY_FLAGS_HAS_TIMESTAMP = (1 << (1)) // set if 64 bits timestamp is present 236 }; 237 238 enum { 239 ENTRY_TYPE_CONNECT_EVENT = 1, 240 ENTRY_TYPE_PKT, 241 ENTRY_TYPE_WAKE_LOCK, 242 ENTRY_TYPE_POWER_EVENT, 243 ENTRY_TYPE_DATA 244 }; 245 246 typedef struct { 247 u16 entry_size; // the size of payload excluding the header. 248 u8 flags; 249 u8 type; // entry type 250 u64 timestamp; // present if has_timestamp bit is set. 251 } __attribute__((packed)) wifi_ring_buffer_entry; 252 253 #define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES 0x00000001 // set if binary entries are present 254 #define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRIES 0x00000002 // set if ascii entries are present 255 256 257 /* ring buffer params */ 258 /** 259 * written_bytes and read_bytes implement a producer consumer API 260 * hence written_bytes >= read_bytes 261 * a modulo arithmetic of the buffer size has to be applied to those counters: 262 * actual offset into ring buffer = written_bytes % ring_buffer_byte_size 263 * 264 */ 265 typedef struct { 266 u8 name[32]; 267 u32 flags; 268 wifi_ring_buffer_id ring_id; // unique integer representing the ring 269 u32 ring_buffer_byte_size; // total memory size allocated for the buffer 270 u32 verbose_level; // verbose level for ring buffer 271 u32 written_bytes; // number of bytes that was written to the buffer by driver, 272 // monotonously increasing integer 273 u32 read_bytes; // number of bytes that was read from the buffer by user land, 274 // monotonously increasing integer 275 u32 written_records; // number of records that was written to the buffer by driver, 276 // monotonously increasing integer 277 } wifi_ring_buffer_status; 278 279 280 /** 281 * Callback for reporting ring data 282 * 283 * The ring buffer data collection is event based: 284 * - Driver calls on_ring_buffer_data when new records are available, the wifi_ring_buffer_status 285 * passed up to framework in the call back indicates to framework if more data is available in 286 * the ring buffer. It is not expected that driver will necessarily always empty the ring 287 * immediately as data is available, instead driver will report data every X seconds or if 288 * N bytes are available. 289 * - In the case where a bug report has to be captured, framework will require driver to upload 290 * all data immediately. This is indicated to driver when framework calls wifi_get_ringdata. 291 * When framework calls wifi_get_ring_data, driver will start sending all available data in the 292 * indicated ring by repeatedly invoking the on_ring_buffer_data callback. 293 * 294 * The callback is called by log handler whenever ring data comes in driver. 295 */ 296 typedef struct { 297 void (*on_ring_buffer_data) (char *ring_name, char *buffer, int buffer_size, 298 wifi_ring_buffer_status *status); 299 } wifi_ring_buffer_data_handler; 300 301 /** 302 * API to set the log handler for getting ring data 303 * - Only a single instance of log handler can be instantiated for each ring buffer. 304 */ 305 wifi_error wifi_set_log_handler(wifi_request_id id, wifi_interface_handle iface, 306 wifi_ring_buffer_data_handler handler); 307 308 /* API to reset the log handler */ 309 wifi_error wifi_reset_log_handler(wifi_request_id id, wifi_interface_handle iface); 310 311 312 /** 313 * Callback for reporting FW dump 314 * 315 * The buffer data collection is event based such as FW health check or FW dump. 316 * The callback is called by alert handler. 317 */ 318 typedef struct { 319 void (*on_alert) (wifi_request_id id, char *buffer, int buffer_size, int err_code); 320 } wifi_alert_handler; 321 322 /* 323 * API to set the alert handler for the alert case in Wi-Fi Chip 324 * - Only a single instance of alert handler can be instantiated. 325 */ 326 wifi_error wifi_set_alert_handler(wifi_request_id id, wifi_interface_handle iface, 327 wifi_alert_handler handler); 328 329 /* API to reset the alert handler */ 330 wifi_error wifi_reset_alert_handler(wifi_request_id id, wifi_interface_handle iface); 331 332 /* API for framework to indicate driver has to upload and drain all data of a given ring */ 333 wifi_error wifi_get_ring_data(wifi_interface_handle iface, char *ring_name); 334 335 336 /** 337 * API to trigger the debug collection. 338 * Unless his API is invoked - logging is not triggered. 339 * - Verbose_level 0 corresponds to no collection, 340 * and it makes log handler stop by no more events from driver. 341 * - Verbose_level 1 correspond to normal log level, with minimal user impact. 342 * This is the default value. 343 * - Verbose_level 2 are enabled when user is lazily trying to reproduce a problem, 344 * wifi performances and power can be impacted but device should not otherwise be 345 * significantly impacted. 346 * - Verbose_level 3+ are used when trying to actively debug a problem. 347 * 348 * ring_name represent the name of the ring for which data collection shall start. 349 * 350 * flags: TBD parameter used to enable/disable specific events on a ring 351 * max_interval: maximum interval in seconds for driver to invoke on_ring_buffer_data, 352 * ignore if zero 353 * min_data_size: minimum data size in buffer for driver to invoke on_ring_buffer_data, 354 * ignore if zero 355 */ 356 wifi_error wifi_start_logging(wifi_interface_handle iface, u32 verbose_level, u32 flags, 357 u32 max_interval_sec, u32 min_data_size, char *ring_name); 358 359 /** 360 * API to get the status of all ring buffers supported by driver. 361 * - Caller is responsible to allocate / free ring buffer status. 362 * - Maximum no of ring buffer would be 10. 363 */ 364 wifi_error wifi_get_ring_buffers_status(wifi_interface_handle iface, u32 *num_rings, 365 wifi_ring_buffer_status *status); 366 367 /** 368 * Synchronous memory dump by user request. 369 * - Caller is responsible to store memory dump data into a local, 370 * e.g., /data/misc/wifi/memdump.bin 371 */ 372 typedef struct { 373 void (*on_firmware_memory_dump) (char *buffer, int buffer_size); 374 } wifi_firmware_memory_dump_handler; 375 376 /** 377 * API to collect a firmware memory dump for a given iface by async memdump event. 378 * - Triggered by Alerthandler, esp. when FW problem or FW health check happens 379 * - Caller is responsible to store fw dump data into a local, 380 * e.g., /data/misc/wifi/alertdump-1.bin 381 */ 382 wifi_error wifi_get_firmware_memory_dump(wifi_interface_handle iface, 383 wifi_firmware_memory_dump_handler handler); 384 385 /** 386 * API to collect a firmware version string. 387 * - Caller is responsible to allocate / free a buffer to retrieve firmware verion info. 388 * - Max string will be at most 256 bytes. 389 */ 390 wifi_error wifi_get_firmware_version(wifi_interface_handle iface, char *buffer, int buffer_size); 391 392 /** 393 * API to collect a driver version string. 394 * - Caller is responsible to allocate / free a buffer to retrieve driver verion info. 395 * - Max string will be at most 256 bytes. 396 */ 397 wifi_error wifi_get_driver_version(wifi_interface_handle iface, char *buffer, int buffer_size); 398 399 400 /* Feature set */ 401 enum { 402 WIFI_LOGGER_MEMORY_DUMP_SUPPORTED = (1 << (0)), // Memory dump of FW 403 WIFI_LOGGER_PER_PACKET_TX_RX_STATUS_SUPPORTED = (1 << (1)), // PKT status 404 WIFI_LOGGER_CONNECT_EVENT_SUPPORTED = (1 << (2)), // Connectivity event 405 WIFI_LOGGER_POWER_EVENT_SUPPORTED = (1 << (3)), // POWER of Driver 406 WIFI_LOGGER_WAKE_LOCK_SUPPORTED = (1 << (4)), // WAKE LOCK of Driver 407 WIFI_LOGGER_VERBOSE_SUPPORTED = (1 << (5)), // verbose log of FW 408 WIFI_LOGGER_WATCHDOG_TIMER_SUPPORTED = (1 << (6)), // monitor the health of FW 409 WIFI_LOGGER_DRIVER_DUMP_SUPPORTED = (1 << (7)), // dumps driver state 410 WIFI_LOGGER_PACKET_FATE_SUPPORTED = (1 << (8)), // tracks connection packets' fate 411 }; 412 413 /** 414 * API to retrieve the current supportive features. 415 * - An integer variable is enough to have bit mapping info by caller. 416 */ 417 wifi_error wifi_get_logger_supported_feature_set(wifi_interface_handle iface, 418 unsigned int *support); 419 420 typedef struct { 421 /* Buffer is to be allocated and freed by HAL implementation. */ 422 void (*on_driver_memory_dump) (char *buffer, int buffer_size); 423 } wifi_driver_memory_dump_callbacks; 424 425 /** 426 API to collect driver state. 427 428 Framework will call this API soon before or after (but not 429 concurrently with) wifi_get_firmware_memory_dump(). Capturing 430 firmware and driver dumps is intended to help identify 431 inconsistent state between these components. 432 433 - In response to this call, HAL implementation should make one or 434 more calls to callbacks.on_driver_memory_dump(). Framework will 435 copy data out of the received |buffer|s, and concatenate the 436 contents thereof. 437 - HAL implemention will indicate completion of the driver memory 438 dump by returning from this call. 439 */ 440 wifi_error wifi_get_driver_memory_dump( 441 wifi_interface_handle iface, 442 wifi_driver_memory_dump_callbacks callbacks); 443 444 445 /* packet fate logs */ 446 447 #define MD5_PREFIX_LEN 4 448 #define MAX_FATE_LOG_LEN 32 449 #define MAX_FRAME_LEN_ETHERNET 1518 450 #define MAX_FRAME_LEN_80211_MGMT 2352 // 802.11-2012 Fig. 8-34 451 452 typedef enum { 453 // Sent over air and ACKed. 454 TX_PKT_FATE_ACKED, 455 456 // Sent over air but not ACKed. (Normal for broadcast/multicast.) 457 TX_PKT_FATE_SENT, 458 459 // Queued within firmware, but not yet sent over air. 460 TX_PKT_FATE_FW_QUEUED, 461 462 // Dropped by firmware as invalid. E.g. bad source address, bad checksum, 463 // or invalid for current state. 464 TX_PKT_FATE_FW_DROP_INVALID, 465 466 // Dropped by firmware due to lack of buffer space. 467 TX_PKT_FATE_FW_DROP_NOBUFS, 468 469 // Dropped by firmware for any other reason. Includes frames that 470 // were sent by driver to firmware, but unaccounted for by 471 // firmware. 472 TX_PKT_FATE_FW_DROP_OTHER, 473 474 // Queued within driver, not yet sent to firmware. 475 TX_PKT_FATE_DRV_QUEUED, 476 477 // Dropped by driver as invalid. E.g. bad source address, or 478 // invalid for current state. 479 TX_PKT_FATE_DRV_DROP_INVALID, 480 481 // Dropped by driver due to lack of buffer space. 482 TX_PKT_FATE_DRV_DROP_NOBUFS, 483 484 // Dropped by driver for any other reason. 485 TX_PKT_FATE_DRV_DROP_OTHER, 486 } wifi_tx_packet_fate; 487 488 typedef enum { 489 // Valid and delivered to network stack (e.g., netif_rx()). 490 RX_PKT_FATE_SUCCESS, 491 492 // Queued within firmware, but not yet sent to driver. 493 RX_PKT_FATE_FW_QUEUED, 494 495 // Dropped by firmware due to host-programmable filters. 496 RX_PKT_FATE_FW_DROP_FILTER, 497 498 // Dropped by firmware as invalid. E.g. bad checksum, decrypt failed, 499 // or invalid for current state. 500 RX_PKT_FATE_FW_DROP_INVALID, 501 502 // Dropped by firmware due to lack of buffer space. 503 RX_PKT_FATE_FW_DROP_NOBUFS, 504 505 // Dropped by firmware for any other reason. 506 RX_PKT_FATE_FW_DROP_OTHER, 507 508 // Queued within driver, not yet delivered to network stack. 509 RX_PKT_FATE_DRV_QUEUED, 510 511 // Dropped by driver due to filter rules. 512 RX_PKT_FATE_DRV_DROP_FILTER, 513 514 // Dropped by driver as invalid. E.g. not permitted in current state. 515 RX_PKT_FATE_DRV_DROP_INVALID, 516 517 // Dropped by driver due to lack of buffer space. 518 RX_PKT_FATE_DRV_DROP_NOBUFS, 519 520 // Dropped by driver for any other reason. 521 RX_PKT_FATE_DRV_DROP_OTHER, 522 } wifi_rx_packet_fate; 523 524 typedef enum { 525 FRAME_TYPE_UNKNOWN, 526 FRAME_TYPE_ETHERNET_II, 527 FRAME_TYPE_80211_MGMT, 528 } frame_type; 529 530 typedef struct { 531 // The type of MAC-layer frame that this frame_info holds. 532 // - For data frames, use FRAME_TYPE_ETHERNET_II. 533 // - For management frames, use FRAME_TYPE_80211_MGMT. 534 // - If the type of the frame is unknown, use FRAME_TYPE_UNKNOWN. 535 frame_type payload_type; 536 537 // The number of bytes included in |frame_content|. If the frame 538 // contents are missing (e.g. RX frame dropped in firmware), 539 // |frame_len| should be set to 0. 540 size_t frame_len; 541 542 // Host clock when this frame was received by the driver (either 543 // outbound from the host network stack, or inbound from the 544 // firmware). 545 // - The timestamp should be taken from a clock which includes time 546 // the host spent suspended (e.g. ktime_get_boottime()). 547 // - If no host timestamp is available (e.g. RX frame was dropped in 548 // firmware), this field should be set to 0. 549 u32 driver_timestamp_usec; 550 551 // Firmware clock when this frame was received by the firmware 552 // (either outbound from the host, or inbound from a remote 553 // station). 554 // - The timestamp should be taken from a clock which includes time 555 // firmware spent suspended (if applicable). 556 // - If no firmware timestamp is available (e.g. TX frame was 557 // dropped by driver), this field should be set to 0. 558 // - Consumers of |frame_info| should _not_ assume any 559 // synchronization between driver and firmware clocks. 560 u32 firmware_timestamp_usec; 561 562 // Actual frame content. 563 // - Should be provided for TX frames originated by the host. 564 // - Should be provided for RX frames received by the driver. 565 // - Optionally provided for TX frames originated by firmware. (At 566 // discretion of HAL implementation.) 567 // - Optionally provided for RX frames dropped in firmware. (At 568 // discretion of HAL implementation.) 569 // - If frame content is not provided, |frame_len| should be set 570 // to 0. 571 union { 572 char ethernet_ii_bytes[MAX_FRAME_LEN_ETHERNET]; 573 char ieee_80211_mgmt_bytes[MAX_FRAME_LEN_80211_MGMT]; 574 } frame_content; 575 } frame_info; 576 577 typedef struct { 578 // Prefix of MD5 hash of |frame_inf.frame_content|. If frame 579 // content is not provided, prefix of MD5 hash over the same data 580 // that would be in frame_content, if frame content were provided. 581 char md5_prefix[MD5_PREFIX_LEN]; 582 wifi_tx_packet_fate fate; 583 frame_info frame_inf; 584 } wifi_tx_report; 585 586 typedef struct { 587 // Prefix of MD5 hash of |frame_inf.frame_content|. If frame 588 // content is not provided, prefix of MD5 hash over the same data 589 // that would be in frame_content, if frame content were provided. 590 char md5_prefix[MD5_PREFIX_LEN]; 591 wifi_rx_packet_fate fate; 592 frame_info frame_inf; 593 } wifi_rx_report; 594 595 /** 596 API to start packet fate monitoring. 597 - Once stared, monitoring should remain active until HAL is unloaded. 598 - When HAL is unloaded, all packet fate buffers should be cleared. 599 */ 600 wifi_error wifi_start_pkt_fate_monitoring(wifi_interface_handle handle); 601 602 /** 603 API to retrieve fates of outbound packets. 604 - HAL implementation should fill |tx_report_bufs| with fates of 605 _first_ min(n_requested_fates, actual packets) frames 606 transmitted for the most recent association. The fate reports 607 should follow the same order as their respective packets. 608 - HAL implementation may choose (but is not required) to include 609 reports for management frames. 610 - Packets reported by firmware, but not recognized by driver, 611 should be included. However, the ordering of the corresponding 612 reports is at the discretion of HAL implementation. 613 - Framework may call this API multiple times for the same association. 614 - Framework will ensure |n_requested_fates <= MAX_FATE_LOG_LEN|. 615 - Framework will allocate and free the referenced storage. 616 */ 617 wifi_error wifi_get_tx_pkt_fates(wifi_interface_handle handle, 618 wifi_tx_report *tx_report_bufs, 619 size_t n_requested_fates, 620 size_t *n_provided_fates); 621 622 /** 623 API to retrieve fates of inbound packets. 624 - HAL implementation should fill |rx_report_bufs| with fates of 625 _first_ min(n_requested_fates, actual packets) frames 626 received for the most recent association. The fate reports 627 should follow the same order as their respective packets. 628 - HAL implementation may choose (but is not required) to include 629 reports for management frames. 630 - Packets reported by firmware, but not recognized by driver, 631 should be included. However, the ordering of the corresponding 632 reports is at the discretion of HAL implementation. 633 - Framework may call this API multiple times for the same association. 634 - Framework will ensure |n_requested_fates <= MAX_FATE_LOG_LEN|. 635 - Framework will allocate and free the referenced storage. 636 */ 637 wifi_error wifi_get_rx_pkt_fates(wifi_interface_handle handle, 638 wifi_rx_report *rx_report_bufs, 639 size_t n_requested_fates, 640 size_t *n_provided_fates); 641 642 #ifdef __cplusplus 643 } 644 #endif /* __cplusplus */ 645 646 #endif /*__WIFI_HAL_STATS_ */ 647