OSDN Git Service

adjust gscan and wifi_logger headers
[android-x86/hardware-libhardware_legacy.git] / include / hardware_legacy / wifi_logger.h
index a201b49..0f9ec0a 100644 (file)
@@ -12,16 +12,39 @@ extern "C"
 #define LOGGER_MINOR_VERSION      0\r
 #define LOGGER_MICRO_VERSION      0\r
 \r
+\r
+\r
+/**\r
+ * WiFi logger life cycle is as follow:\r
+ *\r
+ * - at initialization time, framework will call wifi_get_ring_buffers_status so as to obtain the\r
+ * names and list of supported buffers\r
+ * - when WiFi operation start framework will call wifi_start_logging so as to trigger log collection\r
+ * - Developper UI will provide an option to the user, so as it can set the verbose level of individual buffer\r
+ *    as reported by wifi_get_ring_buffers_status\r
+ * - during wifi operations, driver will periodically report per ring data to framework by invoking the\r
+ *    on_ring_buffer_data call back\r
+ * - when capturing a bug report, framework will indicate to driver that all the data has to be uploaded,\r
+ *   urgently, by calling wifi_get_ring_data\r
+ *\r
+ * The data uploaded by driver will be stored by framework in separate files, with one stream of file per ring.\r
+ * Framework will store the files in pcapng format, allowing for easy merging and parsing with network\r
+ * analyzer tools.\r
+ */\r
+\r
+\r
 typedef int wifi_radio;\r
 typedef int wifi_ring_buffer_id;\r
 \r
+#define PER_PACKET_ENTRY_FLAGS_DIRECTION_TX 1 //  0: TX, 1: RX\r
+#define PER_PACKET_ENTRY_FLAGS_TX_SUCCESS 2 // whether packet was transmitted or received/decrypted successfully\r
+#define PER_PACKET_ENTRY_FLAGS_80211_HEADER 4 // has full 802.11 header, else has 802.3 header\r
+#define PER_PACKET_ENTRY_FLAGS_PROTECTED 8  // whether packet was encrypted\r
+\r
 typedef struct {\r
-    u8 direction:1; //  0: TX, 1: RX\r
-    u8 success:1; // whether packet was transmitted or received/decrypted successfully\r
-    u8 has_80211_header:1; // has full 802.11 header, else has 802.3 header\r
-    u8 protected_packet:1; // whether packet was encrypted\r
-    u8 tid:4; // transmit  or received tid\r
-    u8 MCS; // modulation and bandwidth\r
+    u8 flags;\r
+    u8 tid; // transmit or received tid\r
+    u16 MCS; // modulation and bandwidth\r
     u8 rssi; // TX: RSSI of ACK for that packet\r
              // RX: RSSI of packet\r
     u8 num_retries; // number of attempted retries\r
@@ -39,9 +62,11 @@ typedef struct {
     u8 data[0]; // packet data. The length of packet data is determined by the entry_size field of\r
                 // the wifi_ring_buffer_entry structure. It is expected that first bytes of the\r
                 // packet, or packet headers only (up to TCP or RTP/UDP headers) will be copied into the ring\r
-} wifi_ring_per_packet_status_entry;\r
+} __attribute__((packed)) wifi_ring_per_packet_status_entry;\r
 \r
+static char per_packet_status_ring_name[] = "wifi_per_packet_status"; // Ring buffer name for per-packet status ring\r
 \r
+// Below events refer to the wifi_connectivity_event ring and shall be supported\r
 \r
 #define WIFI_EVENT_ASSOCIATION_REQUESTED 0 // driver receive association command from kernel\r
 #define WIFI_EVENT_AUTH_COMPLETE 1\r
