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