From b4442c37ffd4aa4232a317131bff8f13669801ed Mon Sep 17 00:00:00 2001 From: Kevin Tang Date: Thu, 2 Apr 2015 16:05:51 -0700 Subject: enhancements to rtt.h Bug:19917983 Change-Id: Iebbc60f52b38875f661314908b72d17354f76b20 --- include/hardware_legacy/rtt.h | 207 +++++++++++++++++++++++++++--------------- 1 file changed, 135 insertions(+), 72 deletions(-) diff --git a/include/hardware_legacy/rtt.h b/include/hardware_legacy/rtt.h index 45937fc..f0c5b29 100644 --- a/include/hardware_legacy/rtt.h +++ b/include/hardware_legacy/rtt.h @@ -5,81 +5,142 @@ #ifndef __WIFI_HAL_RTT_H__ #define __WIFI_HAL_RTT_H__ -/* channel operating width */ - /* Ranging status */ typedef enum { - RTT_STATUS_SUCCESS, - RTT_STATUS_FAILURE, - RTT_STATUS_FAIL_NO_RSP, - RTT_STATUS_FAIL_INVALID_TS, // Invalid T1-T4 timestamp - RTT_STATUS_FAIL_PROTOCOL, // 11mc protocol failed - RTT_STATUS_FAIL_REJECTED, - RTT_STATUS_FAIL_NOT_SCHEDULED_YET, - RTT_STATUS_FAIL_SCHEDULE, // schedule failed - RTT_STATUS_FAIL_TM_TIMEOUT, - RTT_STATUS_FAIL_AP_ON_DIFF_CHANNEL, - RTT_STATUS_FAIL_NO_CAPABILITY, - RTT_STATUS_FAIL_BUSY_TRY_LATER, - RTT_STATUS_ABORTED + 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_INVALID, - RTT_TYPE_1_SIDED, - RTT_TYPE_2_SIDED, - RTT_TYPE_AUTO, // Two sided if remote supports; one sided otherwise + 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; // optional - rtt type hint. - // RTT_TYPE_AUTO implies best effort - wifi_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 interval; // interval between RTT burst (unit ms). - // Only valid when multi_burst = 1 - unsigned num_burst; // total number of RTT bursts, 1 means single shot - unsigned num_frames_per_burst; // num of frames in each RTT burst - // for single side, measurement result num = frame number - // for 2 side RTT, measurement result num = frame number - 1 - unsigned num_retries_per_measurement_frame; // retry time for RTT MEASUREMENT frame - - //following fields are only valid for 2 side RTT - unsigned num_retries_per_ftmr; - byte LCI_request; // request LCI or not - byte LCR_request; // request LCR or not - unsigned burst_timeout; // unit of 250 us - byte preamble; // 0- Legacy,1- HT, 2-VHT - byte bw; //5, 10, 20, 40, 80,160 + 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*/ +/* RTT results */ typedef struct { - mac_addr addr; // device mac address - unsigned burst_num; // # of burst inside a multi-burst request - unsigned measurement_number; // total RTT measurement Frames - unsigned success_number; // total successful RTT measurement Frames - byte number_per_burst_peer; //Max number of FTM numbers per burst the other side support, - //11mc only - wifi_rtt_status status; // ranging status - byte retry_after_duration; // in s , 11mc only, only for RTT_STATUS_FAIL_BUSY_TRY_LATER, 1-31s - 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; // TX rate - wifi_rate rx_rate; // Rx rate - 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, How long the FW time is to finish one burst measurement + 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; @@ -99,7 +160,7 @@ wifi_error wifi_rtt_range_cancel(wifi_request_id id, wifi_interface_handle ifac /* NBD ranging channel map */ typedef struct { - wifi_channel availablity[32]; // specifies the channel map for each of the 16 TU windows + 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; @@ -117,25 +178,27 @@ wifi_error wifi_rtt_channel_map_set(wifi_request_id id, 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 -#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 +// 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; - byte lcr_support; - byte preamble_support; //bit mask indicate what preamble is supported - byte bw_support; //bit mask indicate what BW 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 */ -- cgit v1.1