@@ -69,30 +94,77 @@ typedef struct {
                                                             // with EAPOL index 1-4\r
 #define WIFI_EVENT_FW_EAPOL_FRAME_RECEIVED 24 // with rate, regardless of the fact that EAPOL frame\r
                                            // is accepted or rejected by firmware\r
-#define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has received EAPOL\r
-                                                    //frame and will queue it up to wpa_supplicant\r
+#define WIFI_EVENT_DRIVER_EAPOL_FRAME_RECEIVED 26 // with rate, and eapol index, driver has received\r
+                                                  // EAPOL frame and will queue it up to wpa_supplicant\r
 #define WIFI_EVENT_BLOCK_ACK_NEGOTIATION_COMPLETE 27 // with success/failure, parameters\r
 #define WIFI_EVENT_BT_COEX_BT_SCO_START 28\r
 #define WIFI_EVENT_BT_COEX_BT_SCO_STOP 29\r
-#define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc..., when BT starts transmiting twice per BT slot\r
+#define WIFI_EVENT_BT_COEX_BT_SCAN_START 30 // for paging/scan etc..., when BT starts transmiting\r
+                                            //    twice per BT slot\r
 #define WIFI_EVENT_BT_COEX_BT_SCAN_STOP 31\r
 #define WIFI_EVENT_BT_COEX_BT_HID_START 32\r
 #define WIFI_EVENT_BT_COEX_BT_HID_STOP 33\r
 #define WIFI_EVENT_ROAM_AUTH_STARTED 34 // firmware sends auth frame in roaming to next candidate\r
 #define WIFI_EVENT_ROAM_AUTH_COMPLETE 35 // firmware receive auth confirm from ap\r
-#define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in roaming to next candidate\r
+#define WIFI_EVENT_ROAM_ASSOC_STARTED 36 // firmware sends assoc/reassoc frame in\r
+                                         //     roaming to next candidate\r
 #define WIFI_EVENT_ROAM_ASSOC_COMPLETE 37 // firmware receive assoc/reassoc confirm from ap\r
 \r
 \r
+\r
+// Parameters of wifi logger events are TLVs\r
+// Event parameters tags are defined as:\r
+#define WIFI_TAG_VENDOR_SPECIFIC 0 // take a byte stream as parameter\r
+#define WIFI_TAG_BSSID 1 // takes a 6 bytes MAC address as parameter\r
+#define WIFI_TAG_ADDR 2 // takes a 6 bytes MAC address as parameter\r
+#define WIFI_TAG_SSID 3 // takes a 32 bytes SSID address as parameter\r
+#define WIFI_TAG_STATUS 4 // takes an integer as parameter\r
+#define WIFI_TAG_CHANNEL_SPEC 5 // takes one or more wifi_channel_spec as parameter\r
+#define WIFI_TAG_WAKE_LOCK_EVENT 6 // takes a wake_lock_event struct as parameter\r
+#define WIFI_TAG_ADDR1 7 // takes a 6 bytes MAC address as parameter\r
+#define WIFI_TAG_ADDR2 8 // takes a 6 bytes MAC address as parameter\r
+#define WIFI_TAG_ADDR3 9 // takes a 6 bytes MAC address as parameter\r
+#define WIFI_TAG_ADDR4 10 // takes a 6 bytes MAC address as parameter\r
+#define WIFI_TAG_TSF 11 // take a 64 bits TSF value as parameter\r
+#define WIFI_TAG_IE 12  // take one or more specific 802.11 IEs parameter, IEs are in turn indicated\r
+                        // in TLV format as per 802.11 spec\r
+#define WIFI_TAG_INTERFACE 13 // take interface name as parameter\r
+#define WIFI_TAG_REASON_CODE 14 // take a reason code as per 802.11 as parameter\r
+#define WIFI_TAG_RATE_MBPS 15 // take a wifi rate in 0.5 mbps\r
+\r
+typedef struct {\r
+    u16 tag;\r
+    u16 length; // length of value\r
+    u8 value[0];\r
+} __attribute__((packed)) tlv_log;\r
+\r
+typedef struct {\r
+    u16 event;\r
+    tlv_log tlvs[0];    // separate parameter structure per event to be provided and optional data\r
+                        // the event_data is expected to include an official android part, with some\r
+                        // parameter as transmit rate, num retries, num scan result found etc...\r
+                        // as well, event_data can include a vendor proprietary part which is\r
+                        // understood by the developer only.\r
+} __attribute__((packed)) wifi_ring_buffer_driver_connectivity_event;\r
+\r
+// Ring buffer name for connectivity events ring\r
+static char connectivity_event_ring_name[] = "wifi_connectivity_events";\r
+\r
+// Ring buffer name for power events ring. note that power event are extremely frequents\r
+// and thus should be stored in their own ring/file so as not to clobber connectivity events\r
+\r
+typedef struct {\r
+    int status;   // 0 taken, 1 released\r
+    int reason;   // reason why this wake lock is taken\r
+    char name[0]; // null terminated\r
+} __attribute__((packed)) wake_lock_event;\r
+\r
 typedef struct {\r
     u16 event;\r
-    u8 event_data[0]; // separate parameter structure per event to be provided and optional data\r
-                        // the event_data is expected to include an official android part, with some parameter\r
-                        // as transmit rate, num retries, num scan result found etc...\r
-                        // as well, event_data can include a vendor proprietary part which is understood\r
-                        // by the developer only.\r
-} wifi_ring_buffer_driver_connectivity_event;\r
+    tlv_log tlvs[0];\r
+} __attribute__((packed)) wifi_power_event;\r
 \r
