From 47fb7ab9d086fd23ecbd5485a0101345eb14353e Mon Sep 17 00:00:00 2001 From: Pierre Vandwalle Date: Tue, 10 Mar 2015 18:17:18 -0700 Subject: [PATCH] additional HAL APIs Change-Id: I8a62e58b869fdbc8e8b3b4d50d04f0c4c015d103 --- include/hardware_legacy/link_layer_stats.h | 15 --- include/hardware_legacy/wifi_hal.h | 23 ++++ include/hardware_legacy/wifi_logger.h | 144 +++++++++++++++++---- 3 files changed, 142 insertions(+), 40 deletions(-) diff --git a/include/hardware_legacy/link_layer_stats.h b/include/hardware_legacy/link_layer_stats.h index 172c73e..c6202ad 100644 --- a/include/hardware_legacy/link_layer_stats.h +++ b/include/hardware_legacy/link_layer_stats.h @@ -12,21 +12,6 @@ extern "C" #define STATS_MINOR_VERSION 0 #define STATS_MICRO_VERSION 0 -typedef int wifi_radio; -typedef int wifi_channel; - -/* channel operating width */ -typedef enum { - WIFI_CHAN_WIDTH_20 = 0, - WIFI_CHAN_WIDTH_40 = 1, - WIFI_CHAN_WIDTH_80 = 2, - WIFI_CHAN_WIDTH_160 = 3, - WIFI_CHAN_WIDTH_80P80 = 4, - WIFI_CHAN_WIDTH_5 = 5, - WIFI_CHAN_WIDTH_10 = 6, - WIFI_CHAN_WIDTH_INVALID = -1 -} wifi_channel_width; - typedef enum { WIFI_DISCONNECTED = 0, WIFI_AUTHENTICATING = 1, diff --git a/include/hardware_legacy/wifi_hal.h b/include/hardware_legacy/wifi_hal.h index be4e985..2f14526 100644 --- a/include/hardware_legacy/wifi_hal.h +++ b/include/hardware_legacy/wifi_hal.h @@ -19,6 +19,29 @@ #include +/* WiFi Common definitions */ +/* channel operating width */ +typedef enum { + WIFI_CHAN_WIDTH_20 = 0, + WIFI_CHAN_WIDTH_40 = 1, + WIFI_CHAN_WIDTH_80 = 2, + WIFI_CHAN_WIDTH_160 = 3, + WIFI_CHAN_WIDTH_80P80 = 4, + WIFI_CHAN_WIDTH_5 = 5, + WIFI_CHAN_WIDTH_10 = 6, + WIFI_CHAN_WIDTH_INVALID = -1 +} wifi_channel_width; + +typedef int wifi_radio; +typedef int wifi_channel; + +typedef struct { + wifi_channel_width width; + int center_frequency0; + int center_frequency1; + int primary_frequency; +} wifi_channel_spec; + typedef enum { WIFI_SUCCESS = 0, WIFI_ERROR_NONE = 0, diff --git a/include/hardware_legacy/wifi_logger.h b/include/hardware_legacy/wifi_logger.h index 4e41c42..2880eb8 100644 --- a/include/hardware_legacy/wifi_logger.h +++ b/include/hardware_legacy/wifi_logger.h @@ -12,6 +12,27 @@ extern "C" #define LOGGER_MINOR_VERSION 0 #define LOGGER_MICRO_VERSION 0 + + +/** + * WiFi logger life cycle is as follow: + * + * - at initialization time, framework will call wifi_get_ring_buffers_status so as to obtain the + * names and list of supported buffers + * - when WiFi operation start framework will call wifi_start_logging so as to trigger log collection + * - Developper UI will provide an option to the user, so as it can set the verbose level of individual buffer + * as reported by wifi_get_ring_buffers_status + * - during wifi operations, driver will periodically report per ring data to framework by invoking the + * on_ring_buffer_data call back + * - when capturing a bug report, framework will indicate to driver that all the data has to be uploaded, + * urgently, by calling wifi_get_ring_data + * + * The data uploaded by driver will be stored by framework in separate files, with one stream of file per ring. + * Framework will store the files in pcapng format, allowing for easy merging and parsing with network + * analyzer tools. + */ + + typedef int wifi_radio; typedef int wifi_ring_buffer_id; @@ -70,31 +91,78 @@ typedef struct { // with EAPOL index 1-4 #define WIFI_EVENT_FW_EAPOL_FRAME_RECEIVED 24 // with rate, regardless of the fact that EAPOL frame // is accepted or rejected by firmware -#define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has received EAPOL - //frame and will queue it up to wpa_supplicant +#define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has received + // EAPOL frame and will queue it up to wpa_supplicant #define WIFI_EVENT_BLOCK_ACK_NEGOTIATION_COMPLETE 27 // with success/failure, parameters #define WIFI_EVENT_BT_COEX_BT_SCO_START 28 #define WIFI_EVENT_BT_COEX_BT_SCO_STOP 29 -#define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc..., when BT starts transmiting twice per BT slot +#define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc..., when BT starts transmiting + // twice per BT slot #define WIFI_EVENT_BT_COEX_BT_SCAN_STOP 31 #define WIFI_EVENT_BT_COEX_BT_HID_START 32 #define WIFI_EVENT_BT_COEX_BT_HID_STOP 33 #define WIFI_EVENT_ROAM_AUTH_STARTED 34 // firmware sends auth frame in roaming to next candidate #define WIFI_EVENT_ROAM_AUTH_COMPLETE 35 // firmware receive auth confirm from ap -#define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in roaming to next candidate +#define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in + // roaming to next candidate #define WIFI_EVENT_ROAM_ASSOC_COMPLETE 37 // firmware receive assoc/reassoc confirm from ap + +// Parameters of wifi logger events are TLVs +// Event parameters tags are defined as: +#define WIFI_TAG_VENDOR_SPECIFIC 0 // take a byte stream as parameter +#define WIFI_TAG_BSSID 1 // takes a 6 bytes MAC address as parameter +#define WIFI_TAG_ADDR 2 // takes a 6 bytes MAC address as parameter +#define WIFI_TAG_SSID 3 // takes a 32 bytes SSID address as parameter +#define WIFI_TAG_STATUS 4 // takes an integer as parameter +#define WIFI_TAG_CHANNEL_SPEC 5 // takes one or more wifi_channel_spec as parameter +#define WIFI_TAG_WAKE_LOCK_EVENT 6 // takes a wake_lock_event struct as parameter +#define WIFI_TAG_ADDR1 7 // takes a 6 bytes MAC address as parameter +#define WIFI_TAG_ADDR2 8 // takes a 6 bytes MAC address as parameter +#define WIFI_TAG_ADDR3 9 // takes a 6 bytes MAC address as parameter +#define WIFI_TAG_ADDR4 10 // takes a 6 bytes MAC address as parameter +#define WIFI_TAG_TSF 11 // take a 64 bits TSF value as parameter +#define WIFI_TAG_IE 12 // take one or more specific 802.11 IEs parameter, IEs are in turn indicated + // in TLV format as per 802.11 spec +#define WIFI_TAG_INTERFACE 13 // take interface name as parameter +#define WIFI_TAG_REASON_CODE 14 // take a reason code as per 802.11 as parameter +#define WIFI_TAG_RATE_MBPS 15 // take a wifi rate in 0.5 mbps + +typedef struct { + u16 tag; + u16 length; // length of value + u8 value[0]; +} tlv_log; + typedef struct { u16 event; - u8 event_data[0]; // separate parameter structure per event to be provided and optional data - // the event_data is expected to include an official android part, with some parameter - // as transmit rate, num retries, num scan result found etc... - // as well, event_data can include a vendor proprietary part which is understood - // by the developer only. + tlv_log tlvs[0]; // separate parameter structure per event to be provided and optional data + // the event_data is expected to include an official android part, with some + // parameter as transmit rate, num retries, num scan result found etc... + // as well, event_data can include a vendor proprietary part which is + // understood by the developer only. } wifi_ring_buffer_driver_connectivity_event; -static char connectivity_event_ring_name[] = "wifi_connectivity_events"; //ring buffer name for connectivity events ring +// Ring buffer name for connectivity events ring +static char connectivity_event_ring_name[] = "wifi_connectivity_events"; + +// Ring buffer name for power events ring. note that power event are extremely frequents +// and thus should be stored in their own ring/file so as not to clobber connectivity events + +typedef struct { + int status; // 0 taken, 1 released + int reason; // reason why this wake lock is taken + char name[0]; // null terminated +} wake_lock_event; + +typedef struct { + u16 event; + tlv_log tlvs[0]; +} wifi_power_event; + +static char power_event_ring_name[] = "wifi_power_events"; + /** * This structure represent a logger entry within a ring buffer. @@ -122,11 +190,12 @@ typedef struct { union { u8 data[0]; wifi_ring_buffer_driver_connectivity_event connectivity_event; + wifi_ring_per_packet_status_entry packet_status; }; } wifi_ring_buffer_entry; -#define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES 0x00000001 // set if binary entries are present -#define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRIES 0x00000002 // set if ascii entries are present +#define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES 0x00000001 // set if binary entries are present +#define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRI 0x00000002 // set if ascii entries are present /* ring buffer params */ /** @@ -146,24 +215,53 @@ typedef struct { u32 read_bytes; // number of bytes that was read from the buffer by user land, monotonously increasing integer } wifi_ring_buffer_status; +/** + * Callback for reporting ring data + * + * The ring buffer data collection is event based: + * - driver calls on_ring_buffer_data when new records are available, the wifi_ring_buffer_status + * passed up to framework in the call back indicates to framework if more data is available in + * the ring buffer. It is not expected that driver will necessarily always empty the ring + * immediately as data is available, instead driver will report data every X seconds or if + * N bytes are available. + * - in the case where a bug report has to be captured, framework will require driver to upload + * all data immediately. This is indicated to driver when framework calls wifi_get_ringdata. + * When framework calls wifi_get_ring_data, driver will start sending all available data in the + * indicated ring by repeatedly invoking the on_ring_buffer_data callback + * + * The callback is called by driver whenever new data is + */ +typedef struct { + void (*on_ring_buffer_data) (wifi_request_id id, wifi_ring_buffer_id ring_id, char *buffer, int buffer_size, wifi_ring_buffer_status *status); +} wifi_ring_buffer_data_handler; + + +/* api for framework to indicate driver has to upload and drain all data of a given ring */ +wifi_error wifi_get_ring_data(wifi_request_id id, + wifi_interface_handle iface, wifi_ring_buffer_id ring_id); + + /** * API to trigger the debug collection. * Unless his API is invoked - logging is not triggered. * - verbose_level 0 corresponds to no collection - * - verbose_level 1+ are TBD, with increasing level of logging + * - verbose_level 1 correspond to normal log level, with minimal user impact. this is the default value + * - verbose_level 2 are enabled when user is lazily trying to reproduce a problem, wifi performances and power + * can be impacted but device should not otherwise be significantly impacted + * - verbose_level 3+ are used when trying to actively debug a problem * * buffer_name represent the name of the ring for which data collection shall start. + * + * flags: TBD parameter used to enable/disable specific events on a ring + * max_interval: maximum interval in seconds for driver to invoke on_ring_buffer_data, ignore if zero + * min_data_size: minimum data size in buffer for driver to invoke on_ring_buffer_data, ignore if zero */ -wifi_error wifi_set_logging_level(wifi_interface_handle iface, u32 verbose_level, u8 * buffer_name); -/* callback for reporting ring buffer status */ -typedef struct { - void (*on_ring_buffer_status_results) (wifi_request_id id, u32 num_buffers, wifi_ring_buffer_status *status); -} wifi_ring_buffer_status_result_handler; +wifi_error wifi_start_logging(wifi_interface_handle iface, u32 verbose_level, u32 flags, u32 max_interval_sec, u32 min_data_size, u8 *buffer_name, wifi_ring_buffer_data_handler handler); -/* api to get the status of a ring buffer */ -wifi_error wifi_get_ring_buffer_status(wifi_request_id id, - wifi_interface_handle iface, wifi_ring_buffer_id ring_id, wifi_ring_buffer_status_result_handler handler); +/* api to get the status of all ring buffers supported by driver */ +wifi_error wifi_get_ring_buffers_status(wifi_request_id id, + wifi_interface_handle iface, u32 num_buffers, wifi_ring_buffer_status *status); /* api to collect a firmware memory dump for a given iface */ wifi_error wifi_get_firmware_memory_dump(wifi_request_id id, @@ -177,10 +275,6 @@ wifi_error wifi_get_firmware_version(wifi_request_id id, wifi_error wifi_get_driver_version(wifi_request_id id, wifi_interface_handle iface, char * buffer, int buffer_size); -/* api to collect driver records */ -wifi_error wifi_get_ringdata(wifi_request_id id, - wifi_interface_handle iface, wifi_ring_buffer_id ring_id); - /* Feature set */ #define WIFI_LOGGER_MEMORY_DUMP_SUPPORTED 1 #define WIFI_LOGGER_PER_PACKET_TX_RX_STATUS_SUPPORTED 2