4 #ifndef __WIFI_HAL_GSCAN_H__
5 #define __WIFI_HAL_GSCAN_H__
10 WIFI_BAND_UNSPECIFIED,
11 WIFI_BAND_BG = 1, // 2.4 GHz
12 WIFI_BAND_A = 2, // 5 GHz without DFS
13 WIFI_BAND_A_DFS = 4, // 5 GHz DFS only
14 WIFI_BAND_A_WITH_DFS = 6, // 5 GHz with DFS
15 WIFI_BAND_ABG = 3, // 2.4 GHz + 5 GHz; no DFS
16 WIFI_BAND_ABG_WITH_DFS = 7, // 2.4 GHz + 5 GHz with DFS
19 const unsigned MAX_CHANNELS = 16;
20 const unsigned MAX_BUCKETS = 16;
21 const unsigned MAX_HOTLIST_APS = 128;
22 const unsigned MAX_SIGNIFICANT_CHANGE_APS = 64;
23 const unsigned MAX_PNO_SSID = 128;
25 wifi_error wifi_get_valid_channels(wifi_interface_handle handle,
26 int band, int max_channels, wifi_channel *channels, int *num_channels);
29 int max_scan_cache_size; // total space allocated for scan (in bytes)
30 int max_scan_buckets; // maximum number of channel buckets
31 int max_ap_cache_per_scan; // maximum number of APs that can be stored per scan
32 int max_rssi_sample_size; // number of RSSI samples used for averaging RSSI
33 int max_scan_reporting_threshold; // max possible report_threshold as described
34 // in wifi_scan_cmd_params
35 int max_hotlist_aps; // maximum number of entries for hotlist APs
36 int max_significant_wifi_change_aps; // maximum number of entries for
37 // significant wifi change APs
38 int max_bssid_history_entries; // number of BSSID/RSSI entries that device can hold
39 } wifi_gscan_capabilities;
41 wifi_error wifi_get_gscan_capabilities(wifi_interface_handle handle,
42 wifi_gscan_capabilities *capabilities);
45 WIFI_SCAN_BUFFER_FULL,
50 /* Format of information elements found in the beacon */
52 byte id; // element identifier
53 byte len; // number of bytes to follow
55 } wifi_information_element;
58 wifi_timestamp ts; // time since boot (in microsecond) when the result was
60 char ssid[32+1]; // null terminated
62 wifi_channel channel; // channel frequency in MHz
63 wifi_rssi rssi; // in db
64 wifi_timespan rtt; // in nanoseconds
65 wifi_timespan rtt_sd; // standard deviation in rtt
66 unsigned short beacon_period; // period advertised in the beacon
67 unsigned short capability; // capabilities advertised in the beacon
68 unsigned int ie_length; // size of the ie_data blob
69 char ie_data[1]; // blob of all the information elements found in the
70 // beacon; this data should be a packed list of
71 // wifi_information_element objects, one after the other.
76 /* reported when report_threshold is reached in scan cache */
77 void (*on_scan_results_available) (wifi_request_id id, unsigned num_results_available);
79 /* reported when each probe response is received, if report_events
80 * enabled in wifi_scan_cmd_params */
81 void (*on_full_scan_result) (wifi_request_id id, wifi_scan_result *result);
83 /* optional event - indicates progress of scanning statemachine */
84 void (*on_scan_event) (wifi_scan_event event, unsigned status);
86 } wifi_scan_result_handler;
89 wifi_channel channel; // frequency
90 int dwellTimeMs; // dwell time hint
91 int passive; // 0 => active, 1 => passive scan; ignored for DFS
92 /* Add channel class */
93 } wifi_scan_channel_spec;
97 int bucket; // bucket index, 0 based
98 wifi_band band; // when UNSPECIFIED, use channel list
99 int period; // desired period, in millisecond; if this is too
100 // low, the firmware should choose to generate results as
101 // fast as it can instead of failing the command.
102 // for exponential backoff bucket this is the min_period
103 /* report_events semantics -
104 * 0 => report only when scan history is % full
105 * 1 => same as 0 + report a scan completion event after scanning this bucket
106 * 2 => same as 1 + forward scan results (beacons/probe responses + IEs) in real time to HAL
107 * 3 => same as 2 + forward scan results (beacons/probe responses + IEs) in real time to
108 supplicant as well (optional) .
111 int max_period; // if max_period is non zero or different than period, then this bucket is
112 // an exponential backoff bucket and the scan period will grow exponentially
113 // as per formula: actual_period(N) = period ^ (N/(step_count+1))
114 // to a maximum period of max_period
115 int exponent; // for exponential back off bucket: multiplier: new_period = old_period * exponent
116 int step_count; // for exponential back off bucket, number of scans performed at a given
117 // period and until the exponent is applied
120 // channels to scan; these may include DFS channels
121 // Note that a given channel may appear in multiple buckets
122 wifi_scan_channel_spec channels[MAX_CHANNELS];
123 } wifi_scan_bucket_spec;
126 int base_period; // base timer period in ms
127 int max_ap_per_scan; // number of APs to store in each scan ientryn the
128 // BSSID/RSSI history buffer (keep the highest RSSI APs)
129 int report_threshold_percent; // in %, when scan buffer is this much full, wake up AP
130 int report_threshold_num_scans; // in number of scans, wake up AP after these many scans
132 wifi_scan_bucket_spec buckets[MAX_BUCKETS];
133 } wifi_scan_cmd_params;
135 /* Start periodic GSCAN */
136 wifi_error wifi_start_gscan(wifi_request_id id, wifi_interface_handle iface,
137 wifi_scan_cmd_params params, wifi_scan_result_handler handler);
139 /* Stop periodic GSCAN */
140 wifi_error wifi_stop_gscan(wifi_request_id id, wifi_interface_handle iface);
143 WIFI_SCAN_FLAG_INTERRUPTED = 1 // Indicates that scan results are not complete because
144 // probes were not sent on some channels
147 /* Get the GSCAN cached scan results */
149 int scan_id; // a unique identifier for the scan unit
150 int flags; // a bitmask with additional information about scan
151 int num_results; // number of bssids retrieved by the scan
152 wifi_scan_result *results; // scan results - one for each bssid
153 } wifi_cached_scan_results;
155 wifi_error wifi_get_cached_gscan_results(wifi_interface_handle iface, byte flush,
156 int max, wifi_cached_scan_results *results, int *num);
160 void (*on_hotlist_ap_found)(wifi_request_id id,
161 unsigned num_results, wifi_scan_result *results);
162 void (*on_hotlist_ap_lost)(wifi_request_id id,
163 unsigned num_results, wifi_scan_result *results);
164 } wifi_hotlist_ap_found_handler;
167 mac_addr bssid; // AP BSSID
168 wifi_rssi low; // low threshold
169 wifi_rssi high; // high threshold
170 } ap_threshold_param;
173 int lost_ap_sample_size;
174 int num_ap; // number of hotlist APs
175 ap_threshold_param ap[MAX_HOTLIST_APS]; // hotlist APs
176 } wifi_bssid_hotlist_params;
178 /* Set the BSSID Hotlist */
179 wifi_error wifi_set_bssid_hotlist(wifi_request_id id, wifi_interface_handle iface,
180 wifi_bssid_hotlist_params params, wifi_hotlist_ap_found_handler handler);
182 /* Clear the BSSID Hotlist */
183 wifi_error wifi_reset_bssid_hotlist(wifi_request_id id, wifi_interface_handle iface);
185 /* Significant wifi change */
187 mac_addr bssid; // BSSID
188 wifi_channel channel; // channel frequency in MHz
189 int num_rssi; // number of rssi samples
190 wifi_rssi rssi[]; // RSSI history in db
191 } wifi_significant_change_result;
194 void (*on_significant_change)(wifi_request_id id,
195 unsigned num_results, wifi_significant_change_result **results);
196 } wifi_significant_change_handler;
198 // The sample size parameters in the wifi_significant_change_params structure
199 // represent the number of occurence of a g-scan where the BSSID was seen and RSSI was
200 // collected for that BSSID, or, the BSSID was expected to be seen and didn't.
201 // for instance: lost_ap_sample_size : number of time a g-scan was performed on the
202 // channel the BSSID was seen last, and the BSSID was not seen during those g-scans
204 int rssi_sample_size; // number of samples for averaging RSSI
205 int lost_ap_sample_size; // number of samples to confirm AP loss
206 int min_breaching; // number of APs breaching threshold
207 int num_ap; // max 64
208 ap_threshold_param ap[MAX_SIGNIFICANT_CHANGE_APS];
209 } wifi_significant_change_params;
211 /* Set the Signifcant AP change list */
212 wifi_error wifi_set_significant_change_handler(wifi_request_id id, wifi_interface_handle iface,
213 wifi_significant_change_params params, wifi_significant_change_handler handler);
215 /* Clear the Signifcant AP change list */
216 wifi_error wifi_reset_significant_change_handler(wifi_request_id id, wifi_interface_handle iface);
218 /* Random MAC OUI for PNO */
219 wifi_error wifi_set_scanning_mac_oui(wifi_interface_handle handle, oui scan_oui);
222 #define WIFI_PNO_FLAG_DIRECTED_SCAN = 1 // whether directed scan needs to be performed (for hidden SSIDs)
223 #define WIFI_PNO_FLAG_HASH_PROVIDED = 2 // whether a crc32 hash of the ssid is provided instead of the ssid
225 // Code for matching the beacon AUTH IE - additional codes TBD
226 #define WIFI_PNO_AUTH_CODE_OPEN 1 // open
227 #define WIFI_PNO_AUTH_CODE_PSK 2 // WPA_PSK or WPA2PSK
228 #define WIFI_PNO_AUTH_CODE_EAPOL 4 // any EAPOL
231 // for each network framework will either specify a ssid or a crc32
232 // if ssid is specified (i.e. ssid[0] != 0) then crc32 field shall be ignored.
233 // A PNO network shall be reported once, that is, once a network is reported by firmware
234 // its entry shall be marked as "done" until framework call wifi_set_epno_list.
235 // Calling wifi_set_epno_list shall reset the "done" status of pno networks in firmware.
238 char rssi_threshold; // threshold for considering this SSID as found
240 int crc32; // crc32 of the SSID, this allows for memory size optimization
241 // i.e. not passing the whole SSID
242 // in firmware and instead storing a shorter string
243 char auth_bit_field; // auth bitfield for matching WPA IE
248 int num_networks; // number of SSIDs
249 wifi_epno_network networks[]; // PNO networks
253 int network_index; // index of the network found in the pno list
255 wifi_channel channel;
262 void (*on_network_found)(wifi_request_id id,
263 unsigned num_results, wifi_epno_result *results);
267 /* Set the PNO list */
268 wifi_error wifi_set_epno_list(wifi_request_id id, wifi_interface_handle iface,
269 int num_networks, wifi_epno_network *networks, wifi_epno_handler handler);