+static char power_event_ring_name[] = "wifi_power_events";\r
 \r
 /**\r
  * This structure represent a logger entry within a ring buffer.\r
@@ -109,19 +181,25 @@ typedef struct {
  * data logged by drivers into their ring buffer, store the data into log files and include\r
  * the logs into android bugreports.\r
  */\r
+\r
+#define RING_BUFFER_ENTRY_FLAGS_HAS_BINARY 1 // set for binary entries\r
+#define RING_BUFFER_ENTRY_FLAGS_HAS_TIMESTAMP 2 // set if 64 bits timestamp is present\r
+\r
 typedef struct {\r
-    u16 entry_size:13;\r
-    u16 binary:1; //set for binary entries\r
-    u16 has_timestamp:1; //set if 64 bits timestamp is present\r
-    u16 reserved:1;\r
+    u16 entry_size;\r
+    u8 flags;\r
     u8 type; // Per ring specific\r
-    u8 resvd;\r
     u64 timestamp; //present if has_timestamp bit is set.\r
-    u8 data[0];\r
-} wifi_ring_buffer_entry;\r
+    union {\r
+        u8 data[0];\r
+        wifi_ring_buffer_driver_connectivity_event connectivity_event;\r
+        wifi_ring_per_packet_status_entry packet_status;\r
+        wifi_power_event power_event;\r
+        };\r
+} __attribute__((packed)) wifi_ring_buffer_entry;\r
 \r
