include/hardware_legacy/gscan.h

   1
   2 #include "wifi_hal.h"
   3
   4 #ifndef __WIFI_HAL_GSCAN_H__
   5 #define __WIFI_HAL_GSCAN_H__
   6
   7 /* AP Scans */
   8
   9 typedef enum {
  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
  17 } wifi_band;
  18
  19 #define MAX_CHANNELS                16
  20 #define MAX_BUCKETS                 16
  21 #define MAX_HOTLIST_APS             128
  22 #define MAX_SIGNIFICANT_CHANGE_APS  64
  23 #define MAX_PNO_SSID                128;
  24 #define MAX_HOTLIST_SSID            8;
  25
  26 wifi_error wifi_get_valid_channels(wifi_interface_handle handle,
  27         int band, int max_channels, wifi_channel *channels, int *num_channels);
  28
  29 typedef struct {
  30     int max_scan_cache_size;                 // total space allocated for scan (in bytes)
  31     int max_scan_buckets;                    // maximum number of channel buckets
  32     int max_ap_cache_per_scan;               // maximum number of APs that can be stored per scan
  33     int max_rssi_sample_size;                // number of RSSI samples used for averaging RSSI
  34     int max_scan_reporting_threshold;        // max possible report_threshold as described
  35                                              // in wifi_scan_cmd_params
  36     int max_hotlist_aps;                     // maximum number of entries for hotlist APs
  37     int max_significant_wifi_change_aps;     // maximum number of entries for
  38                                              // significant wifi change APs
  39     int max_bssid_history_entries;           // number of BSSID/RSSI entries that device can hold
  40 } wifi_gscan_capabilities;
  41
  42 wifi_error wifi_get_gscan_capabilities(wifi_interface_handle handle,
  43         wifi_gscan_capabilities *capabilities);
  44
  45 typedef enum {
  46    WIFI_SCAN_BUFFER_FULL,
  47    WIFI_SCAN_COMPLETE,
  48 } wifi_scan_event;
  49
  50
  51 /* Format of information elements found in the beacon */
  52 typedef struct {
  53     byte id;                            // element identifier
  54     byte len;                           // number of bytes to follow
  55     byte data[];
  56 } wifi_information_element;
  57
  58 typedef struct {
  59     wifi_timestamp ts;                  // time since boot (in microsecond) when the result was
  60                                         // retrieved
  61     char ssid[32+1];                    // null terminated
  62     mac_addr bssid;
  63     wifi_channel channel;               // channel frequency in MHz
  64     wifi_rssi rssi;                     // in db
  65     wifi_timespan rtt;                  // in nanoseconds
  66     wifi_timespan rtt_sd;               // standard deviation in rtt
  67     unsigned short beacon_period;       // period advertised in the beacon
  68     unsigned short capability;          // capabilities advertised in the beacon
  69     unsigned int ie_length;             // size of the ie_data blob
  70     char         ie_data[1];            // blob of all the information elements found in the
  71                                         // beacon; this data should be a packed list of
  72                                         // wifi_information_element objects, one after the other.
  73     // other fields
  74 } wifi_scan_result;
  75
  76 typedef struct {
  77     /* reported when report_threshold is reached in scan cache */
  78     void (*on_scan_results_available) (wifi_request_id id, unsigned num_results_available);
  79
  80     /* reported when each probe response is received, if report_events
  81      * enabled in wifi_scan_cmd_params */
  82     void (*on_full_scan_result) (wifi_request_id id, wifi_scan_result *result);
  83
  84     /* optional event - indicates progress of scanning statemachine */
  85     void (*on_scan_event) (wifi_scan_event event, unsigned status);
  86
  87 } wifi_scan_result_handler;
  88
  89 typedef struct {
  90     wifi_channel channel;               // frequency
  91     int dwellTimeMs;                    // dwell time hint
  92     int passive;                        // 0 => active, 1 => passive scan; ignored for DFS
  93     /* Add channel class */
  94 } wifi_scan_channel_spec;
  95
  96
  97 typedef struct {
  98     int bucket;                         // bucket index, 0 based
  99     wifi_band band;                     // when UNSPECIFIED, use channel list
 100     int period;                         // desired period, in millisecond; if this is too
 101                                         // low, the firmware should choose to generate results as
 102                                         // fast as it can instead of failing the command.
 103                                         // for exponential backoff bucket this is the min_period
 104     /* report_events semantics -
 105      *  0 => report only when scan history is % full
 106      *  1 => same as 0 + report a scan completion event after scanning this bucket
 107      *  2 => same as 1 + forward scan results (beacons/probe responses + IEs) in real time to HAL
 108      *  3 => same as 2 + forward scan results (beacons/probe responses + IEs) in real time to
 109              supplicant as well (optional) .
 110      */
 111     byte report_events;
 112     int max_period; // if max_period is non zero or different than period, then this bucket is
 113                     // an exponential backoff bucket and the scan period will grow exponentially
 114                     // as per formula: actual_period(N) = period ^ (N/(step_count+1))
 115                     // to a maximum period of max_period
 116     int exponent; // for exponential back off bucket: multiplier: new_period = old_period * exponent
 117     int step_count; // for exponential back off bucket, number of scans performed at a given
 118                     // period and until the exponent is applied
 119
 120     int num_channels;
 121     // channels to scan; these may include DFS channels
 122     // Note that a given channel may appear in multiple buckets
 123     wifi_scan_channel_spec channels[MAX_CHANNELS];
 124 } wifi_scan_bucket_spec;
 125
 126 typedef struct {
 127     int base_period;                    // base timer period in ms
 128     int max_ap_per_scan;                // number of APs to store in each scan ientryn the
 129                                         // BSSID/RSSI history buffer (keep the highest RSSI APs)
 130     int report_threshold_percent;       // in %, when scan buffer is this much full, wake up AP
 131     int report_threshold_num_scans;     // in number of scans, wake up AP after these many scans
 132     int num_buckets;
 133     wifi_scan_bucket_spec buckets[MAX_BUCKETS];
 134 } wifi_scan_cmd_params;
 135
 136 /* Start periodic GSCAN */
 137 wifi_error wifi_start_gscan(wifi_request_id id, wifi_interface_handle iface,
 138         wifi_scan_cmd_params params, wifi_scan_result_handler handler);
 139
 140 /* Stop periodic GSCAN */
 141 wifi_error wifi_stop_gscan(wifi_request_id id, wifi_interface_handle iface);
 142
 143 typedef enum {
 144     WIFI_SCAN_FLAG_INTERRUPTED = 1      // Indicates that scan results are not complete because
 145                                         // probes were not sent on some channels
 146 } wifi_scan_flags;
 147
 148 /* Get the GSCAN cached scan results */
 149 typedef struct {
 150     int scan_id;                        // a unique identifier for the scan unit
 151     int flags;                          // a bitmask with additional information about scan
 152     int num_results;                    // number of bssids retrieved by the scan
 153     wifi_scan_result *results;          // scan results - one for each bssid
 154 } wifi_cached_scan_results;
 155
 156 wifi_error wifi_get_cached_gscan_results(wifi_interface_handle iface, byte flush,
 157         int max, wifi_cached_scan_results *results, int *num);
 158
 159 /* BSSID Hotlist */
 160 typedef struct {
 161     void (*on_hotlist_ap_found)(wifi_request_id id,
 162             unsigned num_results, wifi_scan_result *results);
 163     void (*on_hotlist_ap_lost)(wifi_request_id id,
 164             unsigned num_results, wifi_scan_result *results);
 165 } wifi_hotlist_ap_found_handler;
 166
 167 typedef struct {
 168     mac_addr  bssid;                    // AP BSSID
 169     wifi_rssi low;                      // low threshold
 170     wifi_rssi high;                     // high threshold
 171 } ap_threshold_param;
 172
 173 typedef struct {
 174     int lost_ap_sample_size;
 175     int num_ap;                                 // number of hotlist APs
 176     ap_threshold_param ap[MAX_HOTLIST_APS];     // hotlist APs
 177 } wifi_bssid_hotlist_params;
 178
 179 /* Set the BSSID Hotlist */
 180 wifi_error wifi_set_bssid_hotlist(wifi_request_id id, wifi_interface_handle iface,
 181         wifi_bssid_hotlist_params params, wifi_hotlist_ap_found_handler handler);
 182
 183 /* Clear the BSSID Hotlist */
 184 wifi_error wifi_reset_bssid_hotlist(wifi_request_id id, wifi_interface_handle iface);
 185
 186
 187 /* SSID Hotlist */
 188 typedef struct {
 189     void (*on_hotlist_ssid_found)(wifi_request_id id,
 190             unsigned num_results, wifi_scan_result *results);
 191     void (*on_hotlist_ssid_lost)(wifi_request_id id,
 192             unsigned num_results, wifi_scan_result *results);
 193 } wifi_hotlist_ssid_found_handler;
 194
 195 typedef struct {
 196     char  ssid[32+1];                   // SSID
 197     wifi_band band;                     // band for this set of threshold params
 198     wifi_rssi low;                      // low threshold
 199     wifi_rssi high;                     // high threshold
 200 } ssid_threshold_param;
 201
 202 typedef struct {
 203     int lost_ssid_sample_size;
 204     int num_ap;                                 // number of hotlist APs
 205     ssid_threshold_param ssid[MAX_HOTLIST_APS];     // hotlist APs
 206 } wifi_ssid_hotlist_params;
 207
 208
 209 /* Set the SSID Hotlist */
 210 wifi_error wifi_set_ssid_hotlist(wifi_request_id id, wifi_interface_handle iface,
 211         wifi_ssid_hotlist_params params, wifi_hotlist_ssid_found_handler handler);
 212
 213 /* Clear the SSID Hotlist */
 214 wifi_error wifi_reset_ssid_hotlist(wifi_request_id id, wifi_interface_handle iface);
 215
 216
 217
 218 /* Significant wifi change */
 219 typedef struct {
 220     mac_addr bssid;                     // BSSID
 221     wifi_channel channel;               // channel frequency in MHz
 222     int num_rssi;                       // number of rssi samples
 223     wifi_rssi rssi[];                   // RSSI history in db
 224 } wifi_significant_change_result;
 225
 226 typedef struct {
 227     void (*on_significant_change)(wifi_request_id id,
 228             unsigned num_results, wifi_significant_change_result **results);
 229 } wifi_significant_change_handler;
 230
 231 // The sample size parameters in the wifi_significant_change_params structure
 232 // represent the number of occurence of a g-scan where the BSSID was seen and RSSI was
 233 // collected for that BSSID, or, the BSSID was expected to be seen and didn't.
 234 // for instance: lost_ap_sample_size : number of time a g-scan was performed on the
 235 // channel the BSSID was seen last, and the BSSID was not seen during those g-scans
 236 typedef struct {
 237     int rssi_sample_size;               // number of samples for averaging RSSI
 238     int lost_ap_sample_size;            // number of samples to confirm AP loss
 239     int min_breaching;                  // number of APs breaching threshold
 240     int num_ap;                         // max 64
 241     ap_threshold_param ap[MAX_SIGNIFICANT_CHANGE_APS];
 242 } wifi_significant_change_params;
 243
 244 /* Set the Signifcant AP change list */
 245 wifi_error wifi_set_significant_change_handler(wifi_request_id id, wifi_interface_handle iface,
 246         wifi_significant_change_params params, wifi_significant_change_handler handler);
 247
 248 /* Clear the Signifcant AP change list */
 249 wifi_error wifi_reset_significant_change_handler(wifi_request_id id, wifi_interface_handle iface);
 250
 251 /* Random MAC OUI for PNO */
 252 wifi_error wifi_set_scanning_mac_oui(wifi_interface_handle handle, oui scan_oui);
 253
 254 // Whether directed scan needs to be performed (for hidden SSIDs)
 255 #define WIFI_PNO_FLAG_DIRECTED_SCAN = 1
 256 // Whether PNO event shall be triggered if the network is found on A band
 257 #define WIFI_PNO_FLAG_A_BAND = 2
 258 // Whether PNO event shall be triggered if the network is found on G band
 259 #define WIFI_PNO_FLAG_G_BAND = 4
 260 // Whether strict matching is required (i.e. firmware shall not match on the entire SSID)
 261 #define WIFI_PNO_FLAG_STRICT_MATCH = 8
 262
 263 // Code for matching the beacon AUTH IE - additional codes TBD
 264 #define WIFI_PNO_AUTH_CODE_OPEN  1 // open
 265 #define WIFI_PNO_AUTH_CODE_PSK   2 // WPA_PSK or WPA2PSK
 266 #define WIFI_PNO_AUTH_CODE_EAPOL 4 // any EAPOL
 267
 268 // Enhanced PNO:
 269 // Enhanced PNO feature is expected to be enabled all of the time (e.g. screen lit) and may thus
 270 // requires firmware to store a large number of networks, covering the whole list of known network.
 271 // Therefore, it is acceptable for firmware to store a crc24, crc32 or other short hash of the SSID,
 272 // such that a low but non-zero probability of collision exist. With that scheme it should be
 273 // possible for firmware to keep an entry as small as 4 bytes for each pno network.
 274 // For instance, a firmware pn0 entry can be implemented in the form of:
 275 //          PNO ENTRY = crc24(3 bytes) | RSSI_THRESHOLD>>3 (5 bits) | auth flags(3 bits)
 276 //
 277 // A PNO network shall be reported once, that is, once a network is reported by firmware
 278 // its entry shall be marked as "done" until framework calls wifi_set_epno_list again.
 279 // Calling wifi_set_epno_list shall reset the "done" status of pno networks in firmware.
 280 typedef struct {
 281     char ssid[32+1];
 282     char rssi_threshold; // threshold for considering this SSID as found, required granularity for
 283                          // this threshold is 4dBm to 8dBm
 284     char flags;          //  WIFI_PNO_FLAG_XXX
 285     char auth_bit_field; // auth bit field for matching WPA IE
 286 } wifi_epno_network;
 287
 288 /* PNO list */
 289 typedef struct {
 290     int num_networks;                 // number of SSIDs
 291     wifi_epno_network networks[];     // PNO networks
 292 } wifi_epno_params;
 293
 294 typedef struct {
 295     // on results
 296     void (*on_network_found)(wifi_request_id id,
 297             unsigned num_results, wifi_scan_result *results);
 298 } wifi_epno_handler;
 299
 300
 301 /* Set the PNO list */
 302 wifi_error wifi_set_epno_list(wifi_request_id id, wifi_interface_handle iface,
 303         int num_networks, wifi_epno_network *networks, wifi_epno_handler handler);
 304
 305
 306 /* SSID white list */
 307 /* Note that this feature requires firmware to be able to indicate to kernel sme and wpa_supplicant
 308  * that the SSID of the network has changed
 309  * and thus requires further changed in cfg80211 stack, for instance,
 310  * the below function would change:
 311
 312  void __cfg80211_roamed(struct wireless_dev *wdev,
 313                        struct cfg80211_bss *bss,
 314                        const u8 *req_ie, size_t req_ie_len,
 315                        const u8 *resp_ie, size_t resp_ie_len)
 316  * when firmware roam to a new SSID the corresponding link layer stats info need to be updated:
 317      struct wifi_interface_link_layer_info;
 318  */
 319 typedef struct {
 320     char ssid[32+1]; // null terminated
 321 } wifi_ssid;
 322
 323 wifi_error wifi_set_ssid_white_list(wifi_request_id id, wifi_interface_handle iface,
 324         int num_networks, wifi_ssid *ssids);
 325
 326
 327
 328 /* Set G-SCAN roam parameters */
 329 /**
 330  * Firmware roaming is implemented with two modes:
 331  *   1- "Alert" mode roaming, (Note: alert roaming is the pre-L roaming, whereas firmware is
 332  *      "urgently" hunting for another BSSID because the RSSI is low, or because many successive
 333  *      beacons have been lost or other bad link conditions).
 334  *   2- "Lazy" mode, where firmware is hunting for a better BSSID or white listed SSID even though
 335  *      the RSSI of the link is good.
 336  *      Lazy mode is configured thru G-scan, that is, the results of G-scans are compared to the
 337  *      current RSSI and fed thru the roaming engine.
 338  *      Lazy scan will be enabled (and or throttled down by reducing the number of G-scans) by
 339  *      framework only in certain conditions, such as:
 340  *          - no real time (VO/VI) traffic at the interface
 341  *          - low packet rate for BE/BK packets a the interface
 342  *          - system conditions (screen lit/dark) etc...
 343  *
 344  * For consistency, the roam parameters will always be configured by framework such that:
 345  *
 346  * condition 1- A_band_boost_threshold >= (alert_roam_rssi_trigger + 10)
 347  * This condition ensures that Lazy roam doesn't cause the device to roam to a 5GHz BSSID whose RSSI
 348  * is lower than the alert threshold, which would consequently trigger a roam to a low RSSI BSSID,
 349  * hence triggering alert mode roaming.
 350  * In other words, in alert mode, the A_band parameters may safely be ignored by WiFi chipset.
 351  *
 352  * condition 2- A_band_boost_threshold > A_band_penalty_factor
 353  *
 354  */
 355
 356 /**
 357  * Example:
 358  * A_band_boost_threshold = -65
 359  * A_band_penalty_threshold = -75
 360  * A_band_boost_factor = 4
 361  * A_band_penalty_factor = 2
 362  * A_band_max_boost = 50
 363  *
 364  * a 5GHz RSSI value is transformed as below:
 365  * -20 -> -20+ 50 = 30
 366  * -60 -> -60 + 4 * (-60 - A_band_boost_threshold) = -60 + 16 = -44
 367  * -70 -> -70
 368  * -80 -> -80 - 2 * (A_band_penalty_threshold - (-80)) = -80 - 10 = -90
 369  */
 370
 371 typedef struct {
 372     // Lazy roam parameters
 373     // A_band_XX parameters are applied to 5GHz BSSIDs when comparing with a 2.4GHz BSSID
 374     // they may not be applied when comparing two 5GHz BSSIDs
 375     int A_band_boost_threshold;     // RSSI threshold above which 5GHz RSSI is favored
 376     int A_band_penalty_threshold;   // RSSI threshold below which 5GHz RSSI is penalized
 377     int A_band_boost_factor;        // factor by which 5GHz RSSI is boosted
 378                                // boost=RSSI_measured-5GHz_boost_threshold)*5GHz_boost_factor
 379     int A_band_penalty_factor;      // factor by which 5GHz RSSI is penalized
 380                                // penalty=(5GHz_penalty_factor-RSSI_measured)*5GHz_penalty_factor
 381     int A_band_max_boost;           // maximum boost that can be applied to a 5GHz RSSI
 382
 383     // Hysteresis: ensuring the currently associated BSSID is favored
 384     // so as to prevent ping-pong situations
 385     int lazy_roam_histeresys;       // boost applied to current BSSID
 386
 387     // Alert mode enable, i.e. configuring when firmware enters alert mode
 388     int alert_roam_rssi_trigger;    // RSSI below which "Alert" roam is enabled
 389 } wifi_roam_params;
 390
 391 wifi_error wifi_set_gscan_roam_params(wifi_request_id id, wifi_interface_handle iface,
 392                                         wifi_roam_params * params);
 393
 394 /**
 395  * Enable/Disable "Lazy" roam
 396  */
 397 wifi_error wifi_set_lazy_roam(wifi_request_id id, wifi_interface_handle iface, int enable);
 398
 399 /**
 400  * Per BSSID preference
 401  */
 402 typedef struct {
 403     char bssid[6];
 404     int rssi_modifier;  // modifier applied to the RSSI of the BSSIDfor the purpose of comparing
 405                         // it with other roam candidate
 406 } wifi_bssid_preference;
 407
 408 wifi_error wifi_set_lazy_roam(wifi_request_id id, wifi_interface_handle iface,
 409                                     int num_bssid, wifi_bssid_preference *prefs);
 410
 411
 412 typedef struct {
 413     int max_number_epno_networks;           // max number of epno entries, M target is 64
 414     int max_number_of_white_listed_ssid;    // max number of white listed SSIDs, M target is 2 to 4
 415     int max_number_of_hotlist_ssid;         // max number of hotlist SSIDs, M target is 4
 416 } wifi_roam_autojoin_offload_capabilities;
 417
 418 wifi_error wifi_get_roam_autojoin_offload_capabilities(wifi_interface_handle handle,
 419         wifi_roam_autojoin_offload_capabilities *capabilities);
 420
 421 #endif
 422