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 typedef struct {
23     u8 requester_supported; // 0 for not supporting requester
24     u8 responder_supported; // 0 for not supporting responder
25     u8 broadcast_twt_supported; // 0 for not supporting broadcast TWT
26     u8 flexibile_twt_supported; // 0 for not supporting flexible TWT
27 } TwtCapability;
28 
29 typedef struct {
30     TwtCapability device_capability;
31     TwtCapability peer_capability;
32 } TwtCapabilitySet;
33 
34 // For all optional fields below, if no value specify -1
35 typedef struct {
36     u8 config_id;        // An unique ID for an individual TWT request
37     u8 negotiation_type; // 0 for individual TWT, 1 for broadcast TWT
38     u8 trigger_type;     // 0 for non-triggered TWT, 1 for triggered TWT
39     s32 wake_dur_us;     // Proposed wake duration in us
40     s32 wake_int_us;     // Average wake interval in us
41     s32 wake_int_min_us; // Min wake interval in us. Optional.
42     s32 wake_int_max_us; // Max wake interval in us. Optional.
43     s32 wake_dur_min_us; // Min wake duration in us. Optional.
44     s32 wake_dur_max_us; // Max wake duration in us. Optional.
45     s32 avg_pkt_size;    // Average bytes of each packet to send in each wake
46                          // duration. Optional.
47     s32 avg_pkt_num;     // Average number of packets to send in each wake
48                          // duration. Optional.
49     s32 wake_time_off_us; // First wake duration time offset in us. Optional.
50 } TwtSetupRequest;
51 
52 typedef enum {
53     TWT_SETUP_SUCCESS = 0, // TWT setup is accepted.
54     TWT_SETUP_REJECT = 1,  // TWT setup is rejected by AP.
55     TWT_SETUP_TIMEOUT = 2, // TWT setup response from AP times out.
56     TWT_SETUP_IE = 3,      // AP sent TWT Setup IE parsing failure.
57     TWT_SETUP_PARAMS = 4,  // AP sent TWT Setup IE Parameters invalid.
58     TWT_SETUP_ERROR = 255, // Generic error
59 } TwtSetupReasonCode;
60 
61 typedef struct {
62     u8 config_id; // An unique ID for an individual TWT request
63     u8 status;    // 0 for success, non-zero for failure
64     TwtSetupReasonCode reason_code;
65     u8 negotiation_type; // 0 for individual TWT, 1 for broadcast TWT
66     u8 trigger_type;     // 0 for non-triggered TWT, 1 for triggered TWT
67     s32 wake_dur_us;     // Proposed wake duration in us
68     s32 wake_int_us;     // Average wake interval in us
69     s32 wake_time_off_us; // First wake duration time offset in us.
70 } TwtSetupResponse;
71 
72 typedef struct {
73     u8 config_id;        // An unique ID for an individual TWT request
74     u8 all_twt;          // 0 for individual setp request, 1 for all TWT
75     u8 negotiation_type; // 0 for individual TWT, 1 for broadcast TWT
76 } TwtTeardownRequest;
77 
78 typedef enum {
79     TWT_TD_RC_HOST = 0,  // Teardown triggered by Host
80     TWT_TD_RC_PEER = 1,  // Peer initiated teardown
81     TWT_TD_RC_MCHAN = 2, // Teardown due to MCHAN Active
82     TWT_TD_RC_MCNX = 3,  // Teardown due to MultiConnection
83     TWT_TD_RC_CSA = 4,   // Teardown due to CSA
84     TWT_TD_RC_BTCX = 5,  // Teardown due to BT Coex
85     TWT_TD_RC_SETUP_FAIL = 6, // Setup fails midway. Teardown all connections
86     TWT_TD_RC_SCHED = 7,   // Teardown by TWT Scheduler
87     TWT_TD_RC_ERROR = 255, // Generic error cases
88 } TwtTeardownReason;
89 
90 typedef struct {
91     u8 config_id; // An unique ID for an individual TWT request
92     u8 all_twt;   // 0 for individual setp request, 1 for all TWT
93     u8 status;    // 0 for success, non-zero for failure
94     TwtTeardownReason reason;
95 } TwtTeardownCompletion;
96 
97 typedef struct {
98     u8 config_id;       // An unique ID for an individual TWT request
99     u8 all_twt;         // 0 for individual setup request, 1 for all TWT
100     s32 resume_time_us; // If -1, TWT is suspended for indefinite time.
101                         // Otherwise, TWT is suspended for resume_time_us
102 } TwtInfoFrameRequest;
103 
104 typedef enum {
105     TWT_INFO_RC_HOST  = 0, // Host initiated TWT Info frame */
106     TWT_INFO_RC_PEER  = 1, // Peer initiated TWT Info frame
107     TWT_INFO_RC_ERROR = 2, // Generic error conditions */
108 } TwtInfoFrameReason;
109 
110 // TWT Info frame triggered externally.
111 // Device should not send TwtInfoFrameReceived to Host for internally
112 // triggered TWT Info frame during SCAN, MCHAN operations.
113 typedef struct {
114     u8 config_id; // An unique ID for an individual TWT request
115     u8 all_twt;   // 0 for individual setup request, 1 for all TWT
116     u8 status;    // 0 for success, non-zero for failure
117     TwtInfoFrameReason reason;
118     u8 twt_resumed; // 1 - TWT resumed, 0 - TWT suspended
119 } TwtInfoFrameReceived;
120 
121 typedef struct {
122     u8 config_id;
123     u32 avg_pkt_num_tx; // Average number of Tx packets in each wake duration.
124     u32 avg_pkt_num_rx; // Average number of Rx packets in each wake duration.
125     u32 avg_tx_pkt_size; // Average bytes per Rx packet in each wake duration.
126     u32 avg_rx_pkt_size; // Average bytes per Rx packet in each wake duration.
127     u32 avg_eosp_dur_us; // Average duration of early terminated SP
128     u32 eosp_count;  // Count of early terminations
129     u32 num_sp; // Count of service period (SP), also known as wake duration.
130 } TwtStats;
131 
132 // Asynchronous notification from the device.
133 // For example, TWT was torn down by the device and later when the device is
134 // ready, it can send this async notification.
135 // This can be expandable in future.
136 typedef enum {
137    TWT_NOTIF_ALLOW_TWT  = 1, // Device ready to process TWT Setup request
138 } TwtNotification;
139 
140 typedef struct {
141     TwtNotification notification;
142 } TwtDeviceNotify;
143 
144 // Callbacks for various TWT responses and events
145 typedef struct {
146     // Callback for TWT setup response
147     void (*EventTwtSetupResponse)(TwtSetupResponse *event);
148     // Callback for TWT teardown completion
149     void (*EventTwtTeardownCompletion)(TwtTeardownCompletion* event);
150     // Callback for TWT info frame received event
151     void (*EventTwtInfoFrameReceived)(TwtInfoFrameReceived* event);
152     // Callback for TWT notification from the device
153     void (*EventTwtDeviceNotify)(TwtDeviceNotify* event);
154 } TwtCallbackHandler;
155 
156 #endif /* __WIFI_HAL_TWT_H__ */
157