1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef __WIFI_HAL_TWT_H__ 18 #define __WIFI_HAL_TWT_H__ 19 20 #include "wifi_hal.h" 21 22 /** 23 * New HAL interface to Target Wake Time (TWT). 24 */ 25 26 /* TWT capabilities supported */ 27 typedef struct { 28 u8 is_twt_requester_supported; // 0 for not supporting twt requester 29 u8 is_twt_responder_supported; // 0 for not supporting twt responder 30 u8 is_broadcast_twt_supported; // 0 for not supporting broadcast twt 31 u8 is_flexible_twt_supported; // 0 for not supporting flexible twt schedules 32 u32 min_wake_duration_micros; // minimum twt wake duration capable in microseconds 33 u32 max_wake_duration_micros; // maximum twt wake duration capable in microseconds 34 u64 min_wake_interval_micros; // minimum twt wake interval capable in microseconds 35 u64 max_wake_interval_micros; // maximum twt wake interval capable in microseconds 36 } wifi_twt_capabilities; 37 38 /* TWT request parameters to setup or update a TWT session */ 39 typedef struct { 40 s8 mlo_link_id; // MLO Link id in case TWT is requesting for MLO connection. 41 // Otherwise UNSPECIFIED. 42 u32 min_wake_duration_micros; // minimum twt wake duration in microseconds 43 u32 max_wake_duration_micros; // maximum twt wake duration in microseconds 44 u64 min_wake_interval_micros; // minimum twt wake interval in microseconds 45 u64 max_wake_interval_micros; // maximum twt wake interval in microseconds 46 } wifi_twt_request; 47 48 /* TWT negotiation types */ 49 typedef enum { 50 WIFI_TWT_NEGO_TYPE_INDIVIDUAL, 51 WIFI_TWT_NEGO_TYPE_BROADCAST, 52 } wifi_twt_negotiation_type; 53 54 /* TWT session */ 55 typedef struct { 56 u32 session_id; // a unique identifier for the session 57 s8 mlo_link_id; // link id in case of MLO connection. Otherwise UNSPECIFIED. 58 u32 wake_duration_micros; // TWT service period in microseconds 59 u64 wake_interval_micros; // TWT wake interval for this session in microseconds 60 wifi_twt_negotiation_type negotiation_type; // TWT negotiation type 61 u8 is_trigger_enabled; // 0 if this TWT session is not trigger enabled 62 u8 is_announced; // 0 if this TWT session is not announced 63 u8 is_implicit; // 0 if this TWT session is not implicit 64 u8 is_protected; // 0 if this TWT session is not protected 65 u8 is_updatable; // 0 if this TWT session is not updatable 66 u8 is_suspendable; // 0 if this TWT session can not be suspended and resumed 67 u8 is_responder_pm_mode_enabled; // 0 if TWT responder does not intend to go to doze mode 68 // outside of TWT service periods 69 } wifi_twt_session; 70 71 /* TWT session stats */ 72 typedef struct { 73 u32 avg_pkt_num_tx; // Average number of Tx packets in each wake duration. 74 u32 avg_pkt_num_rx; // Average number of Rx packets in each wake duration. 75 u32 avg_tx_pkt_size; // Average bytes per Rx packet in each wake duration. 76 u32 avg_rx_pkt_size; // Average bytes per Rx packet in each wake duration. 77 u32 avg_eosp_dur_us; // Average duration of early terminated SP 78 u32 eosp_count; // Count of early terminations 79 } wifi_twt_session_stats; 80 81 /* TWT error codes */ 82 typedef enum { 83 WIFI_TWT_ERROR_CODE_FAILURE_UNKNOWN, // unknown failure 84 WIFI_TWT_ERROR_CODE_ALREADY_RESUMED, // TWT session is already resumed 85 WIFI_TWT_ERROR_CODE_ALREADY_SUSPENDED, // TWT session is already suspended 86 WIFI_TWT_ERROR_CODE_INVALID_PARAMS, // invalid parameters 87 WIFI_TWT_ERROR_CODE_MAX_SESSION_REACHED,// maximum number of sessions reached 88 WIFI_TWT_ERROR_CODE_NOT_AVAILABLE, // requested operation is not available 89 WIFI_TWT_ERROR_CODE_NOT_SUPPORTED, // requested operation is not supported 90 WIFI_TWT_ERROR_CODE_PEER_NOT_SUPPORTED, // requested operation is not supported by the 91 // peer 92 WIFI_TWT_ERROR_CODE_PEER_REJECTED, // requested operation is rejected by the peer 93 WIFI_TWT_ERROR_CODE_TIMEOUT, // requested operation is timed out 94 } wifi_twt_error_code; 95 96 /* TWT teardown reason codes */ 97 typedef enum { 98 WIFI_TWT_TEARDOWN_REASON_CODE_UNKNOWN, // unknown reason 99 WIFI_TWT_TEARDOWN_REASON_CODE_LOCALLY_REQUESTED, // teardown requested by the framework 100 WIFI_TWT_TEARDOWN_REASON_CODE_INTERNALLY_INITIATED, // teardown initiated internally by the 101 // firmware or driver. 102 WIFI_TWT_TEARDOWN_REASON_CODE_PEER_INITIATED, // teardown initiated by the peer 103 } wifi_twt_teardown_reason_code; 104 105 /** 106 * TWT events 107 * 108 * Each of the events has a wifi_request_id to match the command responsible for the event. If the 109 * id is 0, the event is an unsolicited. 110 */ 111 typedef struct { 112 /** 113 * Called to indicate a TWT failure. 114 * 115 * @param id Id used to identify the command. The value 0 indicates no associated command. 116 * @param error_code TWT error code. 117 */ 118 void (*on_twt_failure)(wifi_request_id id, wifi_twt_error_code error_code); 119 120 /** 121 * Called when a Target Wake Time session is created. See wifi_twt_session_setup. 122 * 123 * @param id Id used to identify the command. 124 * @param session TWT session created. 125 */ 126 void (*on_twt_session_create)(wifi_request_id id, wifi_twt_session session); 127 128 /** 129 * Called when a Target Wake Time session is updated. See wifi_twt_session_update. 130 * 131 * @param id Id used to identify the command. The value 0 indicates no associated command. 132 * @param twtSession TWT session. 133 */ 134 void (*on_twt_session_update)(wifi_request_id id, wifi_twt_session session); 135 136 /** 137 * Called when the Target Wake Time session is torn down. See wifi_twt_session_teardown. 138 * 139 * @param id Id used to identify the command. The value 0 indicates no associated command. 140 * @param session_id TWT session id. 141 * @param reason Teardown reason code. 142 */ 143 void (*on_twt_session_teardown)(wifi_request_id id, int session_id, 144 wifi_twt_teardown_reason_code reason); 145 146 /** 147 * Called when TWT session stats available. See wifi_twt_session_get_stats. 148 * 149 * @param id Id used to identify the command. 150 * @param session_id TWT session id. 151 * @param stats TWT session stats. 152 */ 153 void (*on_twt_session_stats)(wifi_request_id id, int session_id, wifi_twt_session_stats stats); 154 155 /** 156 * Called when the Target Wake Time session is suspended. See wifi_twt_session_suspend. 157 * 158 * @param id Id used to identify the command. 159 * @param session_id TWT session id. 160 */ 161 void (*on_twt_session_suspend)(wifi_request_id id, int session_id); 162 163 /** 164 * Called when the Target Wake Time session is resumed. See wifi_twt_session_resume. 165 * 166 * @param id Id used to identify the command. 167 * @param session_id TWT session id. 168 */ 169 void (*on_twt_session_resume)(wifi_request_id id, int session_id); 170 } wifi_twt_events; 171 172 /** 173 * Important note: Following legacy HAL TWT interface is deprecated. It will be removed in future. 174 * Please use the new interface listed above. 175 */ 176 typedef struct { 177 u8 requester_supported; // 0 for not supporting requester 178 u8 responder_supported; // 0 for not supporting responder 179 u8 broadcast_twt_supported; // 0 for not supporting broadcast TWT 180 u8 flexibile_twt_supported; // 0 for not supporting flexible TWT 181 } TwtCapability; 182 183 typedef struct { 184 TwtCapability device_capability; 185 TwtCapability peer_capability; 186 } TwtCapabilitySet; 187 188 // For all optional fields below, if no value specify -1 189 typedef struct { 190 u8 config_id; // An unique ID for an individual TWT request 191 u8 negotiation_type; // 0 for individual TWT, 1 for broadcast TWT 192 u8 trigger_type; // 0 for non-triggered TWT, 1 for triggered TWT 193 s32 wake_dur_us; // Proposed wake duration in us 194 s32 wake_int_us; // Average wake interval in us 195 s32 wake_int_min_us; // Min wake interval in us. Optional. 196 s32 wake_int_max_us; // Max wake interval in us. Optional. 197 s32 wake_dur_min_us; // Min wake duration in us. Optional. 198 s32 wake_dur_max_us; // Max wake duration in us. Optional. 199 s32 avg_pkt_size; // Average bytes of each packet to send in each wake 200 // duration. Optional. 201 s32 avg_pkt_num; // Average number of packets to send in each wake 202 // duration. Optional. 203 s32 wake_time_off_us; // First wake duration time offset in us. Optional. 204 } TwtSetupRequest; 205 206 typedef enum { 207 TWT_SETUP_SUCCESS = 0, // TWT setup is accepted. 208 TWT_SETUP_REJECT = 1, // TWT setup is rejected by AP. 209 TWT_SETUP_TIMEOUT = 2, // TWT setup response from AP times out. 210 TWT_SETUP_IE = 3, // AP sent TWT Setup IE parsing failure. 211 TWT_SETUP_PARAMS = 4, // AP sent TWT Setup IE Parameters invalid. 212 TWT_SETUP_ERROR = 255, // Generic error 213 } TwtSetupReasonCode; 214 215 typedef struct { 216 u8 config_id; // An unique ID for an individual TWT request 217 u8 status; // 0 for success, non-zero for failure 218 TwtSetupReasonCode reason_code; 219 u8 negotiation_type; // 0 for individual TWT, 1 for broadcast TWT 220 u8 trigger_type; // 0 for non-triggered TWT, 1 for triggered TWT 221 s32 wake_dur_us; // Proposed wake duration in us 222 s32 wake_int_us; // Average wake interval in us 223 s32 wake_time_off_us; // First wake duration time offset in us. 224 } TwtSetupResponse; 225 226 typedef struct { 227 u8 config_id; // An unique ID for an individual TWT request 228 u8 all_twt; // 0 for individual setp request, 1 for all TWT 229 u8 negotiation_type; // 0 for individual TWT, 1 for broadcast TWT 230 } TwtTeardownRequest; 231 232 typedef enum { 233 TWT_TD_RC_HOST = 0, // Teardown triggered by Host 234 TWT_TD_RC_PEER = 1, // Peer initiated teardown 235 TWT_TD_RC_MCHAN = 2, // Teardown due to MCHAN Active 236 TWT_TD_RC_MCNX = 3, // Teardown due to MultiConnection 237 TWT_TD_RC_CSA = 4, // Teardown due to CSA 238 TWT_TD_RC_BTCX = 5, // Teardown due to BT Coex 239 TWT_TD_RC_SETUP_FAIL = 6, // Setup fails midway. Teardown all connections 240 TWT_TD_RC_SCHED = 7, // Teardown by TWT Scheduler 241 TWT_TD_RC_ERROR = 255, // Generic error cases 242 } TwtTeardownReason; 243 244 typedef struct { 245 u8 config_id; // An unique ID for an individual TWT request 246 u8 all_twt; // 0 for individual setp request, 1 for all TWT 247 u8 status; // 0 for success, non-zero for failure 248 TwtTeardownReason reason; 249 } TwtTeardownCompletion; 250 251 typedef struct { 252 u8 config_id; // An unique ID for an individual TWT request 253 u8 all_twt; // 0 for individual setup request, 1 for all TWT 254 s32 resume_time_us; // If -1, TWT is suspended for indefinite time. 255 // Otherwise, TWT is suspended for resume_time_us 256 } TwtInfoFrameRequest; 257 258 typedef enum { 259 TWT_INFO_RC_HOST = 0, // Host initiated TWT Info frame */ 260 TWT_INFO_RC_PEER = 1, // Peer initiated TWT Info frame 261 TWT_INFO_RC_ERROR = 2, // Generic error conditions */ 262 } TwtInfoFrameReason; 263 264 // TWT Info frame triggered externally. 265 // Device should not send TwtInfoFrameReceived to Host for internally 266 // triggered TWT Info frame during SCAN, MCHAN operations. 267 typedef struct { 268 u8 config_id; // An unique ID for an individual TWT request 269 u8 all_twt; // 0 for individual setup request, 1 for all TWT 270 u8 status; // 0 for success, non-zero for failure 271 TwtInfoFrameReason reason; 272 u8 twt_resumed; // 1 - TWT resumed, 0 - TWT suspended 273 } TwtInfoFrameReceived; 274 275 typedef struct { 276 u8 config_id; 277 u32 avg_pkt_num_tx; // Average number of Tx packets in each wake duration. 278 u32 avg_pkt_num_rx; // Average number of Rx packets in each wake duration. 279 u32 avg_tx_pkt_size; // Average bytes per Rx packet in each wake duration. 280 u32 avg_rx_pkt_size; // Average bytes per Rx packet in each wake duration. 281 u32 avg_eosp_dur_us; // Average duration of early terminated SP 282 u32 eosp_count; // Count of early terminations 283 u32 num_sp; // Count of service period (SP), also known as wake duration. 284 } TwtStats; 285 286 // Asynchronous notification from the device. 287 // For example, TWT was torn down by the device and later when the device is 288 // ready, it can send this async notification. 289 // This can be expandable in future. 290 typedef enum { 291 TWT_NOTIF_ALLOW_TWT = 1, // Device ready to process TWT Setup request 292 } TwtNotification; 293 294 typedef struct { 295 TwtNotification notification; 296 } TwtDeviceNotify; 297 298 // Callbacks for various TWT responses and events 299 typedef struct { 300 // Callback for TWT setup response 301 void (*EventTwtSetupResponse)(TwtSetupResponse *event); 302 // Callback for TWT teardown completion 303 void (*EventTwtTeardownCompletion)(TwtTeardownCompletion* event); 304 // Callback for TWT info frame received event 305 void (*EventTwtInfoFrameReceived)(TwtInfoFrameReceived* event); 306 // Callback for TWT notification from the device 307 void (*EventTwtDeviceNotify)(TwtDeviceNotify* event); 308 } TwtCallbackHandler; 309 310 #endif /* __WIFI_HAL_TWT_H__ */ 311