Home | History | Annotate | Download | only in hardware_legacy
      1 
      2 #include "wifi_hal.h"
      3 #include "gscan.h"
      4 
      5 #ifndef __WIFI_HAL_RTT_H__
      6 #define __WIFI_HAL_RTT_H__
      7 
      8 /* Ranging status */
      9 typedef enum {
     10     RTT_STATUS_SUCCESS       = 0,
     11     RTT_STATUS_FAILURE       = 1,           // general failure status
     12     RTT_STATUS_FAIL_NO_RSP   = 2,           // target STA does not respond to request
     13     RTT_STATUS_FAIL_REJECTED = 3,           // request rejected. Applies to 2-sided RTT only
     14     RTT_STATUS_FAIL_NOT_SCHEDULED_YET  = 4,
     15     RTT_STATUS_FAIL_TM_TIMEOUT         = 5, // timing measurement times out
     16     RTT_STATUS_FAIL_AP_ON_DIFF_CHANNEL = 6, // Target on different channel, cannot range
     17     RTT_STATUS_FAIL_NO_CAPABILITY  = 7,     // ranging not supported
     18     RTT_STATUS_ABORTED             = 8,     // request aborted for unknown reason
     19     RTT_STATUS_FAIL_INVALID_TS     = 9,     // Invalid T1-T4 timestamp
     20     RTT_STATUS_FAIL_PROTOCOL       = 10,    // 11mc protocol failed
     21     RTT_STATUS_FAIL_SCHEDULE       = 11,    // request could not be scheduled
     22     RTT_STATUS_FAIL_BUSY_TRY_LATER = 12,    // responder cannot collaborate at time of request
     23     RTT_STATUS_INVALID_REQ         = 13,    // bad request args
     24     RTT_STATUS_NO_WIFI             = 14,    // WiFi not enabled
     25     RTT_STATUS_FAIL_FTM_PARAM_OVERRIDE = 15 // Responder overrides param info, cannot range with new params
     26 } wifi_rtt_status;
     27 
     28 /* RTT peer type */
     29 typedef enum {
     30     RTT_PEER_AP         = 0x1,
     31     RTT_PEER_STA        = 0x2,
     32     RTT_PEER_P2P_GO     = 0x3,
     33     RTT_PEER_P2P_CLIENT = 0x4,
     34     RTT_PEER_NAN        = 0x5
     35 } rtt_peer_type;
     36 
     37 /* RTT Measurement Bandwidth */
     38 typedef enum {
     39     WIFI_RTT_BW_5   = 0x01,
     40     WIFI_RTT_BW_10  = 0x02,
     41     WIFI_RTT_BW_20  = 0x04,
     42     WIFI_RTT_BW_40  = 0x08,
     43     WIFI_RTT_BW_80  = 0x10,
     44     WIFI_RTT_BW_160 = 0x20
     45 } wifi_rtt_bw;
     46 
     47 /* RTT Measurement Preamble */
     48 typedef enum {
     49     WIFI_RTT_PREAMBLE_LEGACY = 0x1,
     50     WIFI_RTT_PREAMBLE_HT     = 0x2,
     51     WIFI_RTT_PREAMBLE_VHT    = 0x4
     52 } wifi_rtt_preamble;
     53 
     54 /* RTT Type */
     55 typedef enum {
     56     RTT_TYPE_1_SIDED = 0x1,
     57     RTT_TYPE_2_SIDED = 0x2,
     58 } wifi_rtt_type;
     59 
     60 /* RTT configuration */
     61 typedef struct {
     62     mac_addr addr;                 // peer device mac address
     63     wifi_rtt_type type;            // 1-sided or 2-sided RTT
     64     rtt_peer_type peer;            // optional - peer device hint (STA, P2P, AP)
     65     wifi_channel_info channel;     // Required for STA-AP mode, optional for P2P, NBD etc.
     66     unsigned burst_period;         // Time interval between bursts (units: 100 ms).
     67                                    // Applies to 1-sided and 2-sided RTT multi-burst requests.
     68                                    // Range: 0-31, 0: no preference by initiator (2-sided RTT)
     69     unsigned num_burst;            // Total number of RTT bursts to be executed. It will be
     70                                    // specified in the same way as the parameter "Number of
     71                                    // Burst Exponent" found in the FTM frame format. It
     72                                    // applies to both: 1-sided RTT and 2-sided RTT. Valid
     73                                    // values are 0 to 15 as defined in 802.11mc std.
     74                                    // 0 means single shot
     75                                    // The implication of this parameter on the maximum
     76                                    // number of RTT results is the following:
     77                                    // for 1-sided RTT: max num of RTT results = (2^num_burst)*(num_frames_per_burst)
     78                                    // for 2-sided RTT: max num of RTT results = (2^num_burst)*(num_frames_per_burst - 1)
     79     unsigned num_frames_per_burst; // num of frames per burst.
     80                                    // Minimum value = 1, Maximum value = 31
     81                                    // For 2-sided this equals the number of FTM frames
     82                                    // to be attempted in a single burst. This also
     83                                    // equals the number of FTM frames that the
     84                                    // initiator will request that the responder send
     85                                    // in a single frame.
     86     unsigned num_retries_per_rtt_frame; // number of retries for a failed RTT frame. Applies
     87                                         // to 1-sided RTT only. Minimum value = 0, Maximum value = 3
     88 
     89     //following fields are only valid for 2-side RTT
     90     unsigned num_retries_per_ftmr; // Maximum number of retries that the initiator can
     91                                    // retry an FTMR frame.
     92                                    // Minimum value = 0, Maximum value = 3
     93     byte LCI_request;              // 1: request LCI, 0: do not request LCI
     94     byte LCR_request;              // 1: request LCR, 0: do not request LCR
     95     unsigned burst_duration;       // Applies to 1-sided and 2-sided RTT. Valid values will
     96                                    // be 2-11 and 15 as specified by the 802.11mc std for
     97                                    // the FTM parameter burst duration. In a multi-burst
     98                                    // request, if responder overrides with larger value,
     99                                    // the initiator will return failure. In a single-burst
    100                                    // request if responder overrides with larger value,
    101                                    // the initiator will sent TMR_STOP to terminate RTT
    102                                    // at the end of the burst_duration it requested.
    103     wifi_rtt_preamble preamble;    // RTT preamble to be used in the RTT frames
    104     wifi_rtt_bw bw;                // RTT BW to be used in the RTT frames
    105 } wifi_rtt_config;
    106 
    107 /* RTT results */
    108 typedef struct {
    109     mac_addr addr;                // device mac address
    110     unsigned burst_num;           // burst number in a multi-burst request
    111     unsigned measurement_number;  // Total RTT measurement frames attempted
    112     unsigned success_number;      // Total successful RTT measurement frames
    113     byte  number_per_burst_peer;  // Maximum number of "FTM frames per burst" supported by
    114                                   // the responder STA. Applies to 2-sided RTT only.
    115                                   // If reponder overrides with larger value:
    116                                   // - for single-burst request initiator will truncate the
    117                                   // larger value and send a TMR_STOP after receiving as
    118                                   // many frames as originally requested.
    119                                   // - for multi-burst request, initiator will return
    120                                   // failure right away.
    121     wifi_rtt_status status;       // ranging status
    122     byte retry_after_duration;    // When status == RTT_STATUS_FAIL_BUSY_TRY_LATER,
    123                                   // this will be the time provided by the responder as to
    124                                   // when the request can be tried again. Applies to 2-sided
    125                                   // RTT only. In sec, 1-31sec.
    126     wifi_rtt_type type;           // RTT type
    127     wifi_rssi rssi;               // average rssi in 0.5 dB steps e.g. 143 implies -71.5 dB
    128     wifi_rssi rssi_spread;        // rssi spread in 0.5 dB steps e.g. 5 implies 2.5 dB spread (optional)
    129     wifi_rate tx_rate;            // 1-sided RTT: TX rate of RTT frame.
    130                                   // 2-sided RTT: TX rate of initiator's Ack in response to FTM frame.
    131     wifi_rate rx_rate;            // 1-sided RTT: TX rate of Ack from other side.
    132                                   // 2-sided RTT: TX rate of FTM frame coming from responder.
    133     wifi_timespan rtt;            // round trip time in picoseconds
    134     wifi_timespan rtt_sd;         // rtt standard deviation in picoseconds
    135     wifi_timespan rtt_spread;     // difference between max and min rtt times recorded in picoseconds
    136     int distance_mm;              // distance in mm (optional)
    137     int distance_sd_mm;           // standard deviation in mm (optional)
    138     int distance_spread_mm;       // difference between max and min distance recorded in mm (optional)
    139     wifi_timestamp ts;            // time of the measurement (in microseconds since boot)
    140     int burst_duration;           // in ms, actual time taken by the FW to finish one burst
    141                                   // measurement. Applies to 1-sided and 2-sided RTT.
    142     int negotiated_burst_num;     // Number of bursts allowed by the responder. Applies
    143                                   // to 2-sided RTT only.
    144     wifi_information_element *LCI; // for 11mc only
    145     wifi_information_element *LCR; // for 11mc only
    146 } wifi_rtt_result;
    147 
    148 /* RTT result callback */
    149 typedef struct {
    150     void (*on_rtt_results) (wifi_request_id id, unsigned num_results, wifi_rtt_result *rtt_result[]);
    151 } wifi_rtt_event_handler;
    152 
    153 /* API to request RTT measurement */
    154 wifi_error wifi_rtt_range_request(wifi_request_id id, wifi_interface_handle iface,
    155         unsigned num_rtt_config, wifi_rtt_config rtt_config[], wifi_rtt_event_handler handler);
    156 
    157 /* API to cancel RTT measurements */
    158 wifi_error wifi_rtt_range_cancel(wifi_request_id id,  wifi_interface_handle iface,
    159         unsigned num_devices, mac_addr addr[]);
    160 
    161 /* NBD ranging channel map */
    162 typedef struct {
    163     wifi_channel availablity[32]; // specifies the channel map for each of the 16 TU windows
    164     // frequency of 0 => unspecified; which means firmware is
    165     // free to do whatever it wants in this window.
    166 } wifi_channel_map;
    167 
    168 /* API to start publishing the channel map on responder device in a NBD cluster.
    169    Responder device will take this request and schedule broadcasting the channel map
    170    in a NBD ranging attribute in a SDF. DE will automatically remove the ranging
    171    attribute from the OTA queue after number of DW specified by num_dw
    172    where Each DW is 512 TUs apart */
    173 wifi_error wifi_rtt_channel_map_set(wifi_request_id id,
    174         wifi_interface_handle iface, wifi_channel_map *params, unsigned num_dw);
    175 
    176 /* API to clear the channel map on the responder device in a NBD cluster.
    177    Responder device will cancel future ranging channel request, starting from next
    178    DW interval and will also stop broadcasting NBD ranging attribute in SDF */
    179 wifi_error wifi_rtt_channel_map_clear(wifi_request_id id,  wifi_interface_handle iface);
    180 
    181 // Preamble definition for bit mask used in wifi_rtt_capabilities
    182 #define PREAMBLE_LEGACY 0x1
    183 #define PREAMBLE_HT     0x2
    184 #define PREAMBLE_VHT    0x4
    185 
    186 // BW definition for bit mask used in wifi_rtt_capabilities
    187 #define BW_5_SUPPORT   0x1
    188 #define BW_10_SUPPORT  0x2
    189 #define BW_20_SUPPORT  0x4
    190 #define BW_40_SUPPORT  0x8
    191 #define BW_80_SUPPORT  0x10
    192 #define BW_160_SUPPORT 0x20
    193 
    194 /* RTT Capabilities */
    195 typedef struct {
    196     byte rtt_one_sided_supported;  // if 1-sided rtt data collection is supported
    197     byte rtt_ftm_supported;        // if ftm rtt data collection is supported
    198     byte lci_support;              // if initiator supports LCI request. Applies to 2-sided RTT
    199     byte lcr_support;              // if initiator supports LCR request. Applies to 2-sided RTT
    200     byte preamble_support;         // bit mask indicates what preamble is supported by initiator
    201     byte bw_support;               // bit mask indicates what BW is supported by initiator
    202     byte responder_supported;      // if 11mc responder mode is supported
    203     byte mc_version;               // draft 11mc spec version supported by chip. For instance,
    204                                    // version 4.0 should be 40 and version 4.3 should be 43 etc.
    205 } wifi_rtt_capabilities;
    206 
    207 /*  RTT capabilities of the device */
    208 wifi_error wifi_get_rtt_capabilities(wifi_interface_handle iface, wifi_rtt_capabilities *capabilities);
    209 
    210 /* debugging definitions */
    211 enum {
    212     RTT_DEBUG_DISABLE,
    213     RTT_DEBUG_LOG,
    214     RTT_DEBUG_PROTO,
    215     RTT_DEBUG_BURST,
    216     RTT_DEBUG_ACCURACY,
    217     RTT_DEBUG_LOGDETAIL
    218 };  //rtt debug type
    219 
    220 enum {
    221     RTT_DEBUG_FORMAT_TXT,
    222     RTT_DEBUG_FORMAT_BINARY
    223 }; //rtt debug format
    224 
    225 typedef struct rtt_debug {
    226     unsigned version;
    227     unsigned len; // total length of after len field
    228     unsigned type;  // rtt debug type
    229     unsigned format; //rtt debug format
    230     char dbuf[0]; // debug content
    231 } rtt_debug_t;
    232 
    233 /* set configuration for debug */
    234 wifi_error wifi_rtt_debug_cfg(wifi_interface_handle h, unsigned rtt_dbg_type, char *cfgbuf, unsigned cfg_buf_size);
    235 /* get the debug information */
    236 wifi_error wifi_rtt_debug_get(wifi_interface_handle h, rtt_debug_t **debugbuf);
    237 /* free the debug buffer */
    238 wifi_error wifi_rtt_debug_free(wifi_interface_handle h, rtt_debug_t *debugbuf);
    239 
    240 /* API for setting LCI/LCR information to be provided to a requestor */
    241 typedef enum {
    242     WIFI_MOTION_NOT_EXPECTED = 0, // Not expected to change location
    243     WIFI_MOTION_EXPECTED = 1,     // Expected to change location
    244     WIFI_MOTION_UNKNOWN  = 2,     // Movement pattern unknown
    245 } wifi_motion_pattern;
    246 
    247 typedef struct {
    248     long latitude;              // latitude in degrees * 2^25 , 2's complement
    249     long longitude;             // latitude in degrees * 2^25 , 2's complement
    250     int  altitude;              // Altitude in units of 1/256 m
    251     byte latitude_unc;          // As defined in Section 2.3.2 of IETF RFC 6225
    252     byte longitude_unc;         // As defined in Section 2.3.2 of IETF RFC 6225
    253     byte altitude_unc;          // As defined in Section 2.4.5 from IETF RFC 6225:
    254 
    255     //Following element for configuring the Z subelement
    256     wifi_motion_pattern motion_pattern;
    257     int  floor;                 // floor in units of 1/16th of floor. 0x80000000 if unknown.
    258     int  height_above_floor;    // in units of 1/64 m
    259     int  height_unc;            // in units of 1/64 m. 0 if unknown
    260 } wifi_lci_information;
    261 
    262 typedef struct {
    263     char country_code[2];       // country code
    264     int  length;                // length of the info field
    265     char civic_info[256];       // Civic info to be copied in FTM frame
    266 } wifi_lcr_information;
    267 
    268 // API to configure the LCI. Used in RTT Responder mode only
    269 wifi_error wifi_set_lci(wifi_request_id id, wifi_interface_handle iface,
    270                         wifi_lci_information *lci);
    271 
    272 // API to configure the LCR. Used in RTT Responder mode only.
    273 wifi_error wifi_set_lcr(wifi_request_id id, wifi_interface_handle iface,
    274                         wifi_lcr_information *lcr);
    275 
    276 /**
    277  * RTT Responder information
    278  */
    279 typedef struct {
    280     wifi_channel_info channel;
    281     wifi_rtt_preamble preamble;
    282 } wifi_rtt_responder;
    283 
    284 /**
    285  * Get RTT responder information e.g. WiFi channel to enable responder on.
    286  */
    287 wifi_error wifi_rtt_get_responder_info(wifi_interface_handle iface,
    288                                        wifi_rtt_responder *responder_info);
    289 
    290 /**
    291  * Enable RTT responder mode.
    292  * channel_hint - hint of the channel information where RTT responder should be enabled on.
    293  * max_duration_seconds - timeout of responder mode.
    294  * channel_used - channel used for RTT responder, NULL if responder is not enabled.
    295  */
    296 wifi_error wifi_enable_responder(wifi_request_id id, wifi_interface_handle iface,
    297                                  wifi_channel_info channel_hint, unsigned max_duration_seconds,
    298                                  wifi_rtt_responder *responder_info);
    299 
    300 /**
    301  * Disable RTT responder mode.
    302  */
    303 wifi_error wifi_disable_responder(wifi_request_id id, wifi_interface_handle iface);
    304 
    305 #endif
    306