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 RTT_STATUS_NAN_RANGING_PROTOCOL_FAILURE =16, //Negotiation failure 27 RTT_STATUS_NAN_RANGING_CONCURRENCY_NOT_SUPPORTED=17, //concurrency not supported (NDP+RTT) 28 } wifi_rtt_status; 29 30 /* RTT peer type */ 31 typedef enum { 32 RTT_PEER_AP = 0x1, 33 RTT_PEER_STA = 0x2, 34 RTT_PEER_P2P_GO = 0x3, 35 RTT_PEER_P2P_CLIENT = 0x4, 36 RTT_PEER_NAN = 0x5 37 } rtt_peer_type; 38 39 /* RTT Measurement Bandwidth */ 40 typedef enum { 41 WIFI_RTT_BW_UNSPECIFIED = 0x00, 42 WIFI_RTT_BW_5 = 0x01, 43 WIFI_RTT_BW_10 = 0x02, 44 WIFI_RTT_BW_20 = 0x04, 45 WIFI_RTT_BW_40 = 0x08, 46 WIFI_RTT_BW_80 = 0x10, 47 WIFI_RTT_BW_160 = 0x20, 48 WIFI_RTT_BW_320 = 0x40 49 } wifi_rtt_bw; 50 51 /* RTT Measurement Preamble */ 52 typedef enum { 53 WIFI_RTT_PREAMBLE_INVALID = 0x0, 54 WIFI_RTT_PREAMBLE_LEGACY = 0x1, 55 WIFI_RTT_PREAMBLE_HT = 0x2, 56 WIFI_RTT_PREAMBLE_VHT = 0x4, 57 WIFI_RTT_PREAMBLE_HE = 0x8, 58 WIFI_RTT_PREAMBLE_EHT = 0x10, 59 } wifi_rtt_preamble ; 60 61 /* RTT Type */ 62 typedef enum { 63 RTT_TYPE_1_SIDED = 0x1, 64 /* Deprecated. Use RTT_TYPE_2_SIDED_11MC instead. */ 65 RTT_TYPE_2_SIDED = 0x2, 66 RTT_TYPE_2_SIDED_11MC = RTT_TYPE_2_SIDED, 67 RTT_TYPE_2_SIDED_11AZ_NTB = 0x3, 68 69 } wifi_rtt_type; 70 71 /* RTT configuration */ 72 typedef struct { 73 mac_addr addr; // peer device mac address 74 wifi_rtt_type type; // 1-sided or 2-sided RTT (11mc and 11az) 75 rtt_peer_type peer; // optional - peer device hint (STA, P2P, AP) 76 wifi_channel_info channel; // Required for STA-AP mode, optional for P2P, NBD etc. 77 unsigned burst_period; // Time interval between bursts (units: 100 ms). 78 // Applies to 1-sided and 2-sided RTT multi-burst requests. 79 // Range: 0-31, 0: no preference by initiator (2-sided RTT) 80 // Note: Applicable for 11mc only. 81 unsigned num_burst; // Total number of RTT bursts to be executed. It will be 82 // specified in the same way as the parameter "Number of 83 // Burst Exponent" found in the FTM frame format. It 84 // applies to both: 1-sided RTT and 2-sided RTT. Valid 85 // values are 0 to 15 as defined in 802.11mc std. 86 // 0 means single shot 87 // The implication of this parameter on the maximum 88 // number of RTT results is the following: 89 // for 1-sided RTT: max num of RTT results = (2^num_burst)*(num_frames_per_burst) 90 // for 2-sided RTT: max num of RTT results = (2^num_burst)*(num_frames_per_burst - 1) 91 // Note: Applicable for 11mc only. 92 unsigned num_frames_per_burst; // num of frames per burst. 93 // Minimum value = 1, Maximum value = 31 94 // For 2-sided this equals the number of FTM frames 95 // to be attempted in a single burst. This also 96 // equals the number of FTM frames that the 97 // initiator will request that the responder send 98 // in a single frame. 99 // Note: Applicable for 11mc only. 100 unsigned num_retries_per_rtt_frame; // number of retries for a failed RTT frame. Applies 101 // to 1-sided RTT only. Minimum value = 0, Maximum value = 3 102 103 //following fields are only valid for 2-side RTT 104 unsigned num_retries_per_ftmr; // Maximum number of retries that the initiator can 105 // retry an FTMR frame. 106 // Minimum value = 0, Maximum value = 3 107 byte LCI_request; // 1: request LCI, 0: do not request LCI 108 byte LCR_request; // 1: request LCR, 0: do not request LCR 109 unsigned burst_duration; // Applies to 1-sided and 2-sided 11mc RTT. Valid values will 110 // be 2-11 and 15 as specified by the 802.11mc std for 111 // the FTM parameter burst duration. In a multi-burst 112 // request, if responder overrides with larger value, 113 // the initiator will return failure. In a single-burst 114 // request if responder overrides with larger value, 115 // the initiator will sent TMR_STOP to terminate RTT 116 // at the end of the burst_duration it requested. 117 wifi_rtt_preamble preamble; // RTT preamble to be used in the RTT frames 118 wifi_rtt_bw bw; // RTT BW to be used in the RTT frames 119 } wifi_rtt_config; 120 121 /* RTT configuration v3 (11az support)*/ 122 typedef struct { 123 wifi_rtt_config rtt_config; 124 u64 ntb_min_measurement_time; // 11az Non-Trigger-based (non-TB) minimum measurement time in 125 // units of 100 microseconds 126 u64 ntb_max_measurement_time; // 11az Non-Trigger-based (non-TB) maximum measurement time in 127 // units of 10 milliseconds 128 } wifi_rtt_config_v3; 129 130 /* RTT results */ 131 typedef struct { 132 mac_addr addr; // device mac address 133 unsigned burst_num; // burst number in a multi-burst request. Note: Applicable to 134 // 1-sided RTT and 2-sided IEEE 802.11mc only. 135 unsigned measurement_number; // Total RTT measurement frames attempted 136 unsigned success_number; // Total successful RTT measurement frames 137 byte number_per_burst_peer; // Maximum number of "FTM frames per burst" supported by 138 // the responder STA. Applies to 2-sided RTT only. 139 // If reponder overrides with larger value: 140 // - for single-burst request initiator will truncate the 141 // larger value and send a TMR_STOP after receiving as 142 // many frames as originally requested. 143 // - for multi-burst request, initiator will return 144 // failure right away. 145 wifi_rtt_status status; // ranging status 146 byte retry_after_duration; // When status == RTT_STATUS_FAIL_BUSY_TRY_LATER, 147 // this will be the time provided by the responder as to 148 // when the request can be tried again. Applies to 2-sided 149 // RTT only. In sec, 1-31sec. 150 wifi_rtt_type type; // RTT type 151 wifi_rssi rssi; // average rssi in 0.5 dB steps e.g. 143 implies -71.5 dB 152 wifi_rssi rssi_spread; // rssi spread in 0.5 dB steps e.g. 5 implies 2.5 dB spread (optional) 153 wifi_rate tx_rate; // 1-sided RTT: TX rate of RTT frame. 154 // 2-sided RTT: TX rate of initiator's Ack in response to FTM frame. 155 wifi_rate rx_rate; // 1-sided RTT: TX rate of Ack from other side. 156 // 2-sided RTT: TX rate of FTM frame coming from responder. 157 wifi_timespan rtt; // round trip time in picoseconds 158 wifi_timespan rtt_sd; // rtt standard deviation in picoseconds 159 wifi_timespan rtt_spread; // difference between max and min rtt times recorded in picoseconds 160 // Note: Only applicable for IEEE 802.11mc 161 int distance_mm; // distance in mm (optional) 162 int distance_sd_mm; // standard deviation in mm (optional) 163 int distance_spread_mm; // difference between max and min distance recorded in mm (optional) 164 wifi_timestamp ts; // time of the measurement (in microseconds since boot) 165 int burst_duration; // in ms, actual time taken by the FW to finish one burst 166 // measurement. Applies to 1-sided and 2-sided RTT. 167 int negotiated_burst_num; // Number of bursts allowed by the responder. Applies 168 // to 2-sided 11mc RTT only. 169 wifi_information_element *LCI; // for 11mc and 11az only 170 wifi_information_element *LCR; // for 11mc and 11az only 171 } wifi_rtt_result; 172 173 /* RTT results version 2 */ 174 typedef struct { 175 wifi_rtt_result rtt_result; // Legacy wifi rtt result structure 176 wifi_channel frequency; // primary channel frequency (MHz) used for ranging measurements 177 // If frequency is unknown, this will be set to |UNSPECIFIED(-1)| 178 wifi_rtt_bw packet_bw; // RTT packet bandwidth is an average BW of the BWs of RTT frames. 179 // Cap the average close to a specific valid RttBw. 180 } wifi_rtt_result_v2; 181 182 /* RTT results v3 (11az support)*/ 183 typedef struct { 184 wifi_rtt_result_v2 rtt_result; 185 byte i2r_tx_ltf_repetition_count;// Multiple transmissions of HE-LTF symbols in an HE (I2R) 186 // Ranging NDP. An HE-LTF repetition value of 1 indicates no 187 // repetitions. 188 byte r2i_tx_ltf_repetition_count;// Multiple transmissions of HE-LTF symbols in an HE (R2I) 189 // Ranging NDP. An HE-LTF repetition value of 1 indicates no 190 // repetitions. 191 u64 ntb_min_measurement_time; // Minimum non-trigger based (non-TB) dynamic measurement time 192 // in units of 100 microseconds assigned by the 11az responder. 193 u64 ntb_max_measurement_time; // Maximum non-trigger based (non-TB) dynamic measurement 194 // time in units of 10 milliseconds assigned by the 11az 195 // responder. 196 byte num_tx_sts; // Number of transmit space-time streams used. 197 byte num_rx_sts; // Number of receive space-time streams used. 198 } wifi_rtt_result_v3; 199 200 201 /* RTT result callbacks */ 202 typedef struct { 203 /* 204 * This callback is deprecated on Android 14 and onwards. Newer implementations should support 205 * on_rtt_results_v2 callback. 206 */ 207 void (*on_rtt_results) (wifi_request_id id, 208 unsigned num_results, 209 wifi_rtt_result *rtt_result[]); 210 211 /* 212 * Called when vendor implementation supports sending RTT results version 2. 213 * 214 * Note: This callback is deprecated on Android 15 onwards. Newer implementation should support 215 * on_rtt_results_v3. 216 */ 217 void (*on_rtt_results_v2) (wifi_request_id id, 218 unsigned num_results, 219 wifi_rtt_result_v2 *rtt_result_v2[]); 220 } wifi_rtt_event_handler; 221 222 /* API to request RTT measurement */ 223 wifi_error wifi_rtt_range_request(wifi_request_id id, wifi_interface_handle iface, 224 unsigned num_rtt_config, wifi_rtt_config rtt_config[], wifi_rtt_event_handler handler); 225 226 /* RTT result v3 callback (11az support) */ 227 typedef struct { 228 /* 229 * Called when vendor implementation supports sending RTT results version 3 (Added support for 230 * 11az ranging) 231 */ 232 void (*on_rtt_results_v3) (wifi_request_id id, 233 unsigned num_results, 234 wifi_rtt_result_v3 *rtt_result_v3[]); 235 } wifi_rtt_event_handler_v3; 236 237 238 /* v3 API to request RTT measurement(11az support). */ 239 wifi_error wifi_rtt_range_request_v3(wifi_request_id id, 240 wifi_interface_handle iface, 241 unsigned num_rtt_config, 242 wifi_rtt_config_v3 rtt_config_v3[], 243 wifi_rtt_event_handler_v3 handler); 244 245 /* API to cancel RTT measurements */ 246 wifi_error wifi_rtt_range_cancel(wifi_request_id id, wifi_interface_handle iface, 247 unsigned num_devices, mac_addr addr[]); 248 249 /* NBD ranging channel map */ 250 typedef struct { 251 wifi_channel availablity[32]; // specifies the channel map for each of the 16 TU windows 252 // frequency of 0 => unspecified; which means firmware is 253 // free to do whatever it wants in this window. 254 } wifi_channel_map; 255 256 /* API to start publishing the channel map on responder device in a NBD cluster. 257 Responder device will take this request and schedule broadcasting the channel map 258 in a NBD ranging attribute in a SDF. DE will automatically remove the ranging 259 attribute from the OTA queue after number of DW specified by num_dw 260 where Each DW is 512 TUs apart */ 261 wifi_error wifi_rtt_channel_map_set(wifi_request_id id, 262 wifi_interface_handle iface, wifi_channel_map *params, unsigned num_dw); 263 264 /* API to clear the channel map on the responder device in a NBD cluster. 265 Responder device will cancel future ranging channel request, starting from “next” 266 DW interval and will also stop broadcasting NBD ranging attribute in SDF */ 267 wifi_error wifi_rtt_channel_map_clear(wifi_request_id id, wifi_interface_handle iface); 268 269 // Preamble definition for bit mask used in wifi_rtt_capabilities 270 #define PREAMBLE_LEGACY 0x1 271 #define PREAMBLE_HT 0x2 272 #define PREAMBLE_VHT 0x4 273 #define PREAMBLE_HE 0x8 274 #define PREAMBLE_EHT 0x10 275 276 // BW definition for bit mask used in wifi_rtt_capabilities 277 #define BW_5_SUPPORT 0x1 278 #define BW_10_SUPPORT 0x2 279 #define BW_20_SUPPORT 0x4 280 #define BW_40_SUPPORT 0x8 281 #define BW_80_SUPPORT 0x10 282 #define BW_160_SUPPORT 0x20 283 #define BW_320_SUPPORT 0x40 284 285 /* RTT Capabilities */ 286 typedef struct { 287 byte rtt_one_sided_supported; // if 1-sided rtt data collection is supported 288 byte rtt_ftm_supported; // if ftm rtt data collection is supported 289 byte lci_support; // if initiator supports LCI request. Applies to 2-sided RTT 290 // (applies to both 11mc and 11az). 291 byte lcr_support; // if initiator supports LCR request. Applies to 2-sided RTT 292 // (applies to both 11mc and 11az). 293 byte preamble_support; // bit mask indicates what preamble is supported by 11mc 294 // initiator 295 byte bw_support; // bit mask indicates what BW is supported by 11mc initiator 296 byte responder_supported; // if 11mc responder mode is supported 297 byte mc_version; // draft 11mc spec version supported by chip. For instance, 298 // version 4.0 should be 40 and version 4.3 should be 43 etc. 299 } wifi_rtt_capabilities; 300 301 302 /* RTT capabilities of the device */ 303 wifi_error wifi_get_rtt_capabilities(wifi_interface_handle iface, 304 wifi_rtt_capabilities *capabilities); 305 306 /* RTT Capabilities v3 (11az support) */ 307 typedef struct { 308 wifi_rtt_capabilities rtt_capab; 309 byte az_preamble_support; // bit mask indicates what preamble is supported by the 11az 310 // initiator 311 byte az_bw_support; // bit mask indicates what BW is supported by 11az initiator 312 byte ntb_initiator_supported; // if 11az non-TB initiator is supported 313 byte ntb_responder_supported; // if 11az non-TB responder is supported 314 } wifi_rtt_capabilities_v3; 315 316 /* RTT capabilities v3 of the device (11az support) */ 317 wifi_error wifi_get_rtt_capabilities_v3(wifi_interface_handle iface, 318 wifi_rtt_capabilities_v3 *capabilities); 319 320 /* debugging definitions */ 321 enum { 322 RTT_DEBUG_DISABLE, 323 RTT_DEBUG_LOG, 324 RTT_DEBUG_PROTO, 325 RTT_DEBUG_BURST, 326 RTT_DEBUG_ACCURACY, 327 RTT_DEBUG_LOGDETAIL 328 }; //rtt debug type 329 330 enum { 331 RTT_DEBUG_FORMAT_TXT, 332 RTT_DEBUG_FORMAT_BINARY 333 }; //rtt debug format 334 335 typedef struct rtt_debug { 336 unsigned version; 337 unsigned len; // total length of after len field 338 unsigned type; // rtt debug type 339 unsigned format; //rtt debug format 340 char dbuf[0]; // debug content 341 } rtt_debug_t; 342 343 /* set configuration for debug */ 344 wifi_error wifi_rtt_debug_cfg(wifi_interface_handle h, unsigned rtt_dbg_type, char *cfgbuf, unsigned cfg_buf_size); 345 /* get the debug information */ 346 wifi_error wifi_rtt_debug_get(wifi_interface_handle h, rtt_debug_t **debugbuf); 347 /* free the debug buffer */ 348 wifi_error wifi_rtt_debug_free(wifi_interface_handle h, rtt_debug_t *debugbuf); 349 350 /* API for setting LCI/LCR information to be provided to a requestor */ 351 typedef enum { 352 WIFI_MOTION_NOT_EXPECTED = 0, // Not expected to change location 353 WIFI_MOTION_EXPECTED = 1, // Expected to change location 354 WIFI_MOTION_UNKNOWN = 2, // Movement pattern unknown 355 } wifi_motion_pattern; 356 357 typedef struct { 358 long latitude; // latitude in degrees * 2^25 , 2's complement 359 long longitude; // latitude in degrees * 2^25 , 2's complement 360 int altitude; // Altitude in units of 1/256 m 361 byte latitude_unc; // As defined in Section 2.3.2 of IETF RFC 6225 362 byte longitude_unc; // As defined in Section 2.3.2 of IETF RFC 6225 363 byte altitude_unc; // As defined in Section 2.4.5 from IETF RFC 6225: 364 365 //Following element for configuring the Z subelement 366 wifi_motion_pattern motion_pattern; 367 int floor; // floor in units of 1/16th of floor. 0x80000000 if unknown. 368 int height_above_floor; // in units of 1/64 m 369 int height_unc; // in units of 1/64 m. 0 if unknown 370 } wifi_lci_information; 371 372 typedef struct { 373 char country_code[2]; // country code 374 int length; // length of the info field 375 char civic_info[256]; // Civic info to be copied in FTM frame 376 } wifi_lcr_information; 377 378 // API to configure the LCI. Used in RTT Responder mode only 379 wifi_error wifi_set_lci(wifi_request_id id, wifi_interface_handle iface, 380 wifi_lci_information *lci); 381 382 // API to configure the LCR. Used in RTT Responder mode only. 383 wifi_error wifi_set_lcr(wifi_request_id id, wifi_interface_handle iface, 384 wifi_lcr_information *lcr); 385 386 /** 387 * RTT Responder information 388 */ 389 typedef struct { 390 wifi_channel_info channel; 391 wifi_rtt_preamble preamble; 392 } wifi_rtt_responder; 393 394 /** 395 * Get RTT responder information e.g. WiFi channel to enable responder on. 396 */ 397 wifi_error wifi_rtt_get_responder_info(wifi_interface_handle iface, 398 wifi_rtt_responder *responder_info); 399 400 /** 401 * Enable RTT responder mode. 402 * channel_hint - hint of the channel information where RTT responder should be enabled on. 403 * max_duration_seconds - timeout of responder mode. 404 * channel_used - channel used for RTT responder, NULL if responder is not enabled. 405 */ 406 wifi_error wifi_enable_responder(wifi_request_id id, wifi_interface_handle iface, 407 wifi_channel_info channel_hint, unsigned max_duration_seconds, 408 wifi_rtt_responder *responder_info); 409 410 /** 411 * Disable RTT responder mode. 412 */ 413 wifi_error wifi_disable_responder(wifi_request_id id, wifi_interface_handle iface); 414 415 #endif 416