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_radio; 39 typedef int wifi_ring_buffer_id; 40 41 #define PER_PACKET_ENTRY_FLAGS_DIRECTION_TX 1 // 0: TX, 1: RX 42 #define PER_PACKET_ENTRY_FLAGS_TX_SUCCESS 2 // whether packet was transmitted or 43 // received/decrypted successfully 44 #define PER_PACKET_ENTRY_FLAGS_80211_HEADER 4 // has full 802.11 header, else has 802.3 header 45 #define PER_PACKET_ENTRY_FLAGS_PROTECTED 8 // whether packet was encrypted 46 47 typedef struct { 48 u8 flags; 49 u8 tid; // transmit or received tid 50 u16 MCS; // modulation and bandwidth 51 u8 rssi; // TX: RSSI of ACK for that packet 52 // RX: RSSI of packet 53 u8 num_retries; // number of attempted retries 54 u16 last_transmit_rate; // last transmit rate in .5 mbps 55 u16 link_layer_transmit_sequence; // transmit/reeive sequence for that MPDU packet 56 u64 firmware_entry_timestamp; // TX: firmware timestamp (us) when packet is queued within 57 // firmware buffer for SDIO/HSIC or into PCIe buffer 58 // RX: firmware receive timestamp 59 u64 start_contention_timestamp; // firmware timestamp (us) when packet start contending for the 60 // medium for the first time, at head of its AC queue, 61 // or as part of an MPDU or A-MPDU. This timestamp is 62 // not updated for each retry, only the first transmit attempt. 63 u64 transmit_success_timestamp; // fimrware timestamp (us) when packet is successfully 64 // transmitted or aborted because it has exhausted 65 // its maximum number of retries. 66 u8 data[0]; // packet data. The length of packet data is determined by the entry_size field of 67 // the wifi_ring_buffer_entry structure. It is expected that first bytes of the 68 // packet, or packet headers only (up to TCP or RTP/UDP headers) 69 // will be copied into the ring 70 } __attribute__((packed)) wifi_ring_per_packet_status_entry; 71 72 73 /* Below events refer to the wifi_connectivity_event ring and shall be supported */ 74 #define WIFI_EVENT_ASSOCIATION_REQUESTED 0 // driver receives association command from kernel 75 #define WIFI_EVENT_AUTH_COMPLETE 1 76 #define WIFI_EVENT_ASSOC_COMPLETE 2 77 #define WIFI_EVENT_FW_AUTH_STARTED 3 // fw event indicating auth frames are sent 78 #define WIFI_EVENT_FW_ASSOC_STARTED 4 // fw event indicating assoc frames are sent 79 #define WIFI_EVENT_FW_RE_ASSOC_STARTED 5 // fw event indicating reassoc frames are sent 80 #define WIFI_EVENT_DRIVER_SCAN_REQUESTED 6 81 #define WIFI_EVENT_DRIVER_SCAN_RESULT_FOUND 7 82 #define WIFI_EVENT_DRIVER_SCAN_COMPLETE 8 83 #define WIFI_EVENT_G_SCAN_STARTED 9 84 #define WIFI_EVENT_G_SCAN_COMPLETE 10 85 #define WIFI_EVENT_DISASSOCIATION_REQUESTED 11 86 #define WIFI_EVENT_RE_ASSOCIATION_REQUESTED 12 87 #define WIFI_EVENT_ROAM_REQUESTED 13 88 #define WIFI_EVENT_BEACON_RECEIVED 14 // received beacon from AP (event enabled 89 // only in verbose mode) 90 #define WIFI_EVENT_ROAM_SCAN_STARTED 15 // firmware has triggered a roam scan (not g-scan) 91 #define WIFI_EVENT_ROAM_SCAN_COMPLETE 16 // firmware has completed a roam scan (not g-scan) 92 #define WIFI_EVENT_ROAM_SEARCH_STARTED 17 // firmware has started searching for roam 93 // candidates (with reason =xx) 94 #define WIFI_EVENT_ROAM_SEARCH_STOPPED 18 // firmware has stopped searching for roam 95 // candidates (with reason =xx) 96 #define WIFI_EVENT_CHANNEL_SWITCH_ANOUNCEMENT 20 // received channel switch anouncement from AP 97 #define WIFI_EVENT_FW_EAPOL_FRAME_TRANSMIT_START 21 // fw start transmit eapol frame, with 98 // EAPOL index 1-4 99 #define WIFI_EVENT_FW_EAPOL_FRAME_TRANSMIT_STOP 22 // fw gives up eapol frame, with rate, 100 // success/failure and number retries 101 #define WIFI_EVENT_DRIVER_EAPOL_FRAME_TRANSMIT_REQUESTED 23 // kernel queue EAPOL for transmission 102 // in driver with EAPOL index 1-4 103 #define WIFI_EVENT_FW_EAPOL_FRAME_RECEIVED 24 // with rate, regardless of the fact that 104 // EAPOL frame is accepted or rejected by fw 105 #define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has 106 // received EAPOL frame and will queue it up 107 // to wpa_supplicant 108 #define WIFI_EVENT_BLOCK_ACK_NEGOTIATION_COMPLETE 27 // with success/failure, parameters 109 #define WIFI_EVENT_BT_COEX_BT_SCO_START 28 110 #define WIFI_EVENT_BT_COEX_BT_SCO_STOP 29 111 #define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc., when BT starts transmiting 112 // twice per BT slot 113 #define WIFI_EVENT_BT_COEX_BT_SCAN_STOP 31 114 #define WIFI_EVENT_BT_COEX_BT_HID_START 32 115 #define WIFI_EVENT_BT_COEX_BT_HID_STOP 33 116 #define WIFI_EVENT_ROAM_AUTH_STARTED 34 // fw sends auth frame in roaming to next candidate 117 #define WIFI_EVENT_ROAM_AUTH_COMPLETE 35 // fw receive auth confirm from ap 118 #define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in 119 // roaming to next candidate 120 #define WIFI_EVENT_ROAM_ASSOC_COMPLETE 37 // firmware receive assoc/reassoc confirm from ap 121 #define WIFI_EVENT_G_SCAN_STOP 38 // firmware sends stop G_SCAN 122 #define WIFI_EVENT_G_SCAN_CYCLE_STARTED 39 // firmware indicates G_SCAN scan cycle started 123 #define WIFI_EVENT_G_SCAN_CYCLE_COMPLETED 40 // firmware indicates G_SCAN scan cycle completed 124 #define WIFI_EVENT_G_SCAN_BUCKET_STARTED 41 // firmware indicates G_SCAN scan start 125 // for a particular bucket 126 #define WIFI_EVENT_G_SCAN_BUCKET_COMPLETED 42 // firmware indicates G_SCAN scan completed for 127 // for a particular bucket 128 #define WIFI_EVENT_G_SCAN_RESULTS_AVAILABLE 43 // Event received from firmware about G_SCAN scan 129 // results being available 130 #define WIFI_EVENT_G_SCAN_CAPABILITIES 44 // Event received from firmware with G_SCAN 131 // capabilities 132 #define WIFI_EVENT_ROAM_CANDIDATE_FOUND 45 // Event received from firmware when eligible 133 // candidate is found 134 #define WIFI_EVENT_ROAM_SCAN_CONFIG 46 // Event received from firmware when roam scan 135 // configuration gets enabled or disabled 136 137 /** 138 * Parameters of wifi logger events are TLVs 139 * Event parameters tags are defined as: 140 */ 141 #define WIFI_TAG_VENDOR_SPECIFIC 0 // take a byte stream as parameter 142 #define WIFI_TAG_BSSID 1 // takes a 6 bytes MAC address as parameter 143 #define WIFI_TAG_ADDR 2 // takes a 6 bytes MAC address as parameter 144 #define WIFI_TAG_SSID 3 // takes a 32 bytes SSID address as parameter 145 #define WIFI_TAG_STATUS 4 // takes an integer as parameter 146 #define WIFI_TAG_CHANNEL_SPEC 5 // takes one or more wifi_channel_spec as parameter 147 #define WIFI_TAG_WAKE_LOCK_EVENT 6 // takes a wake_lock_event struct as parameter 148 #define WIFI_TAG_ADDR1 7 // takes a 6 bytes MAC address as parameter 149 #define WIFI_TAG_ADDR2 8 // takes a 6 bytes MAC address as parameter 150 #define WIFI_TAG_ADDR3 9 // takes a 6 bytes MAC address as parameter 151 #define WIFI_TAG_ADDR4 10 // takes a 6 bytes MAC address as parameter 152 #define WIFI_TAG_TSF 11 // take a 64 bits TSF value as parameter 153 #define WIFI_TAG_IE 12 // take one or more specific 802.11 IEs parameter, 154 // IEs are in turn indicated in TLV format as per 155 // 802.11 spec 156 #define WIFI_TAG_INTERFACE 13 // take interface name as parameter 157 #define WIFI_TAG_REASON_CODE 14 // take a reason code as per 802.11 as parameter 158 #define WIFI_TAG_RATE_MBPS 15 // take a wifi rate in 0.5 mbps 159 #define WIFI_TAG_REQUEST_ID 16 // take an integer as parameter 160 #define WIFI_TAG_BUCKET_ID 17 // take an integer as parameter 161 #define WIFI_TAG_GSCAN_PARAMS 18 // takes a wifi_scan_cmd_params struct as parameter 162 #define WIFI_TAG_GSCAN_CAPABILITIES 19 // takes a wifi_gscan_capabilities struct as parameter 163 #define WIFI_TAG_SCAN_ID 20 // take an integer as parameter 164 #define WIFI_TAG_RSSI 21 // take an integer as parameter 165 #define WIFI_TAG_CHANNEL 22 // take an integer as parameter 166 #define WIFI_TAG_LINK_ID 23 // take an integer as parameter 167 #define WIFI_TAG_LINK_ROLE 24 // take an integer as parameter 168 #define WIFI_TAG_LINK_STATE 25 // take an integer as parameter 169 #define WIFI_TAG_LINK_TYPE 26 // take an integer as parameter 170 #define WIFI_TAG_TSCO 27 // take an integer as parameter 171 #define WIFI_TAG_RSCO 28 // take an integer as parameter 172 #define WIFI_TAG_EAPOL_MESSAGE_TYPE 29 // take an integer as parameter 173 // M1-1, M2-2, M3-3, M4-4 174 175 typedef struct { 176 u16 tag; 177 u16 length; // length of value 178 u8 value[0]; 179 } __attribute__((packed)) tlv_log; 180 181 typedef struct { 182 u16 event; 183 tlv_log tlvs[0]; // separate parameter structure per event to be provided and optional data 184 // the event_data is expected to include an official android part, with some 185 // parameter as transmit rate, num retries, num scan result found etc... 186 // as well, event_data can include a vendor proprietary part which is 187 // understood by the developer only. 188 } __attribute__((packed)) wifi_ring_buffer_driver_connectivity_event; 189 190 191 /** 192 * Ring buffer name for power events ring. note that power event are extremely frequents 193 * and thus should be stored in their own ring/file so as not to clobber connectivity events. 194 */ 195 typedef struct { 196 int status; // 0 taken, 1 released 197 int reason; // reason why this wake lock is taken 198 char name[0]; // null terminated 199 } __attribute__((packed)) wake_lock_event; 200 201 typedef struct { 202 u16 event; 203 tlv_log tlvs[0]; 204 } __attribute__((packed)) wifi_power_event; 205 206 207 /** 208 * This structure represent a logger entry within a ring buffer. 209 * Wifi driver are responsible to manage the ring buffer and write the debug 210 * information into those rings. 211 * 212 * In general, the debug entries can be used to store meaningful 802.11 information (SME, MLME, 213 * connection and packet statistics) as well as vendor proprietary data that is specific to a 214 * specific driver or chipset. 215 * Binary entries can be used so as to store packet data or vendor specific information and 216 * will be treated as blobs of data by android. 217 * 218 * A user land process will be started by framework so as to periodically retrieve the 219 * data logged by drivers into their ring buffer, store the data into log files and include 220 * the logs into android bugreports. 221 */ 222 enum { 223 RING_BUFFER_ENTRY_FLAGS_HAS_BINARY = (1 << (0)), // set for binary entries 224 RING_BUFFER_ENTRY_FLAGS_HAS_TIMESTAMP = (1 << (1)) // set if 64 bits timestamp is present 225 }; 226 227 enum { 228 ENTRY_TYPE_CONNECT_EVENT = 1, 229 ENTRY_TYPE_PKT, 230 ENTRY_TYPE_WAKE_LOCK, 231 ENTRY_TYPE_POWER_EVENT, 232 ENTRY_TYPE_DATA 233 }; 234 235 typedef struct { 236 u16 entry_size; // the size of payload excluding the header. 237 u8 flags; 238 u8 type; // entry type 239 u64 timestamp; // present if has_timestamp bit is set. 240 } __attribute__((packed)) wifi_ring_buffer_entry; 241 242 #define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES 0x00000001 // set if binary entries are present 243 #define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRIES 0x00000002 // set if ascii entries are present 244 245 246 /* ring buffer params */ 247 /** 248 * written_bytes and read_bytes implement a producer consumer API 249 * hence written_bytes >= read_bytes 250 * a modulo arithmetic of the buffer size has to be applied to those counters: 251 * actual offset into ring buffer = written_bytes % ring_buffer_byte_size 252 * 253 */ 254 typedef struct { 255 u8 name[32]; 256 u32 flags; 257 wifi_ring_buffer_id ring_id; // unique integer representing the ring 258 u32 ring_buffer_byte_size; // total memory size allocated for the buffer 259 u32 verbose_level; // verbose level for ring buffer 260 u32 written_bytes; // number of bytes that was written to the buffer by driver, 261 // monotonously increasing integer 262 u32 read_bytes; // number of bytes that was read from the buffer by user land, 263 // monotonously increasing integer 264 u32 written_records; // number of records that was written to the buffer by driver, 265 // monotonously increasing integer 266 } wifi_ring_buffer_status; 267 268 269 /** 270 * Callback for reporting ring data 271 * 272 * The ring buffer data collection is event based: 273 * - Driver calls on_ring_buffer_data when new records are available, the wifi_ring_buffer_status 274 * passed up to framework in the call back indicates to framework if more data is available in 275 * the ring buffer. It is not expected that driver will necessarily always empty the ring 276 * immediately as data is available, instead driver will report data every X seconds or if 277 * N bytes are available. 278 * - In the case where a bug report has to be captured, framework will require driver to upload 279 * all data immediately. This is indicated to driver when framework calls wifi_get_ringdata. 280 * When framework calls wifi_get_ring_data, driver will start sending all available data in the 281 * indicated ring by repeatedly invoking the on_ring_buffer_data callback. 282 * 283 * The callback is called by log handler whenever ring data comes in driver. 284 */ 285 typedef struct { 286 void (*on_ring_buffer_data) (char *ring_name, char *buffer, int buffer_size, 287 wifi_ring_buffer_status *status); 288 } wifi_ring_buffer_data_handler; 289 290 /** 291 * API to set the log handler for getting ring data 292 * - Only a single instance of log handler can be instantiated for each ring buffer. 293 */ 294 wifi_error wifi_set_log_handler(wifi_request_id id, wifi_interface_handle iface, 295 wifi_ring_buffer_data_handler handler); 296 297 /* API to reset the log handler */ 298 wifi_error wifi_reset_log_handler(wifi_request_id id, wifi_interface_handle iface); 299 300 301 /** 302 * Callback for reporting FW dump 303 * 304 * The buffer data collection is event based such as FW health check or FW dump. 305 * The callback is called by alert handler. 306 */ 307 typedef struct { 308 void (*on_alert) (wifi_request_id id, char *buffer, int buffer_size, int err_code); 309 } wifi_alert_handler; 310 311 /* 312 * API to set the alert handler for the alert case in Wi-Fi Chip 313 * - Only a single instance of alert handler can be instantiated. 314 */ 315 wifi_error wifi_set_alert_handler(wifi_request_id id, wifi_interface_handle iface, 316 wifi_alert_handler handler); 317 318 /* API to reset the alert handler */ 319 wifi_error wifi_reset_alert_handler(wifi_request_id id, wifi_interface_handle iface); 320 321 /* API for framework to indicate driver has to upload and drain all data of a given ring */ 322 wifi_error wifi_get_ring_data(wifi_interface_handle iface, char *ring_name); 323 324 325 /** 326 * API to trigger the debug collection. 327 * Unless his API is invoked - logging is not triggered. 328 * - Verbose_level 0 corresponds to no collection, 329 * and it makes log handler stop by no more events from driver. 330 * - Verbose_level 1 correspond to normal log level, with minimal user impact. 331 * This is the default value. 332 * - Verbose_level 2 are enabled when user is lazily trying to reproduce a problem, 333 * wifi performances and power can be impacted but device should not otherwise be 334 * significantly impacted. 335 * - Verbose_level 3+ are used when trying to actively debug a problem. 336 * 337 * ring_name represent the name of the ring for which data collection shall start. 338 * 339 * flags: TBD parameter used to enable/disable specific events on a ring 340 * max_interval: maximum interval in seconds for driver to invoke on_ring_buffer_data, 341 * ignore if zero 342 * min_data_size: minimum data size in buffer for driver to invoke on_ring_buffer_data, 343 * ignore if zero 344 */ 345 wifi_error wifi_start_logging(wifi_interface_handle iface, u32 verbose_level, u32 flags, 346 u32 max_interval_sec, u32 min_data_size, char *ring_name); 347 348 /** 349 * API to get the status of all ring buffers supported by driver. 350 * - Caller is responsible to allocate / free ring buffer status. 351 * - Maximum no of ring buffer would be 10. 352 */ 353 wifi_error wifi_get_ring_buffers_status(wifi_interface_handle iface, u32 *num_rings, 354 wifi_ring_buffer_status *status); 355 356 /** 357 * Synchronous memory dump by user request. 358 * - Caller is responsible to store memory dump data into a local, 359 * e.g., /data/misc/wifi/memdump.bin 360 */ 361 typedef struct { 362 void (*on_firmware_memory_dump) (char *buffer, int buffer_size); 363 } wifi_firmware_memory_dump_handler; 364 365 /** 366 * API to collect a firmware memory dump for a given iface by async memdump event. 367 * - Triggered by Alerthandler, esp. when FW problem or FW health check happens 368 * - Caller is responsible to store fw dump data into a local, 369 * e.g., /data/misc/wifi/alertdump-1.bin 370 */ 371 wifi_error wifi_get_firmware_memory_dump(wifi_interface_handle iface, 372 wifi_firmware_memory_dump_handler handler); 373 374 /** 375 * API to collect a firmware version string. 376 * - Caller is responsible to allocate / free a buffer to retrieve firmware verion info. 377 * - Max string will be at most 256 bytes. 378 */ 379 wifi_error wifi_get_firmware_version(wifi_interface_handle iface, char *buffer, int buffer_size); 380 381 /** 382 * API to collect a driver version string. 383 * - Caller is responsible to allocate / free a buffer to retrieve driver verion info. 384 * - Max string will be at most 256 bytes. 385 */ 386 wifi_error wifi_get_driver_version(wifi_interface_handle iface, char *buffer, int buffer_size); 387 388 389 /* Feature set */ 390 enum { 391 WIFI_LOGGER_MEMORY_DUMP_SUPPORTED = (1 << (0)), // Memory dump of FW 392 WIFI_LOGGER_PER_PACKET_TX_RX_STATUS_SUPPORTED = (1 << (1)), // PKT status 393 WIFI_LOGGER_CONNECT_EVENT_SUPPORTED = (1 << (2)), // Connectivity event 394 WIFI_LOGGER_POWER_EVENT_SUPPORTED = (1 << (3)), // POWER of Driver 395 WIFI_LOGGER_WAKE_LOCK_SUPPORTED = (1 << (4)), // WAKE LOCK of Driver 396 WIFI_LOGGER_VERBOSE_SUPPORTED = (1 << (5)), // verbose log of FW 397 WIFI_LOGGER_WATCHDOG_TIMER_SUPPORTED = (1 << (6)) // monitor the health of FW 398 }; 399 400 /** 401 * API to retrieve the current supportive features. 402 * - An integer variable is enough to have bit mapping info by caller. 403 */ 404 wifi_error wifi_get_logger_supported_feature_set(wifi_interface_handle iface, 405 unsigned int *support); 406 407 408 #ifdef __cplusplus 409 } 410 #endif /* __cplusplus */ 411 412 #endif /*__WIFI_HAL_STATS_ */ 413 414
