xref: /linux/drivers/net/wireless/intel/iwlwifi/fw/api/time-event.h (revision a1ff5a7d78a036d6c2178ee5acd6ba4946243800)
1 /* SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause */
2 /*
3  * Copyright (C) 2012-2014, 2018-2020, 2022-2024 Intel Corporation
4  * Copyright (C) 2013-2015 Intel Mobile Communications GmbH
5  * Copyright (C) 2016-2017 Intel Deutschland GmbH
6  */
7 #ifndef __iwl_fw_api_time_event_h__
8 #define __iwl_fw_api_time_event_h__
9 
10 #include "fw/api/phy-ctxt.h"
11 
12 /* Time Event types, according to MAC type */
13 enum iwl_time_event_type {
14 	/* BSS Station Events */
15 	TE_BSS_STA_AGGRESSIVE_ASSOC,
16 	TE_BSS_STA_ASSOC,
17 	TE_BSS_EAP_DHCP_PROT,
18 	TE_BSS_QUIET_PERIOD,
19 
20 	/* P2P Device Events */
21 	TE_P2P_DEVICE_DISCOVERABLE,
22 	TE_P2P_DEVICE_LISTEN,
23 	TE_P2P_DEVICE_ACTION_SCAN,
24 	TE_P2P_DEVICE_FULL_SCAN,
25 
26 	/* P2P Client Events */
27 	TE_P2P_CLIENT_AGGRESSIVE_ASSOC,
28 	TE_P2P_CLIENT_ASSOC,
29 	TE_P2P_CLIENT_QUIET_PERIOD,
30 
31 	/* P2P GO Events */
32 	TE_P2P_GO_ASSOC_PROT,
33 	TE_P2P_GO_REPETITIVET_NOA,
34 	TE_P2P_GO_CT_WINDOW,
35 
36 	/* WiDi Sync Events */
37 	TE_WIDI_TX_SYNC,
38 
39 	/* Channel Switch NoA */
40 	TE_CHANNEL_SWITCH_PERIOD,
41 
42 	TE_MAX
43 }; /* MAC_EVENT_TYPE_API_E_VER_1 */
44 
45 /* Time event - defines for command API v1 */
46 
47 /*
48  * @TE_V1_FRAG_NONE: fragmentation of the time event is NOT allowed.
49  * @TE_V1_FRAG_SINGLE: fragmentation of the time event is allowed, but only
50  *	the first fragment is scheduled.
51  * @TE_V1_FRAG_DUAL: fragmentation of the time event is allowed, but only
52  *	the first 2 fragments are scheduled.
53  * @TE_V1_FRAG_ENDLESS: fragmentation of the time event is allowed, and any
54  *	number of fragments are valid.
55  *
56  * Other than the constant defined above, specifying a fragmentation value 'x'
57  * means that the event can be fragmented but only the first 'x' will be
58  * scheduled.
59  */
60 enum {
61 	TE_V1_FRAG_NONE = 0,
62 	TE_V1_FRAG_SINGLE = 1,
63 	TE_V1_FRAG_DUAL = 2,
64 	TE_V1_FRAG_ENDLESS = 0xffffffff
65 };
66 
67 /* If a Time Event can be fragmented, this is the max number of fragments */
68 #define TE_V1_FRAG_MAX_MSK	0x0fffffff
69 /* Repeat the time event endlessly (until removed) */
70 #define TE_V1_REPEAT_ENDLESS	0xffffffff
71 /* If a Time Event has bounded repetitions, this is the maximal value */
72 #define TE_V1_REPEAT_MAX_MSK_V1	0x0fffffff
73 
74 /* Time Event dependencies: none, on another TE, or in a specific time */
75 enum {
76 	TE_V1_INDEPENDENT		= 0,
77 	TE_V1_DEP_OTHER			= BIT(0),
78 	TE_V1_DEP_TSF			= BIT(1),
79 	TE_V1_EVENT_SOCIOPATHIC		= BIT(2),
80 }; /* MAC_EVENT_DEPENDENCY_POLICY_API_E_VER_2 */
81 
82 /*
83  * @TE_V1_NOTIF_NONE: no notifications
84  * @TE_V1_NOTIF_HOST_EVENT_START: request/receive notification on event start
85  * @TE_V1_NOTIF_HOST_EVENT_END:request/receive notification on event end
86  * @TE_V1_NOTIF_INTERNAL_EVENT_START: internal FW use
87  * @TE_V1_NOTIF_INTERNAL_EVENT_END: internal FW use.
88  * @TE_V1_NOTIF_HOST_FRAG_START: request/receive notification on frag start
89  * @TE_V1_NOTIF_HOST_FRAG_END:request/receive notification on frag end
90  * @TE_V1_NOTIF_INTERNAL_FRAG_START: internal FW use.
91  * @TE_V1_NOTIF_INTERNAL_FRAG_END: internal FW use.
92  *
93  * Supported Time event notifications configuration.
94  * A notification (both event and fragment) includes a status indicating weather
95  * the FW was able to schedule the event or not. For fragment start/end
96  * notification the status is always success. There is no start/end fragment
97  * notification for monolithic events.
98  */
99 enum {
100 	TE_V1_NOTIF_NONE = 0,
101 	TE_V1_NOTIF_HOST_EVENT_START = BIT(0),
102 	TE_V1_NOTIF_HOST_EVENT_END = BIT(1),
103 	TE_V1_NOTIF_INTERNAL_EVENT_START = BIT(2),
104 	TE_V1_NOTIF_INTERNAL_EVENT_END = BIT(3),
105 	TE_V1_NOTIF_HOST_FRAG_START = BIT(4),
106 	TE_V1_NOTIF_HOST_FRAG_END = BIT(5),
107 	TE_V1_NOTIF_INTERNAL_FRAG_START = BIT(6),
108 	TE_V1_NOTIF_INTERNAL_FRAG_END = BIT(7),
109 }; /* MAC_EVENT_ACTION_API_E_VER_2 */
110 
111 /* Time event - defines for command API */
112 
113 /*
114  * @TE_V2_FRAG_NONE: fragmentation of the time event is NOT allowed.
115  * @TE_V2_FRAG_SINGLE: fragmentation of the time event is allowed, but only
116  *  the first fragment is scheduled.
117  * @TE_V2_FRAG_DUAL: fragmentation of the time event is allowed, but only
118  *  the first 2 fragments are scheduled.
119  * @TE_V2_FRAG_ENDLESS: fragmentation of the time event is allowed, and any
120  *  number of fragments are valid.
121  *
122  * Other than the constant defined above, specifying a fragmentation value 'x'
123  * means that the event can be fragmented but only the first 'x' will be
124  * scheduled.
125  */
126 enum {
127 	TE_V2_FRAG_NONE = 0,
128 	TE_V2_FRAG_SINGLE = 1,
129 	TE_V2_FRAG_DUAL = 2,
130 	TE_V2_FRAG_MAX = 0xfe,
131 	TE_V2_FRAG_ENDLESS = 0xff
132 };
133 
134 /* Repeat the time event endlessly (until removed) */
135 #define TE_V2_REPEAT_ENDLESS	0xff
136 /* If a Time Event has bounded repetitions, this is the maximal value */
137 #define TE_V2_REPEAT_MAX	0xfe
138 
139 #define TE_V2_PLACEMENT_POS	12
140 #define TE_V2_ABSENCE_POS	15
141 
142 /**
143  * enum iwl_time_event_policy - Time event policy values
144  * A notification (both event and fragment) includes a status indicating weather
145  * the FW was able to schedule the event or not. For fragment start/end
146  * notification the status is always success. There is no start/end fragment
147  * notification for monolithic events.
148  *
149  * @TE_V2_DEFAULT_POLICY: independent, social, present, unoticable
150  * @TE_V2_NOTIF_HOST_EVENT_START: request/receive notification on event start
151  * @TE_V2_NOTIF_HOST_EVENT_END:request/receive notification on event end
152  * @TE_V2_NOTIF_INTERNAL_EVENT_START: internal FW use
153  * @TE_V2_NOTIF_INTERNAL_EVENT_END: internal FW use.
154  * @TE_V2_NOTIF_HOST_FRAG_START: request/receive notification on frag start
155  * @TE_V2_NOTIF_HOST_FRAG_END:request/receive notification on frag end
156  * @TE_V2_NOTIF_INTERNAL_FRAG_START: internal FW use.
157  * @TE_V2_NOTIF_INTERNAL_FRAG_END: internal FW use.
158  * @TE_V2_START_IMMEDIATELY: start time event immediately
159  * @TE_V2_DEP_OTHER: depends on another time event
160  * @TE_V2_DEP_TSF: depends on a specific time
161  * @TE_V2_EVENT_SOCIOPATHIC: can't co-exist with other events of tha same MAC
162  * @TE_V2_ABSENCE: are we present or absent during the Time Event.
163  */
164 enum iwl_time_event_policy {
165 	TE_V2_DEFAULT_POLICY = 0x0,
166 
167 	/* notifications (event start/stop, fragment start/stop) */
168 	TE_V2_NOTIF_HOST_EVENT_START = BIT(0),
169 	TE_V2_NOTIF_HOST_EVENT_END = BIT(1),
170 	TE_V2_NOTIF_INTERNAL_EVENT_START = BIT(2),
171 	TE_V2_NOTIF_INTERNAL_EVENT_END = BIT(3),
172 
173 	TE_V2_NOTIF_HOST_FRAG_START = BIT(4),
174 	TE_V2_NOTIF_HOST_FRAG_END = BIT(5),
175 	TE_V2_NOTIF_INTERNAL_FRAG_START = BIT(6),
176 	TE_V2_NOTIF_INTERNAL_FRAG_END = BIT(7),
177 	TE_V2_START_IMMEDIATELY = BIT(11),
178 
179 	/* placement characteristics */
180 	TE_V2_DEP_OTHER = BIT(TE_V2_PLACEMENT_POS),
181 	TE_V2_DEP_TSF = BIT(TE_V2_PLACEMENT_POS + 1),
182 	TE_V2_EVENT_SOCIOPATHIC = BIT(TE_V2_PLACEMENT_POS + 2),
183 
184 	/* are we present or absent during the Time Event. */
185 	TE_V2_ABSENCE = BIT(TE_V2_ABSENCE_POS),
186 };
187 
188 /**
189  * struct iwl_time_event_cmd - configuring Time Events
190  * with struct MAC_TIME_EVENT_DATA_API_S_VER_2 (see also
191  * with version 1. determined by IWL_UCODE_TLV_FLAGS)
192  * ( TIME_EVENT_CMD = 0x29 )
193  * @id_and_color: ID and color of the relevant MAC,
194  *	&enum iwl_ctxt_id_and_color
195  * @action: action to perform, one of &enum iwl_ctxt_action
196  * @id: this field has two meanings, depending on the action:
197  *	If the action is ADD, then it means the type of event to add.
198  *	For all other actions it is the unique event ID assigned when the
199  *	event was added by the FW.
200  * @apply_time: When to start the Time Event (in GP2)
201  * @max_delay: maximum delay to event's start (apply time), in TU
202  * @depends_on: the unique ID of the event we depend on (if any)
203  * @interval: interval between repetitions, in TU
204  * @duration: duration of event in TU
205  * @repeat: how many repetitions to do, can be TE_REPEAT_ENDLESS
206  * @max_frags: maximal number of fragments the Time Event can be divided to
207  * @policy: defines whether uCode shall notify the host or other uCode modules
208  *	on event and/or fragment start and/or end
209  *	using one of TE_INDEPENDENT, TE_DEP_OTHER, TE_DEP_TSF
210  *	TE_EVENT_SOCIOPATHIC
211  *	using TE_ABSENCE and using TE_NOTIF_*,
212  *	&enum iwl_time_event_policy
213  */
214 struct iwl_time_event_cmd {
215 	/* COMMON_INDEX_HDR_API_S_VER_1 */
216 	__le32 id_and_color;
217 	__le32 action;
218 	__le32 id;
219 	/* MAC_TIME_EVENT_DATA_API_S_VER_2 */
220 	__le32 apply_time;
221 	__le32 max_delay;
222 	__le32 depends_on;
223 	__le32 interval;
224 	__le32 duration;
225 	u8 repeat;
226 	u8 max_frags;
227 	__le16 policy;
228 } __packed; /* MAC_TIME_EVENT_CMD_API_S_VER_2 */
229 
230 /**
231  * struct iwl_time_event_resp - response structure to iwl_time_event_cmd
232  * @status: bit 0 indicates success, all others specify errors
233  * @id: the Time Event type
234  * @unique_id: the unique ID assigned (in ADD) or given (others) to the TE
235  * @id_and_color: ID and color of the relevant MAC,
236  *	&enum iwl_ctxt_id_and_color
237  */
238 struct iwl_time_event_resp {
239 	__le32 status;
240 	__le32 id;
241 	__le32 unique_id;
242 	__le32 id_and_color;
243 } __packed; /* MAC_TIME_EVENT_RSP_API_S_VER_1 */
244 
245 /**
246  * struct iwl_time_event_notif - notifications of time event start/stop
247  * ( TIME_EVENT_NOTIFICATION = 0x2a )
248  * @timestamp: action timestamp in GP2
249  * @session_id: session's unique id
250  * @unique_id: unique id of the Time Event itself
251  * @id_and_color: ID and color of the relevant MAC
252  * @action: &enum iwl_time_event_policy
253  * @status: true if scheduled, false otherwise (not executed)
254  */
255 struct iwl_time_event_notif {
256 	__le32 timestamp;
257 	__le32 session_id;
258 	__le32 unique_id;
259 	__le32 id_and_color;
260 	__le32 action;
261 	__le32 status;
262 } __packed; /* MAC_TIME_EVENT_NTFY_API_S_VER_1 */
263 
264 /*
265  * struct iwl_hs20_roc_req_tail - tail of iwl_hs20_roc_req
266  *
267  * @node_addr: Our MAC Address
268  * @reserved: reserved for alignment
269  * @apply_time: GP2 value to start (should always be the current GP2 value)
270  * @apply_time_max_delay: Maximum apply time delay value in TU. Defines max
271  *	time by which start of the event is allowed to be postponed.
272  * @duration: event duration in TU To calculate event duration:
273  *	timeEventDuration = min(duration, remainingQuota)
274  */
275 struct iwl_hs20_roc_req_tail {
276 	u8 node_addr[ETH_ALEN];
277 	__le16 reserved;
278 	__le32 apply_time;
279 	__le32 apply_time_max_delay;
280 	__le32 duration;
281 } __packed;
282 
283 /*
284  * Aux ROC command
285  *
286  * Command requests the firmware to create a time event for a certain duration
287  * and remain on the given channel. This is done by using the Aux framework in
288  * the FW.
289  * The command was first used for Hot Spot issues - but can be used regardless
290  * to Hot Spot.
291  *
292  * ( HOT_SPOT_CMD 0x53 )
293  *
294  * @id_and_color: ID and color of the MAC
295  * @action: action to perform, see &enum iwl_ctxt_action
296  * @event_unique_id: If the action FW_CTXT_ACTION_REMOVE then the
297  *	event_unique_id should be the id of the time event assigned by ucode.
298  *	Otherwise ignore the event_unique_id.
299  * @sta_id_and_color: station id and color, resumed during "Remain On Channel"
300  *	activity.
301  * @channel_info: channel info
302  */
303 struct iwl_hs20_roc_req {
304 	/* COMMON_INDEX_HDR_API_S_VER_1 hdr */
305 	__le32 id_and_color;
306 	__le32 action;
307 	__le32 event_unique_id;
308 	__le32 sta_id_and_color;
309 	struct iwl_fw_channel_info channel_info;
310 	struct iwl_hs20_roc_req_tail tail;
311 } __packed; /* HOT_SPOT_CMD_API_S_VER_1 */
312 
313 /*
314  * values for AUX ROC result values
315  */
316 enum iwl_mvm_hot_spot {
317 	HOT_SPOT_RSP_STATUS_OK,
318 	HOT_SPOT_RSP_STATUS_TOO_MANY_EVENTS,
319 	HOT_SPOT_MAX_NUM_OF_SESSIONS,
320 };
321 
322 /*
323  * Aux ROC command response
324  *
325  * In response to iwl_hs20_roc_req the FW sends this command to notify the
326  * driver the uid of the timevent.
327  *
328  * ( HOT_SPOT_CMD 0x53 )
329  *
330  * @event_unique_id: Unique ID of time event assigned by ucode
331  * @status: Return status 0 is success, all the rest used for specific errors
332  */
333 struct iwl_hs20_roc_res {
334 	__le32 event_unique_id;
335 	__le32 status;
336 } __packed; /* HOT_SPOT_RSP_API_S_VER_1 */
337 
338 /*
339  * Activity types for the ROC command
340  * @ROC_ACTIVITY_HOTSPOT: ROC for hs20 activity
341  * @ROC_ACTIVITY_P2P_DISC: ROC for p2p discoverability activity
342  * @ROC_ACTIVITY_P2P_TXRX: ROC for p2p action frames activity
343  * @ROC_ACTIVITY_P2P_NEG: ROC for p2p negotiation (used also for TX)
344  */
345 enum iwl_roc_activity {
346 	ROC_ACTIVITY_HOTSPOT,
347 	ROC_ACTIVITY_P2P_DISC,
348 	ROC_ACTIVITY_P2P_TXRX,
349 	ROC_ACTIVITY_P2P_NEG,
350 	ROC_NUM_ACTIVITIES
351 }; /* ROC_ACTIVITY_API_E_VER_1 */
352 
353 /*
354  * ROC command
355  *
356  * Command requests the firmware to remain on a channel for a certain duration.
357  *
358  * ( MAC_CONF_GROUP 0x3, ROC_CMD 0xE )
359  *
360  * @action: action to perform, see &enum iwl_ctxt_action
361  * @activity: type of activity, see &enum iwl_roc_activity
362  * @sta_id: station id, resumed during "Remain On Channel" activity.
363  * @channel_info: &struct iwl_fw_channel_info
364  * @node_addr: node MAC address for Rx filtering
365  * @reserved: align to a dword
366  * @max_delay: max delay the ROC can start in TU
367  * @duration: remain on channel duration in TU
368  */
369 struct iwl_roc_req {
370 	__le32 action;
371 	__le32 activity;
372 	__le32 sta_id;
373 	struct iwl_fw_channel_info channel_info;
374 	u8 node_addr[ETH_ALEN];
375 	__le16 reserved;
376 	__le32 max_delay;
377 	__le32 duration;
378 } __packed; /* ROC_CMD_API_S_VER_3 */
379 
380 /*
381  * ROC notification
382  *
383  * Notification when ROC startes and when ROC ended.
384  *
385  * ( MAC_CONF_GROUP 0x3, ROC_NOTIF 0xf8 )
386  *
387  * @status: true if ROC succeeded to start
388  * @start_end: true if ROC started, false if ROC ended
389  * @activity: notification to which activity - &enum iwl_roc_activity
390  */
391 struct iwl_roc_notif {
392 	__le32 success;
393 	__le32 started;
394 	__le32 activity;
395 } __packed; /* ROC_NOTIF_API_S_VER_1 */
396 
397 /**
398  * enum iwl_mvm_session_prot_conf_id - session protection's configurations
399  * @SESSION_PROTECT_CONF_ASSOC: Start a session protection for association.
400  *	The firmware will allocate two events.
401  *	Valid for BSS_STA and P2P_STA.
402  *	* A rather short event that can't be fragmented and with a very
403  *	high priority. If every goes well (99% of the cases) the
404  *	association should complete within this first event. During
405  *	that event, no other activity will happen in the firmware,
406  *	which is why it can't be too long.
407  *	The length of this event is hard-coded in the firmware: 300TUs.
408  *	* Another event which can be much longer (it's duration is
409  *	configurable by the driver) which has a slightly lower
410  *	priority and that can be fragmented allowing other activities
411  *	to run while this event is running.
412  *	The firmware will automatically remove both events once the driver sets
413  *	the BSS MAC as associated. Neither of the events will be removed
414  *	for the P2P_STA MAC.
415  *	Only the duration is configurable for this protection.
416  * @SESSION_PROTECT_CONF_GO_CLIENT_ASSOC: not used
417  * @SESSION_PROTECT_CONF_P2P_DEVICE_DISCOV: Schedule the P2P Device to be in
418  *	listen mode. Will be fragmented. Valid only on the P2P Device MAC.
419  *	Valid only on the P2P Device MAC. The firmware will take into account
420  *	the duration, the interval and the repetition count.
421  * @SESSION_PROTECT_CONF_P2P_GO_NEGOTIATION: Schedule the P2P Device to be be
422  *	able to run the GO Negotiation. Will not be fragmented and not
423  *	repetitive. Valid only on the P2P Device MAC. Only the duration will
424  *	be taken into account.
425  * @SESSION_PROTECT_CONF_MAX_ID: not used
426  */
427 enum iwl_mvm_session_prot_conf_id {
428 	SESSION_PROTECT_CONF_ASSOC,
429 	SESSION_PROTECT_CONF_GO_CLIENT_ASSOC,
430 	SESSION_PROTECT_CONF_P2P_DEVICE_DISCOV,
431 	SESSION_PROTECT_CONF_P2P_GO_NEGOTIATION,
432 	SESSION_PROTECT_CONF_MAX_ID,
433 }; /* SESSION_PROTECTION_CONF_ID_E_VER_1 */
434 
435 /**
436  * struct iwl_mvm_session_prot_cmd - configure a session protection
437  * @id_and_color: the id and color of the link (or mac, for command version 1)
438  *	for which this session protection is sent
439  * @action: can be either FW_CTXT_ACTION_ADD or FW_CTXT_ACTION_REMOVE,
440  *	see &enum iwl_ctxt_action
441  * @conf_id: see &enum iwl_mvm_session_prot_conf_id
442  * @duration_tu: the duration of the whole protection in TUs.
443  * @repetition_count: not used
444  * @interval: not used
445  *
446  * Note: the session protection will always be scheduled to start as
447  * early as possible, but the maximum delay is configuration dependent.
448  * The firmware supports only one concurrent session protection per vif.
449  * Adding a new session protection will remove any currently running session.
450  */
451 struct iwl_mvm_session_prot_cmd {
452 	/* COMMON_INDEX_HDR_API_S_VER_1 hdr */
453 	__le32 id_and_color;
454 	__le32 action;
455 	__le32 conf_id;
456 	__le32 duration_tu;
457 	__le32 repetition_count;
458 	__le32 interval;
459 } __packed;
460 /* SESSION_PROTECTION_CMD_API_S_VER_1 and
461  * SESSION_PROTECTION_CMD_API_S_VER_2
462  */
463 
464 /**
465  * struct iwl_mvm_session_prot_notif - session protection started / ended
466  * @mac_link_id: the mac id (or link id, for notif ver > 2) for which the
467  *	session protection started / ended
468  * @status: 1 means success, 0 means failure
469  * @start: 1 means the session protection started, 0 means it ended
470  * @conf_id: see &enum iwl_mvm_session_prot_conf_id
471  *
472  * Note that any session protection will always get two notifications: start
473  * and end even the firmware could not schedule it.
474  */
475 struct iwl_mvm_session_prot_notif {
476 	__le32 mac_link_id;
477 	__le32 status;
478 	__le32 start;
479 	__le32 conf_id;
480 } __packed;
481 /* SESSION_PROTECTION_NOTIFICATION_API_S_VER_2 and
482  * SESSION_PROTECTION_NOTIFICATION_API_S_VER_3
483  */
484 
485 #endif /* __iwl_fw_api_time_event_h__ */
486