-#define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES         0x00000001     // set if binary entries are present\r
-#define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRIES          0x00000002     // set if ascii entries are present\r
+#define WIFI_RING_BUFFER_FLAG_HAS_BINARY_ENTRIES 0x00000001     // set if binary entries are present\r
+#define WIFI_RING_BUFFER_FLAG_HAS_ASCII_ENTRIES  0x00000002     // set if ascii entries are present\r
 \r
 /* ring buffer params */\r
 /**\r
@@ -134,43 +212,79 @@ typedef struct {
 typedef struct {\r
    u8 name[32];\r
    u32 flags;\r
-   u64 fd; // linux file descriptor for that buffer\r
+   wifi_ring_buffer_id ring_id; // unique integer representing the ring\r
    u32 ring_buffer_byte_size;   // total memory size allocated for the buffer\r
    u32 verbose_level; //\r
    u32 written_bytes; // number of bytes that was written to the buffer by driver, monotonously increasing integer\r
    u32 read_bytes;  // number of bytes that was read from the buffer by user land, monotonously increasing integer\r
+   u32 written_records;  // number of records that was written to the buffer by driver, monotonously increasing integer\r
+\r
 } wifi_ring_buffer_status;\r
 \r
 /**\r
+ * Callback for reporting ring data\r
+ *\r
+ * The ring buffer data collection is event based:\r
+ *    - driver calls on_ring_buffer_data when new records are available, the wifi_ring_buffer_status\r
+ *      passed up to framework in the call back indicates to framework if more data is available in\r
+ *      the ring buffer. It is not expected that driver will necessarily always empty the ring\r
+ *      immediately as data is available, instead driver will report data every X seconds or if\r
+ *      N bytes are available.\r
+ *    - in the case where a bug report has to be captured, framework will require driver to upload\r
+ *      all data immediately. This is indicated to driver when framework calls wifi_get_ringdata.\r
+ *      When framework calls wifi_get_ring_data, driver will start sending all available data in the\r
+ *      indicated ring by repeatedly invoking the on_ring_buffer_data callback\r
+ *\r
+ * The callback is called by driver whenever new data is\r
+ */\r
+typedef struct {\r
+  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);\r
+} wifi_ring_buffer_data_handler;\r
+\r
+\r
+/* api for framework to indicate driver has to upload and drain all data of a given ring */\r
+wifi_error wifi_get_ring_data(wifi_request_id id,\r
+        wifi_interface_handle iface, wifi_ring_buffer_id ring_id);\r
+\r
+\r
+/**\r
  * API to trigger the debug collection.\r
  *  Unless his API is invoked - logging is not triggered.\r
- *  - verbose_level 0 corresponds to minimal or no collection\r
- *  - verbose_level 1+ are TBD\r
+ *  - verbose_level 0 corresponds to no collection\r
+ *  - verbose_level 1 correspond to normal log level, with minimal user impact. this is the default value\r
+ *  - verbose_level 2 are enabled when user is lazily trying to reproduce a problem, wifi performances and power\r
+ *     can be impacted but device should not otherwise be significantly impacted\r
+ *  - verbose_level 3+ are used when trying to actively debug a problem\r
  *\r
  * buffer_name represent the name of the ring for which data collection shall start.\r
+ *\r
+ * flags: TBD parameter used to enable/disable specific events on a ring\r
+ * max_interval: maximum interval in seconds for driver to invoke on_ring_buffer_data, ignore if zero\r
+ * min_data_size: minimum data size in buffer for driver to invoke on_ring_buffer_data, ignore if zero\r
  */\r
-wifi_error wifi_start_logging(wifi_interface_handle iface, u32 verbose_level, u8 * buffer_name);\r
 \r
-/* callback for reporting ring buffer status */\r
-typedef struct {\r
-  void (*on_ring_buffer_status_results) (wifi_request_id id, u32 num_buffers, wifi_ring_buffer_status *status);\r
-} wifi_ring_buffer_status_result_handler;\r
+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);\r
 \r
-/* api to get the status of a ring buffer */\r
-wifi_error wifi_get_ring_buffer_status(wifi_request_id id,\r
-        wifi_interface_handle iface, wifi_ring_buffer_id ring_id, wifi_ring_buffer_status_result_handler handler);\r
+/* api to get the status of all ring buffers supported by driver */\r
+wifi_error wifi_get_ring_buffers_status(wifi_request_id id,\r
+        wifi_interface_handle iface, u32 num_buffers, wifi_ring_buffer_status *status);\r
 \r
 /* api to collect a firmware memory dump for a given iface */\r
 wifi_error wifi_get_firmware_memory_dump(wifi_request_id id,\r
-        wifi_interface_handle iface, char * buffer, int buffer_size);\r
+        wifi_interface_handle iface, char ** buffer, int *buffer_size);\r
 \r
 /* api to collect a firmware version string */\r
 wifi_error wifi_get_firmware_version(wifi_request_id id,\r
-        wifi_interface_handle iface, char * buffer, int buffer_size);\r
+        wifi_interface_handle iface, char *buffer, int buffer_size);\r
 \r
 /* api to collect a driver version string */\r
 wifi_error wifi_get_driver_version(wifi_request_id id,\r
-        wifi_interface_handle iface, char * buffer, int buffer_size);\r
+        wifi_interface_handle iface, char *buffer, int buffer_size);\r
+\r
+\r
+/* api to collect driver records */\r
+wifi_error wifi_get_ringdata(wifi_request_id id,\r
+        wifi_interface_handle iface, wifi_ring_buffer_id ring_id);\r
 \r
 \r
 /* Feature set */\r