1 #include "wifi_hal.h"
\r
3 #ifndef __WIFI_HAL_LOGGER_H
\r
4 #define __WIFI_HAL_LOGGER_H
\r
9 #endif /* __cplusplus */
\r
11 #define LOGGER_MAJOR_VERSION 1
\r
12 #define LOGGER_MINOR_VERSION 0
\r
13 #define LOGGER_MICRO_VERSION 0
\r
18 * WiFi logger life cycle is as follow:
\r
20 * - at initialization time, framework will call wifi_get_ring_buffers_status so as to obtain the
\r
21 * names and list of supported buffers
\r
22 * - when WiFi operation start framework will call wifi_start_logging so as to trigger log collection
\r
23 * - Developper UI will provide an option to the user, so as it can set the verbose level of individual buffer
\r
24 * as reported by wifi_get_ring_buffers_status
\r
25 * - during wifi operations, driver will periodically report per ring data to framework by invoking the
\r
26 * on_ring_buffer_data call back
\r
27 * - when capturing a bug report, framework will indicate to driver that all the data has to be uploaded,
\r
28 * urgently, by calling wifi_get_ring_data
\r
30 * The data uploaded by driver will be stored by framework in separate files, with one stream of file per ring.
\r
31 * Framework will store the files in pcapng format, allowing for easy merging and parsing with network
\r
36 typedef int wifi_radio;
\r
37 typedef int wifi_ring_buffer_id;
\r
39 #define PER_PACKET_ENTRY_FLAGS_DIRECTION_TX 1 // 0: TX, 1: RX
\r
40 #define PER_PACKET_ENTRY_FLAGS_TX_SUCCESS 2 // whether packet was transmitted or received/decrypted successfully
\r
41 #define PER_PACKET_ENTRY_FLAGS_80211_HEADER 4 // has full 802.11 header, else has 802.3 header
\r
42 #define PER_PACKET_ENTRY_FLAGS_PROTECTED 8 // whether packet was encrypted
\r
46 u8 tid; // transmit or received tid
\r
47 u16 MCS; // modulation and bandwidth
\r
48 u8 rssi; // TX: RSSI of ACK for that packet
\r
49 // RX: RSSI of packet
\r
50 u8 num_retries; // number of attempted retries
\r
51 u16 last_transmit_rate; // last transmit rate in .5 mbps
\r
52 u16 link_layer_transmit_sequence; // transmit/reeive sequence for that MPDU packet
\r
53 u64 firmware_entry_timestamp; // TX: firmware timestamp (us) when packet is queued within firmware buffer
\r
54 // for SDIO/HSIC or into PCIe buffer
\r
55 // RX : firmware receive timestamp
\r
56 u64 start_contention_timestamp; // firmware timestamp (us) when packet start contending for the
\r
57 // medium for the first time, at head of its AC queue,
\r
58 // or as part of an MPDU or A-MPDU. This timestamp is not updated
\r
59 // for each retry, only the first transmit attempt.
\r
60 u64 transmit_success_timestamp; // fimrware timestamp (us) when packet is successfully transmitted
\r
61 // or aborted because it has exhausted its maximum number of retries
\r
62 u8 data[0]; // packet data. The length of packet data is determined by the entry_size field of
\r
63 // the wifi_ring_buffer_entry structure. It is expected that first bytes of the
\r
64 // packet, or packet headers only (up to TCP or RTP/UDP headers) will be copied into the ring
\r
65 } __attribute__((packed)) wifi_ring_per_packet_status_entry;
\r
68 // Below events refer to the wifi_connectivity_event ring and shall be supported
\r
70 #define WIFI_EVENT_ASSOCIATION_REQUESTED 0 // driver receive association command from kernel
\r
71 #define WIFI_EVENT_AUTH_COMPLETE 1
\r
72 #define WIFI_EVENT_ASSOC_COMPLETE 2
\r
73 #define WIFI_EVENT_FW_AUTH_STARTED 3 // received firmware event indicating auth frames are sent
\r
74 #define WIFI_EVENT_FW_ASSOC_STARTED 4 // received firmware event indicating assoc frames are sent
\r
75 #define WIFI_EVENT_FW_RE_ASSOC_STARTED 5 // received firmware event indicating reassoc frames are sent
\r
76 #define WIFI_EVENT_DRIVER_SCAN_REQUESTED 6
\r
77 #define WIFI_EVENT_DRIVER_SCAN_RESULT_FOUND 7
\r
78 #define WIFI_EVENT_DRIVER_SCAN_COMPLETE 8
\r
79 #define WIFI_EVENT_G_SCAN_STARTED 9
\r
80 #define WIFI_EVENT_G_SCAN_COMPLETE 10
\r
81 #define WIFI_EVENT_DISASSOCIATION_REQUESTED 11
\r
82 #define WIFI_EVENT_RE_ASSOCIATION_REQUESTED 12
\r
83 #define WIFI_EVENT_ROAM_REQUESTED 13
\r
84 #define WIFI_EVENT_BEACON_RECEIVED 14 // received beacon from AP (event enabled only in verbose mode)
\r
85 #define WIFI_EVENT_ROAM_SCAN_STARTED 15 // firmware has triggered a roam scan (not g-scan)
\r
86 #define WIFI_EVENT_ROAM_SCAN_COMPLETE 16 // firmware has completed a roam scan (not g-scan)
\r
87 #define WIFI_EVENT_ROAM_SEARCH_STARTED 17 // firmware has started searching for roam candidates (with reason =xx)
\r
88 #define WIFI_EVENT_ROAM_SEARCH_STOPPED 18 // firmware has stopped searching for roam candidates (with reason =xx)
\r
89 #define WIFI_EVENT_CHANNEL_SWITCH_ANOUNCEMENT 20 // received channel switch anouncement from AP
\r
90 #define WIFI_EVENT_FW_EAPOL_FRAME_TRANSMIT_START 21 // fw start transmit eapol frame, with EAPOL index 1-4
\r
91 #define WIFI_EVENT_FW_EAPOL_FRAME_TRANSMIT_STOP 22 // fw gives up eapol frame, with rate, success/failure and number retries
\r
92 #define WIFI_EVENT_DRIVER_EAPOL_FRAME_TRANSMIT_REQUESTED 23 // kernel queue EAPOL for transmission in tdriver
\r
93 // with EAPOL index 1-4
\r
94 #define WIFI_EVENT_FW_EAPOL_FRAME_RECEIVED 24 // with rate, regardless of the fact that EAPOL frame
\r
95 // is accepted or rejected by firmware
\r
96 #define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has received
\r
97 // EAPOL frame and will queue it up to wpa_supplicant
\r
98 #define WIFI_EVENT_BLOCK_ACK_NEGOTIATION_COMPLETE 27 // with success/failure, parameters
\r
99 #define WIFI_EVENT_BT_COEX_BT_SCO_START 28
\r
100 #define WIFI_EVENT_BT_COEX_BT_SCO_STOP 29
\r
101 #define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc..., when BT starts transmiting
\r
102 // twice per BT slot
\r
103 #define WIFI_EVENT_BT_COEX_BT_SCAN_STOP 31
\r
104 #define WIFI_EVENT_BT_COEX_BT_HID_START 32
\r
105 #define WIFI_EVENT_BT_COEX_BT_HID_STOP 33
\r
106 #define WIFI_EVENT_ROAM_AUTH_STARTED 34 // firmware sends auth frame in roaming to next candidate
\r
107 #define WIFI_EVENT_ROAM_AUTH_COMPLETE 35 // firmware receive auth confirm from ap
\r
108 #define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in
\r
109 // roaming to next candidate
\r
110 #define WIFI_EVENT_ROAM_ASSOC_COMPLETE 37 // firmware receive assoc/reassoc confirm from ap
\r
114 // Parameters of wifi logger events are TLVs
\r
115 // Event parameters tags are defined as:
\r
116 #define WIFI_TAG_VENDOR_SPECIFIC 0 // take a byte stream as parameter
\r
117 #define WIFI_TAG_BSSID 1 // takes a 6 bytes MAC address as parameter
\r
118 #define WIFI_TAG_ADDR 2 // takes a 6 bytes MAC address as parameter
\r
119 #define WIFI_TAG_SSID 3 // takes a 32 bytes SSID address as parameter
\r
120 #define WIFI_TAG_STATUS 4 // takes an integer as parameter
\r
121 #define WIFI_TAG_CHANNEL_SPEC 5 // takes one or more wifi_channel_spec as parameter
\r
122 #define WIFI_TAG_WAKE_LOCK_EVENT 6 // takes a wake_lock_event struct as parameter
\r
123 #define WIFI_TAG_ADDR1 7 // takes a 6 bytes MAC address as parameter
\r
124 #define WIFI_TAG_ADDR2 8 // takes a 6 bytes MAC address as parameter
\r
125 #define WIFI_TAG_ADDR3 9 // takes a 6 bytes MAC address as parameter
\r
126 #define WIFI_TAG_ADDR4 10 // takes a 6 bytes MAC address as parameter
\r
127 #define WIFI_TAG_TSF 11 // take a 64 bits TSF value as parameter
\r
128 #define WIFI_TAG_IE 12 // take one or more specific 802.11 IEs parameter, IEs are in turn indicated
\r
129 // in TLV format as per 802.11 spec
\r
130 #define WIFI_TAG_INTERFACE 13 // take interface name as parameter
\r
131 #define WIFI_TAG_REASON_CODE 14 // take a reason code as per 802.11 as parameter
\r
132 #define WIFI_TAG_RATE_MBPS 15 // take a wifi rate in 0.5 mbps
\r
136 u16 length; // length of value
\r
138 } __attribute__((packed)) tlv_log;
\r
142 tlv_log tlvs[0]; // separate parameter structure per event to be provided and optional data
\r
143 // the event_data is expected to include an official android part, with some
\r
144 // parameter as transmit rate, num retries, num scan result found etc...
\r
145 // as well, event_data can include a vendor proprietary part which is
\r
146 // understood by the developer only.
\r
147 } __attribute__((packed)) wifi_ring_buffer_driver_connectivity_event;
\r
150 // Ring buffer name for power events ring. note that power event are extremely frequents
\r
151 // and thus should be stored in their own ring/file so as not to clobber connectivity events
\r
154 int status; // 0 taken, 1 released
\r
155 int reason; // reason why this wake lock is taken
\r
156 char name[0]; // null terminated
\r
157 } __attribute__((packed)) wake_lock_event;
\r
162 } __attribute__((packed)) wifi_power_event;
\r
165 * This structure represent a logger entry within a ring buffer.
\r
166 * Wifi driver are responsible to manage the ring buffer and write the debug
\r
167 * information into those rings.
\r
169 * In general, the debug entries can be used to store meaningful 802.11 information (SME, MLME,
\r
170 * connection and packet statistics) as well as vendor proprietary data that is specific to a
\r
171 * specific driver or chipset.
\r
172 * Binary entries can be used so as to store packet data or vendor specific information and
\r
173 * will be treated as blobs of data by android.
\r
175 * A user land process will be started by framework so as to periodically retrieve the
\r
176 * data logged by drivers into their ring buffer, store the data into log files and include
\r
177 * the logs into android bugreports.
\r
180 RING_BUFFER_ENTRY_FLAGS_HAS_BINARY = (1 << (0)), // set for binary entries
\r
181 RING_BUFFER_ENTRY_FLAGS_HAS_TIMESTAMP = (1 << (1)) // set if 64 bits timestamp is present
\r
185 ENTRY_TYPE_CONNECT_EVENT = 1,
\r
187 ENTRY_TYPE_WAKE_LOCK,
\r
188 ENTRY_TYPE_POWER_EVENT,
\r
193 u16 entry_size; // the size of payload excluding the header.
\r
195 u8 type; // Entry type
\r
196 u64 timestamp; //present if has_timestamp bit is set.
\r
197 } __attribute__((packed)) wifi_ring_buffer_entry;
\r
199 #define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES 0x00000001 // set if binary entries are present
\r
200 #define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRIES 0x00000002 // set if ascii entries are present
\r
202 /* ring buffer params */
\r
204 * written_bytes and read_bytes implement a producer consumer API
\r
205 * hence written_bytes >= read_bytes
\r
206 * a modulo arithmetic of the buffer size has to be applied to those counters:
\r
207 * actual offset into ring buffer = written_bytes % ring_buffer_byte_size
\r
213 wifi_ring_buffer_id ring_id; // unique integer representing the ring
\r
214 u32 ring_buffer_byte_size; // total memory size allocated for the buffer
\r
215 u32 verbose_level; //
\r
216 u32 written_bytes; // number of bytes that was written to the buffer by driver, monotonously increasing integer
\r
217 u32 read_bytes; // number of bytes that was read from the buffer by user land, monotonously increasing integer
\r
218 u32 written_records; // number of records that was written to the buffer by driver, monotonously increasing integer
\r
220 } wifi_ring_buffer_status;
\r
223 * Callback for reporting ring data
\r
225 * The ring buffer data collection is event based:
\r
226 * - driver calls on_ring_buffer_data when new records are available, the wifi_ring_buffer_status
\r
227 * passed up to framework in the call back indicates to framework if more data is available in
\r
228 * the ring buffer. It is not expected that driver will necessarily always empty the ring
\r
229 * immediately as data is available, instead driver will report data every X seconds or if
\r
230 * N bytes are available.
\r
231 * - in the case where a bug report has to be captured, framework will require driver to upload
\r
232 * all data immediately. This is indicated to driver when framework calls wifi_get_ringdata.
\r
233 * When framework calls wifi_get_ring_data, driver will start sending all available data in the
\r
234 * indicated ring by repeatedly invoking the on_ring_buffer_data callback
\r
236 * The callback is called by driver whenever new data is
\r
239 void (*on_ring_buffer_data) (char *ring_name, char *buffer, int buffer_size,
\r
240 wifi_ring_buffer_status *status);
\r
241 } wifi_ring_buffer_data_handler;
\r
243 /* api to set the log handler for getting ring data */
\r
244 wifi_error wifi_set_log_handler(wifi_request_id id, wifi_interface_handle iface,
\r
245 wifi_ring_buffer_data_handler handler);
\r
247 /* api to reset the log handler */
\r
248 wifi_error wifi_reset_log_handler(wifi_request_id id, wifi_interface_handle iface);
\r
252 void (*on_alert) (wifi_request_id id, char *buffer, int buffer_size, int err_code);
\r
253 } wifi_alert_handler;
\r
255 /* api to set the alert handler for the alert case in Wi-Fi Chip */
\r
256 wifi_error wifi_set_alert_handler(wifi_request_id id, wifi_interface_handle iface,
\r
257 wifi_alert_handler handler);
\r
260 /* api to reset the alert handler */
\r
261 wifi_error wifi_reset_alert_handler(wifi_request_id id, wifi_interface_handle iface);
\r
264 /* api for framework to indicate driver has to upload and drain all data of a given ring */
\r
265 wifi_error wifi_get_ring_data(wifi_interface_handle iface, char *ring_name);
\r
269 * API to trigger the debug collection.
\r
270 * Unless his API is invoked - logging is not triggered.
\r
271 * - verbose_level 0 corresponds to no collection
\r
272 * - verbose_level 1 correspond to normal log level, with minimal user impact. this is the default value
\r
273 * - verbose_level 2 are enabled when user is lazily trying to reproduce a problem, wifi performances and power
\r
274 * can be impacted but device should not otherwise be significantly impacted
\r
275 * - verbose_level 3+ are used when trying to actively debug a problem
\r
277 * ring_name represent the name of the ring for which data collection shall start.
\r
279 * flags: TBD parameter used to enable/disable specific events on a ring
\r
280 * max_interval: maximum interval in seconds for driver to invoke on_ring_buffer_data, ignore if zero
\r
281 * min_data_size: minimum data size in buffer for driver to invoke on_ring_buffer_data, ignore if zero
\r
284 wifi_error wifi_start_logging(wifi_interface_handle iface, u32 verbose_level, u32 flags,
\r
285 u32 max_interval_sec, u32 min_data_size, char *ring_name);
\r
287 /* api to get the status of all ring buffers supported by driver */
\r
288 wifi_error wifi_get_ring_buffers_status(wifi_interface_handle iface, u32 *num_rings,
\r
289 wifi_ring_buffer_status **status);
\r
292 void (*on_firmware_memory_dump) (char *buffer, int buffer_size);
\r
293 } wifi_firmware_memory_dump_handler;
\r
296 /* api to collect a firmware memory dump for a given iface */
\r
297 wifi_error wifi_get_firmware_memory_dump(wifi_interface_handle iface,
\r
298 wifi_firmware_memory_dump_handler handler);
\r
300 /* api to collect a firmware version string */
\r
301 wifi_error wifi_get_firmware_version(wifi_interface_handle iface, char **buffer, int *buffer_size);
\r
303 /* api to collect a driver version string */
\r
304 wifi_error wifi_get_driver_version(wifi_interface_handle iface, char **buffer, int *buffer_size);
\r
309 WIFI_LOGGER_MEMORY_DUMP_SUPPORTED = (1 << (0)), // Memory dump of FW
\r
310 WIFI_LOGGER_PER_PACKET_TX_RX_STATUS_SUPPORTED = (1 << (1)), // PKT status
\r
311 WIFI_LOGGER_CONNECT_EVENT_SUPPORTED = (1 << (2)), // Connectivity event
\r
312 WIFI_LOGGER_POWER_EVENT_SUPPORTED = (1 << (3)), // POWER of Driver
\r
313 WIFI_LOGGER_WAKE_LOCK_SUPPORTED = (1 << (4)), // WAKE LOCK of Driver
\r
314 WIFI_LOGGER_VERBOSE_SUPPORTED = (1 << (5)), // verbose log of FW
\r
315 WIFI_LOGGER_WATCHDOG_TIMER_SUPPORTED = (1 << (6)) // monitor the health of FW
\r
317 wifi_error wifi_get_logger_supported_feature_set(wifi_interface_handle iface, unsigned int *support);
\r
322 #endif /* __cplusplus */
\r
324 #endif /*__WIFI_HAL_STATS_ */
\r