rtt.h revision 88aa64b95e2de18380721bda4e05f128cd5107a7
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 */ 9typedef 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 */ 29typedef 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 */ 38typedef 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 */ 48typedef 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 */ 55typedef enum { 56 RTT_TYPE_1_SIDED = 0x1, 57 RTT_TYPE_2_SIDED = 0x2, 58} wifi_rtt_type; 59 60/* RTT configuration */ 61typedef 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 */ 108typedef 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 */ 149typedef 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 */ 154wifi_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 */ 158wifi_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 */ 162typedef 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 */ 173wifi_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 */ 179wifi_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 */ 195typedef 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 */ 208wifi_error wifi_get_rtt_capabilities(wifi_interface_handle iface, wifi_rtt_capabilities *capabilities); 209 210/* debugging definitions */ 211enum { 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 220enum { 221 RTT_DEBUG_FORMAT_TXT, 222 RTT_DEBUG_FORMAT_BINARY 223}; //rtt debug format 224 225typedef 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 */ 234wifi_error wifi_rtt_debug_cfg(wifi_interface_handle h, unsigned rtt_dbg_type, char *cfgbuf, unsigned cfg_buf_size); 235/* get the debug information */ 236wifi_error wifi_rtt_debug_get(wifi_interface_handle h, rtt_debug_t **debugbuf); 237/* free the debug buffer */ 238wifi_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 */ 241typedef 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 247typedef 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 262typedef 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 269wifi_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. 273wifi_error wifi_set_lcr(wifi_request_id id, wifi_interface_handle iface, 274 wifi_lcr_information *lcr); 275 276/** 277 * RTT Responder information 278 */ 279typedef 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 */ 287wifi_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 */ 296wifi_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 */ 303wifi_error wifi_disable_responder(wifi_request_id id, wifi_interface_handle iface); 304 305#endif 306