• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 #include "wifi_hal.h"
2 
3 #ifndef __WIFI_HAL_STATS_H
4 #define __WIFI_HAL_STATS_H
5 
6 #ifdef __cplusplus
7 extern "C"
8 {
9 #endif /* __cplusplus */
10 
11 #define STATS_MAJOR_VERSION      1
12 #define STATS_MINOR_VERSION      0
13 #define STATS_MICRO_VERSION      0
14 
15 typedef enum {
16     WIFI_DISCONNECTED = 0,
17     WIFI_AUTHENTICATING = 1,
18     WIFI_ASSOCIATING = 2,
19     WIFI_ASSOCIATED = 3,
20     WIFI_EAPOL_STARTED = 4,   // if done by firmware/driver
21     WIFI_EAPOL_COMPLETED = 5, // if done by firmware/driver
22 } wifi_connection_state;
23 
24 typedef enum {
25     WIFI_ROAMING_IDLE = 0,
26     WIFI_ROAMING_ACTIVE = 1,
27 } wifi_roam_state;
28 
29 typedef enum {
30     WIFI_INTERFACE_STA = 0,
31     WIFI_INTERFACE_SOFTAP = 1,
32     WIFI_INTERFACE_IBSS = 2,
33     WIFI_INTERFACE_P2P_CLIENT = 3,
34     WIFI_INTERFACE_P2P_GO = 4,
35     WIFI_INTERFACE_NAN = 5,
36     WIFI_INTERFACE_MESH = 6,
37     WIFI_INTERFACE_UNKNOWN = -1
38  } wifi_interface_mode;
39 
40 #define WIFI_CAPABILITY_QOS          0x00000001     // set for QOS association
41 #define WIFI_CAPABILITY_PROTECTED    0x00000002     // set for protected association (802.11 beacon frame control protected bit set)
42 #define WIFI_CAPABILITY_INTERWORKING 0x00000004     // set if 802.11 Extended Capabilities element interworking bit is set
43 #define WIFI_CAPABILITY_HS20         0x00000008     // set for HS20 association
44 #define WIFI_CAPABILITY_SSID_UTF8    0x00000010     // set is 802.11 Extended Capabilities element UTF-8 SSID bit is set
45 #define WIFI_CAPABILITY_COUNTRY      0x00000020     // set is 802.11 Country Element is present
46 
47 typedef struct {
48    wifi_interface_mode mode;     // interface mode
49    u8 mac_addr[6];               // interface mac address (self)
50    wifi_connection_state state;  // connection state (valid for STA, CLI only)
51    wifi_roam_state roaming;      // roaming state
52    u32 capabilities;             // WIFI_CAPABILITY_XXX (self)
53    u8 ssid[33];                  // null terminated SSID
54    u8 bssid[6];                  // bssid
55    u8 ap_country_str[3];         // country string advertised by AP
56    u8 country_str[3];            // country string for this association
57 } wifi_interface_link_layer_info;
58 
59 /* channel information */
60 typedef struct {
61    wifi_channel_width width;   // channel width (20, 40, 80, 80+80, 160)
62    wifi_channel center_freq;   // primary 20 MHz channel
63    wifi_channel center_freq0;  // center frequency (MHz) first segment
64    wifi_channel center_freq1;  // center frequency (MHz) second segment
65 } wifi_channel_info;
66 
67 /* wifi rate */
68 typedef struct {
69    u32 preamble   :3;   // 0: OFDM, 1:CCK, 2:HT 3:VHT 4..7 reserved
70    u32 nss        :2;   // 0:1x1, 1:2x2, 3:3x3, 4:4x4
71    u32 bw         :3;   // 0:20MHz, 1:40Mhz, 2:80Mhz, 3:160Mhz
72    u32 rateMcsIdx :8;   // OFDM/CCK rate code would be as per ieee std in the units of 0.5mbps
73                         // HT/VHT it would be mcs index
74    u32 reserved  :16;   // reserved
75    u32 bitrate;         // units of 100 Kbps
76 } wifi_rate;
77 
78 /* channel statistics */
79 typedef struct {
80    wifi_channel_info channel;  // channel
81    u32 on_time;                // msecs the radio is awake (32 bits number accruing over time)
82    u32 cca_busy_time;          // msecs the CCA register is busy (32 bits number accruing over time)
83 } wifi_channel_stat;
84 
85 /* radio statistics */
86 typedef struct {
87    wifi_radio radio;               // wifi radio (if multiple radio supported)
88    u32 on_time;                    // msecs the radio is awake (32 bits number accruing over time)
89    u32 tx_time;                    // msecs the radio is transmitting (32 bits number accruing over time)
90    u32 rx_time;                    // msecs the radio is in active receive (32 bits number accruing over time)
91    u32 on_time_scan;               // msecs the radio is awake due to all scan (32 bits number accruing over time)
92    u32 on_time_nbd;                // msecs the radio is awake due to NAN (32 bits number accruing over time)
93    u32 on_time_gscan;              // msecs the radio is awake due to G?scan (32 bits number accruing over time)
94    u32 on_time_roam_scan;          // msecs the radio is awake due to roam?scan (32 bits number accruing over time)
95    u32 on_time_pno_scan;           // msecs the radio is awake due to PNO scan (32 bits number accruing over time)
96    u32 on_time_hs20;               // msecs the radio is awake due to HS2.0 scans and GAS exchange (32 bits number accruing over time)
97    u32 num_channels;               // number of channels
98    wifi_channel_stat channels[];   // channel statistics
99 } wifi_radio_stat;
100 
101 /**
102  * Packet statistics reporting by firmware is performed on MPDU basi (i.e. counters increase by 1 for each MPDU)
103  * As well, "data packet" in associated comments, shall be interpreted as 802.11 data packet,
104  * that is, 802.11 frame control subtype == 2 and excluding management and control frames.
105  *
106  * As an example, in the case of transmission of an MSDU fragmented in 16 MPDUs which are transmitted
107  * OTA in a 16 units long a-mpdu, for which a block ack is received with 5 bits set:
108  *          tx_mpdu : shall increase by 5
109  *          retries : shall increase by 16
110  *          tx_ampdu : shall increase by 1
111  * data packet counters shall not increase regardless of the number of BAR potentially sent by device for this a-mpdu
112  * data packet counters shall not increase regardless of the number of BA received by device for this a-mpdu
113  *
114  * For each subsequent retransmission of the 11 remaining non ACK'ed mpdus
115  * (regardless of the fact that they are transmitted in a-mpdu or not)
116  *          retries : shall increase by 1
117  *
118  * If no subsequent BA or ACK are received from AP, until packet lifetime expires for those 11 packet that were not ACK'ed
119  *          mpdu_lost : shall increase by 11
120  */
121 
122 /* per rate statistics */
123 typedef struct {
124    wifi_rate rate;     // rate information
125    u32 tx_mpdu;        // number of successfully transmitted data pkts (ACK rcvd)
126    u32 rx_mpdu;        // number of received data pkts
127    u32 mpdu_lost;      // number of data packet losses (no ACK)
128    u32 retries;        // total number of data pkt retries
129    u32 retries_short;  // number of short data pkt retries
130    u32 retries_long;   // number of long data pkt retries
131 } wifi_rate_stat;
132 
133 /* access categories */
134 typedef enum {
135    WIFI_AC_VO  = 0,
136    WIFI_AC_VI  = 1,
137    WIFI_AC_BE  = 2,
138    WIFI_AC_BK  = 3,
139    WIFI_AC_MAX = 4,
140 } wifi_traffic_ac;
141 
142 /* wifi peer type */
143 typedef enum
144 {
145    WIFI_PEER_STA,
146    WIFI_PEER_AP,
147    WIFI_PEER_P2P_GO,
148    WIFI_PEER_P2P_CLIENT,
149    WIFI_PEER_NAN,
150    WIFI_PEER_TDLS,
151    WIFI_PEER_INVALID,
152 } wifi_peer_type;
153 
154 /* per peer statistics */
155 typedef struct {
156    wifi_peer_type type;           // peer type (AP, TDLS, GO etc.)
157    u8 peer_mac_address[6];        // mac address
158    u32 capabilities;              // peer WIFI_CAPABILITY_XXX
159    u32 num_rate;                  // number of rates
160    wifi_rate_stat rate_stats[];   // per rate statistics, number of entries  = num_rate
161 } wifi_peer_info;
162 
163 /* Per access category statistics */
164 typedef struct {
165    wifi_traffic_ac ac;             // access category (VI, VO, BE, BK)
166    u32 tx_mpdu;                    // number of successfully transmitted unicast data pkts (ACK rcvd)
167    u32 rx_mpdu;                    // number of received unicast data packets
168    u32 tx_mcast;                   // number of succesfully transmitted multicast data packets
169                                    // STA case: implies ACK received from AP for the unicast packet in which mcast pkt was sent
170    u32 rx_mcast;                   // number of received multicast data packets
171    u32 rx_ampdu;                   // number of received unicast a-mpdus; support of this counter is optional
172    u32 tx_ampdu;                   // number of transmitted unicast a-mpdus; support of this counter is optional
173    u32 mpdu_lost;                  // number of data pkt losses (no ACK)
174    u32 retries;                    // total number of data pkt retries
175    u32 retries_short;              // number of short data pkt retries
176    u32 retries_long;               // number of long data pkt retries
177    u32 contention_time_min;        // data pkt min contention time (usecs)
178    u32 contention_time_max;        // data pkt max contention time (usecs)
179    u32 contention_time_avg;        // data pkt avg contention time (usecs)
180    u32 contention_num_samples;     // num of data pkts used for contention statistics
181 } wifi_wmm_ac_stat;
182 
183 /* interface statistics */
184 typedef struct {
185    wifi_interface_handle iface;          // wifi interface
186    wifi_interface_link_layer_info info;  // current state of the interface
187    u32 beacon_rx;                        // access point beacon received count from connected AP
188    u64 average_tsf_offset;               // average beacon offset encountered (beacon_TSF - TBTT)
189                                          // The average_tsf_offset field is used so as to calculate the
190                                          // typical beacon contention time on the channel as well may be
191                                          // used to debug beacon synchronization and related power consumption issue
192    u32 leaky_ap_detected;                // indicate that this AP typically leaks packets beyond the driver guard time.
193    u32 leaky_ap_avg_num_frames_leaked;  // average number of frame leaked by AP after frame with PM bit set was ACK'ed by AP
194    u32 leaky_ap_guard_time;              // guard time currently in force (when implementing IEEE power management based on
195                                          // frame control PM bit), How long driver waits before shutting down the radio and
196                                          // after receiving an ACK for a data frame with PM bit set)
197    u32 mgmt_rx;                          // access point mgmt frames received count from connected AP (including Beacon)
198    u32 mgmt_action_rx;                   // action frames received count
199    u32 mgmt_action_tx;                   // action frames transmit count
200    wifi_rssi rssi_mgmt;                  // access Point Beacon and Management frames RSSI (averaged)
201    wifi_rssi rssi_data;                  // access Point Data Frames RSSI (averaged) from connected AP
202    wifi_rssi rssi_ack;                   // access Point ACK RSSI (averaged) from connected AP
203    wifi_wmm_ac_stat ac[WIFI_AC_MAX];     // per ac data packet statistics
204    u32 num_peers;                        // number of peers
205    wifi_peer_info peer_info[];           // per peer statistics
206 } wifi_iface_stat;
207 
208 /* configuration params */
209 typedef struct {
210    u32 mpdu_size_threshold;             // threshold to classify the pkts as short or long
211                                         // packet size < mpdu_size_threshold => short
212    u32 aggressive_statistics_gathering; // set for field debug mode. Driver should collect all statistics regardless of performance impact.
213 } wifi_link_layer_params;
214 
215 /* API to trigger the link layer statistics collection.
216    Unless his API is invoked - link layer statistics will not be collected.
217    Radio statistics (once started) do not stop or get reset unless wifi_clear_link_stats is invoked
218    Interface statistics (once started) reset and start afresh after each connection */
219 wifi_error wifi_set_link_stats(wifi_interface_handle iface, wifi_link_layer_params params);
220 
221 /* callback for reporting link layer stats */
222 typedef struct {
223   void (*on_link_stats_results) (wifi_request_id id, wifi_iface_stat *iface_stat,
224          int num_radios, wifi_radio_stat *radio_stat);
225 } wifi_stats_result_handler;
226 
227 /* api to collect the link layer statistics for a given iface and all the radio stats */
228 wifi_error wifi_get_link_stats(wifi_request_id id,
229         wifi_interface_handle iface, wifi_stats_result_handler handler);
230 
231 /* wifi statistics bitmap  */
232 #define WIFI_STATS_RADIO              0x00000001      // all radio statistics
233 #define WIFI_STATS_RADIO_CCA          0x00000002      // cca_busy_time (within radio statistics)
234 #define WIFI_STATS_RADIO_CHANNELS     0x00000004      // all channel statistics (within radio statistics)
235 #define WIFI_STATS_RADIO_SCAN         0x00000008      // all scan statistics (within radio statistics)
236 #define WIFI_STATS_IFACE              0x00000010      // all interface statistics
237 #define WIFI_STATS_IFACE_TXRATE       0x00000020      // all tx rate statistics (within interface statistics)
238 #define WIFI_STATS_IFACE_AC           0x00000040      // all ac statistics (within interface statistics)
239 #define WIFI_STATS_IFACE_CONTENTION   0x00000080      // all contention (min, max, avg) statistics (within ac statisctics)
240 
241 /* clear api to reset statistics, stats_clear_rsp_mask identifies what stats have been cleared
242    stop_req = 1 will imply whether to stop the statistics collection.
243    stop_rsp = 1 will imply that stop_req was honored and statistics collection was stopped.
244  */
245 wifi_error wifi_clear_link_stats(wifi_interface_handle iface,
246       u32 stats_clear_req_mask, u32 *stats_clear_rsp_mask, u8 stop_req, u8 *stop_rsp);
247 
248 #ifdef __cplusplus
249 }
250 #endif /* __cplusplus */
251 
252 #endif /*__WIFI_HAL_STATS_ */
253 
254