fw/api/time-event.h

0001 /* SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause */
0002 /*
0003  * Copyright (C) 2012-2014, 2018-2020 Intel Corporation
0004  * Copyright (C) 2013-2015 Intel Mobile Communications GmbH
0005  * Copyright (C) 2016-2017 Intel Deutschland GmbH
0006  */
0007 #ifndef __iwl_fw_api_time_event_h__
0008 #define __iwl_fw_api_time_event_h__
0009
0010 #include "fw/api/phy-ctxt.h"
0011
0012 /* Time Event types, according to MAC type */
0013 enum iwl_time_event_type {
0014     /* BSS Station Events */
0015     TE_BSS_STA_AGGRESSIVE_ASSOC,
0016     TE_BSS_STA_ASSOC,
0017     TE_BSS_EAP_DHCP_PROT,
0018     TE_BSS_QUIET_PERIOD,
0019
0020     /* P2P Device Events */
0021     TE_P2P_DEVICE_DISCOVERABLE,
0022     TE_P2P_DEVICE_LISTEN,
0023     TE_P2P_DEVICE_ACTION_SCAN,
0024     TE_P2P_DEVICE_FULL_SCAN,
0025
0026     /* P2P Client Events */
0027     TE_P2P_CLIENT_AGGRESSIVE_ASSOC,
0028     TE_P2P_CLIENT_ASSOC,
0029     TE_P2P_CLIENT_QUIET_PERIOD,
0030
0031     /* P2P GO Events */
0032     TE_P2P_GO_ASSOC_PROT,
0033     TE_P2P_GO_REPETITIVET_NOA,
0034     TE_P2P_GO_CT_WINDOW,
0035
0036     /* WiDi Sync Events */
0037     TE_WIDI_TX_SYNC,
0038
0039     /* Channel Switch NoA */
0040     TE_CHANNEL_SWITCH_PERIOD,
0041
0042     TE_MAX
0043 }; /* MAC_EVENT_TYPE_API_E_VER_1 */
0044
0045 /* Time event - defines for command API v1 */
0046
0047 /*
0048  * @TE_V1_FRAG_NONE: fragmentation of the time event is NOT allowed.
0049  * @TE_V1_FRAG_SINGLE: fragmentation of the time event is allowed, but only
0050  *  the first fragment is scheduled.
0051  * @TE_V1_FRAG_DUAL: fragmentation of the time event is allowed, but only
0052  *  the first 2 fragments are scheduled.
0053  * @TE_V1_FRAG_ENDLESS: fragmentation of the time event is allowed, and any
0054  *  number of fragments are valid.
0055  *
0056  * Other than the constant defined above, specifying a fragmentation value 'x'
0057  * means that the event can be fragmented but only the first 'x' will be
0058  * scheduled.
0059  */
0060 enum {
0061     TE_V1_FRAG_NONE = 0,
0062     TE_V1_FRAG_SINGLE = 1,
0063     TE_V1_FRAG_DUAL = 2,
0064     TE_V1_FRAG_ENDLESS = 0xffffffff
0065 };
0066
0067 /* If a Time Event can be fragmented, this is the max number of fragments */
0068 #define TE_V1_FRAG_MAX_MSK  0x0fffffff
0069 /* Repeat the time event endlessly (until removed) */
0070 #define TE_V1_REPEAT_ENDLESS    0xffffffff
0071 /* If a Time Event has bounded repetitions, this is the maximal value */
0072 #define TE_V1_REPEAT_MAX_MSK_V1 0x0fffffff
0073
0074 /* Time Event dependencies: none, on another TE, or in a specific time */
0075 enum {
0076     TE_V1_INDEPENDENT       = 0,
0077     TE_V1_DEP_OTHER         = BIT(0),
0078     TE_V1_DEP_TSF           = BIT(1),
0079     TE_V1_EVENT_SOCIOPATHIC     = BIT(2),
0080 }; /* MAC_EVENT_DEPENDENCY_POLICY_API_E_VER_2 */
0081
0082 /*
0083  * @TE_V1_NOTIF_NONE: no notifications
0084  * @TE_V1_NOTIF_HOST_EVENT_START: request/receive notification on event start
0085  * @TE_V1_NOTIF_HOST_EVENT_END:request/receive notification on event end
0086  * @TE_V1_NOTIF_INTERNAL_EVENT_START: internal FW use
0087  * @TE_V1_NOTIF_INTERNAL_EVENT_END: internal FW use.
0088  * @TE_V1_NOTIF_HOST_FRAG_START: request/receive notification on frag start
0089  * @TE_V1_NOTIF_HOST_FRAG_END:request/receive notification on frag end
0090  * @TE_V1_NOTIF_INTERNAL_FRAG_START: internal FW use.
0091  * @TE_V1_NOTIF_INTERNAL_FRAG_END: internal FW use.
0092  *
0093  * Supported Time event notifications configuration.
0094  * A notification (both event and fragment) includes a status indicating weather
0095  * the FW was able to schedule the event or not. For fragment start/end
0096  * notification the status is always success. There is no start/end fragment
0097  * notification for monolithic events.
0098  */
0099 enum {
0100     TE_V1_NOTIF_NONE = 0,
0101     TE_V1_NOTIF_HOST_EVENT_START = BIT(0),
0102     TE_V1_NOTIF_HOST_EVENT_END = BIT(1),
0103     TE_V1_NOTIF_INTERNAL_EVENT_START = BIT(2),
0104     TE_V1_NOTIF_INTERNAL_EVENT_END = BIT(3),
0105     TE_V1_NOTIF_HOST_FRAG_START = BIT(4),
0106     TE_V1_NOTIF_HOST_FRAG_END = BIT(5),
0107     TE_V1_NOTIF_INTERNAL_FRAG_START = BIT(6),
0108     TE_V1_NOTIF_INTERNAL_FRAG_END = BIT(7),
0109 }; /* MAC_EVENT_ACTION_API_E_VER_2 */
0110
0111 /* Time event - defines for command API */
0112
0113 /*
0114  * @TE_V2_FRAG_NONE: fragmentation of the time event is NOT allowed.
0115  * @TE_V2_FRAG_SINGLE: fragmentation of the time event is allowed, but only
0116  *  the first fragment is scheduled.
0117  * @TE_V2_FRAG_DUAL: fragmentation of the time event is allowed, but only
0118  *  the first 2 fragments are scheduled.
0119  * @TE_V2_FRAG_ENDLESS: fragmentation of the time event is allowed, and any
0120  *  number of fragments are valid.
0121  *
0122  * Other than the constant defined above, specifying a fragmentation value 'x'
0123  * means that the event can be fragmented but only the first 'x' will be
0124  * scheduled.
0125  */
0126 enum {
0127     TE_V2_FRAG_NONE = 0,
0128     TE_V2_FRAG_SINGLE = 1,
0129     TE_V2_FRAG_DUAL = 2,
0130     TE_V2_FRAG_MAX = 0xfe,
0131     TE_V2_FRAG_ENDLESS = 0xff
0132 };
0133
0134 /* Repeat the time event endlessly (until removed) */
0135 #define TE_V2_REPEAT_ENDLESS    0xff
0136 /* If a Time Event has bounded repetitions, this is the maximal value */
0137 #define TE_V2_REPEAT_MAX    0xfe
0138
0139 #define TE_V2_PLACEMENT_POS 12
0140 #define TE_V2_ABSENCE_POS   15
0141
0142 /**
0143  * enum iwl_time_event_policy - Time event policy values
0144  * A notification (both event and fragment) includes a status indicating weather
0145  * the FW was able to schedule the event or not. For fragment start/end
0146  * notification the status is always success. There is no start/end fragment
0147  * notification for monolithic events.
0148  *
0149  * @TE_V2_DEFAULT_POLICY: independent, social, present, unoticable
0150  * @TE_V2_NOTIF_HOST_EVENT_START: request/receive notification on event start
0151  * @TE_V2_NOTIF_HOST_EVENT_END:request/receive notification on event end
0152  * @TE_V2_NOTIF_INTERNAL_EVENT_START: internal FW use
0153  * @TE_V2_NOTIF_INTERNAL_EVENT_END: internal FW use.
0154  * @TE_V2_NOTIF_HOST_FRAG_START: request/receive notification on frag start
0155  * @TE_V2_NOTIF_HOST_FRAG_END:request/receive notification on frag end
0156  * @TE_V2_NOTIF_INTERNAL_FRAG_START: internal FW use.
0157  * @TE_V2_NOTIF_INTERNAL_FRAG_END: internal FW use.
0158  * @TE_V2_START_IMMEDIATELY: start time event immediately
0159  * @TE_V2_DEP_OTHER: depends on another time event
0160  * @TE_V2_DEP_TSF: depends on a specific time
0161  * @TE_V2_EVENT_SOCIOPATHIC: can't co-exist with other events of tha same MAC
0162  * @TE_V2_ABSENCE: are we present or absent during the Time Event.
0163  */
0164 enum iwl_time_event_policy {
0165     TE_V2_DEFAULT_POLICY = 0x0,
0166
0167     /* notifications (event start/stop, fragment start/stop) */
0168     TE_V2_NOTIF_HOST_EVENT_START = BIT(0),
0169     TE_V2_NOTIF_HOST_EVENT_END = BIT(1),
0170     TE_V2_NOTIF_INTERNAL_EVENT_START = BIT(2),
0171     TE_V2_NOTIF_INTERNAL_EVENT_END = BIT(3),
0172
0173     TE_V2_NOTIF_HOST_FRAG_START = BIT(4),
0174     TE_V2_NOTIF_HOST_FRAG_END = BIT(5),
0175     TE_V2_NOTIF_INTERNAL_FRAG_START = BIT(6),
0176     TE_V2_NOTIF_INTERNAL_FRAG_END = BIT(7),
0177     TE_V2_START_IMMEDIATELY = BIT(11),
0178
0179     /* placement characteristics */
0180     TE_V2_DEP_OTHER = BIT(TE_V2_PLACEMENT_POS),
0181     TE_V2_DEP_TSF = BIT(TE_V2_PLACEMENT_POS + 1),
0182     TE_V2_EVENT_SOCIOPATHIC = BIT(TE_V2_PLACEMENT_POS + 2),
0183
0184     /* are we present or absent during the Time Event. */
0185     TE_V2_ABSENCE = BIT(TE_V2_ABSENCE_POS),
0186 };
0187
0188 /**
0189  * struct iwl_time_event_cmd - configuring Time Events
0190  * with struct MAC_TIME_EVENT_DATA_API_S_VER_2 (see also
0191  * with version 1. determined by IWL_UCODE_TLV_FLAGS)
0192  * ( TIME_EVENT_CMD = 0x29 )
0193  * @id_and_color: ID and color of the relevant MAC,
0194  *  &enum iwl_ctxt_id_and_color
0195  * @action: action to perform, one of &enum iwl_ctxt_action
0196  * @id: this field has two meanings, depending on the action:
0197  *  If the action is ADD, then it means the type of event to add.
0198  *  For all other actions it is the unique event ID assigned when the
0199  *  event was added by the FW.
0200  * @apply_time: When to start the Time Event (in GP2)
0201  * @max_delay: maximum delay to event's start (apply time), in TU
0202  * @depends_on: the unique ID of the event we depend on (if any)
0203  * @interval: interval between repetitions, in TU
0204  * @duration: duration of event in TU
0205  * @repeat: how many repetitions to do, can be TE_REPEAT_ENDLESS
0206  * @max_frags: maximal number of fragments the Time Event can be divided to
0207  * @policy: defines whether uCode shall notify the host or other uCode modules
0208  *  on event and/or fragment start and/or end
0209  *  using one of TE_INDEPENDENT, TE_DEP_OTHER, TE_DEP_TSF
0210  *  TE_EVENT_SOCIOPATHIC
0211  *  using TE_ABSENCE and using TE_NOTIF_*,
0212  *  &enum iwl_time_event_policy
0213  */
0214 struct iwl_time_event_cmd {
0215     /* COMMON_INDEX_HDR_API_S_VER_1 */
0216     __le32 id_and_color;
0217     __le32 action;
0218     __le32 id;
0219     /* MAC_TIME_EVENT_DATA_API_S_VER_2 */
0220     __le32 apply_time;
0221     __le32 max_delay;
0222     __le32 depends_on;
0223     __le32 interval;
0224     __le32 duration;
0225     u8 repeat;
0226     u8 max_frags;
0227     __le16 policy;
0228 } __packed; /* MAC_TIME_EVENT_CMD_API_S_VER_2 */
0229
0230 /**
0231  * struct iwl_time_event_resp - response structure to iwl_time_event_cmd
0232  * @status: bit 0 indicates success, all others specify errors
0233  * @id: the Time Event type
0234  * @unique_id: the unique ID assigned (in ADD) or given (others) to the TE
0235  * @id_and_color: ID and color of the relevant MAC,
0236  *  &enum iwl_ctxt_id_and_color
0237  */
0238 struct iwl_time_event_resp {
0239     __le32 status;
0240     __le32 id;
0241     __le32 unique_id;
0242     __le32 id_and_color;
0243 } __packed; /* MAC_TIME_EVENT_RSP_API_S_VER_1 */
0244
0245 /**
0246  * struct iwl_time_event_notif - notifications of time event start/stop
0247  * ( TIME_EVENT_NOTIFICATION = 0x2a )
0248  * @timestamp: action timestamp in GP2
0249  * @session_id: session's unique id
0250  * @unique_id: unique id of the Time Event itself
0251  * @id_and_color: ID and color of the relevant MAC
0252  * @action: &enum iwl_time_event_policy
0253  * @status: true if scheduled, false otherwise (not executed)
0254  */
0255 struct iwl_time_event_notif {
0256     __le32 timestamp;
0257     __le32 session_id;
0258     __le32 unique_id;
0259     __le32 id_and_color;
0260     __le32 action;
0261     __le32 status;
0262 } __packed; /* MAC_TIME_EVENT_NTFY_API_S_VER_1 */
0263
0264 /*
0265  * struct iwl_hs20_roc_req_tail - tail of iwl_hs20_roc_req
0266  *
0267  * @node_addr: Our MAC Address
0268  * @reserved: reserved for alignment
0269  * @apply_time: GP2 value to start (should always be the current GP2 value)
0270  * @apply_time_max_delay: Maximum apply time delay value in TU. Defines max
0271  *  time by which start of the event is allowed to be postponed.
0272  * @duration: event duration in TU To calculate event duration:
0273  *  timeEventDuration = min(duration, remainingQuota)
0274  */
0275 struct iwl_hs20_roc_req_tail {
0276     u8 node_addr[ETH_ALEN];
0277     __le16 reserved;
0278     __le32 apply_time;
0279     __le32 apply_time_max_delay;
0280     __le32 duration;
0281 } __packed;
0282
0283 /*
0284  * Aux ROC command
0285  *
0286  * Command requests the firmware to create a time event for a certain duration
0287  * and remain on the given channel. This is done by using the Aux framework in
0288  * the FW.
0289  * The command was first used for Hot Spot issues - but can be used regardless
0290  * to Hot Spot.
0291  *
0292  * ( HOT_SPOT_CMD 0x53 )
0293  *
0294  * @id_and_color: ID and color of the MAC
0295  * @action: action to perform, one of FW_CTXT_ACTION_*
0296  * @event_unique_id: If the action FW_CTXT_ACTION_REMOVE then the
0297  *  event_unique_id should be the id of the time event assigned by ucode.
0298  *  Otherwise ignore the event_unique_id.
0299  * @sta_id_and_color: station id and color, resumed during "Remain On Channel"
0300  *  activity.
0301  * @channel_info: channel info
0302  */
0303 struct iwl_hs20_roc_req {
0304     /* COMMON_INDEX_HDR_API_S_VER_1 hdr */
0305     __le32 id_and_color;
0306     __le32 action;
0307     __le32 event_unique_id;
0308     __le32 sta_id_and_color;
0309     struct iwl_fw_channel_info channel_info;
0310     struct iwl_hs20_roc_req_tail tail;
0311 } __packed; /* HOT_SPOT_CMD_API_S_VER_1 */
0312
0313 /*
0314  * values for AUX ROC result values
0315  */
0316 enum iwl_mvm_hot_spot {
0317     HOT_SPOT_RSP_STATUS_OK,
0318     HOT_SPOT_RSP_STATUS_TOO_MANY_EVENTS,
0319     HOT_SPOT_MAX_NUM_OF_SESSIONS,
0320 };
0321
0322 /*
0323  * Aux ROC command response
0324  *
0325  * In response to iwl_hs20_roc_req the FW sends this command to notify the
0326  * driver the uid of the timevent.
0327  *
0328  * ( HOT_SPOT_CMD 0x53 )
0329  *
0330  * @event_unique_id: Unique ID of time event assigned by ucode
0331  * @status: Return status 0 is success, all the rest used for specific errors
0332  */
0333 struct iwl_hs20_roc_res {
0334     __le32 event_unique_id;
0335     __le32 status;
0336 } __packed; /* HOT_SPOT_RSP_API_S_VER_1 */
0337
0338 /**
0339  * enum iwl_mvm_session_prot_conf_id - session protection's configurations
0340  * @SESSION_PROTECT_CONF_ASSOC: Start a session protection for association.
0341  *  The firmware will allocate two events.
0342  *  Valid for BSS_STA and P2P_STA.
0343  *  * A rather short event that can't be fragmented and with a very
0344  *  high priority. If every goes well (99% of the cases) the
0345  *  association should complete within this first event. During
0346  *  that event, no other activity will happen in the firmware,
0347  *  which is why it can't be too long.
0348  *  The length of this event is hard-coded in the firmware: 300TUs.
0349  *  * Another event which can be much longer (it's duration is
0350  *  configurable by the driver) which has a slightly lower
0351  *  priority and that can be fragmented allowing other activities
0352  *  to run while this event is running.
0353  *  The firmware will automatically remove both events once the driver sets
0354  *  the BSS MAC as associated. Neither of the events will be removed
0355  *  for the P2P_STA MAC.
0356  *  Only the duration is configurable for this protection.
0357  * @SESSION_PROTECT_CONF_GO_CLIENT_ASSOC: not used
0358  * @SESSION_PROTECT_CONF_P2P_DEVICE_DISCOV: Schedule the P2P Device to be in
0359  *  listen mode. Will be fragmented. Valid only on the P2P Device MAC.
0360  *  Valid only on the P2P Device MAC. The firmware will take into account
0361  *  the duration, the interval and the repetition count.
0362  * @SESSION_PROTECT_CONF_P2P_GO_NEGOTIATION: Schedule the P2P Device to be be
0363  *  able to run the GO Negotiation. Will not be fragmented and not
0364  *  repetitive. Valid only on the P2P Device MAC. Only the duration will
0365  *  be taken into account.
0366  * @SESSION_PROTECT_CONF_MAX_ID: not used
0367  */
0368 enum iwl_mvm_session_prot_conf_id {
0369     SESSION_PROTECT_CONF_ASSOC,
0370     SESSION_PROTECT_CONF_GO_CLIENT_ASSOC,
0371     SESSION_PROTECT_CONF_P2P_DEVICE_DISCOV,
0372     SESSION_PROTECT_CONF_P2P_GO_NEGOTIATION,
0373     SESSION_PROTECT_CONF_MAX_ID,
0374 }; /* SESSION_PROTECTION_CONF_ID_E_VER_1 */
0375
0376 /**
0377  * struct iwl_mvm_session_prot_cmd - configure a session protection
0378  * @id_and_color: the id and color of the mac for which this session protection
0379  *  is sent
0380  * @action: can be either FW_CTXT_ACTION_ADD or FW_CTXT_ACTION_REMOVE
0381  * @conf_id: see &enum iwl_mvm_session_prot_conf_id
0382  * @duration_tu: the duration of the whole protection in TUs.
0383  * @repetition_count: not used
0384  * @interval: not used
0385  *
0386  * Note: the session protection will always be scheduled to start as
0387  * early as possible, but the maximum delay is configuration dependent.
0388  * The firmware supports only one concurrent session protection per vif.
0389  * Adding a new session protection will remove any currently running session.
0390  */
0391 struct iwl_mvm_session_prot_cmd {
0392     /* COMMON_INDEX_HDR_API_S_VER_1 hdr */
0393     __le32 id_and_color;
0394     __le32 action;
0395     __le32 conf_id;
0396     __le32 duration_tu;
0397     __le32 repetition_count;
0398     __le32 interval;
0399 } __packed; /* SESSION_PROTECTION_CMD_API_S_VER_1 */
0400
0401 /**
0402  * struct iwl_mvm_session_prot_notif - session protection started / ended
0403  * @mac_id: the mac id for which the session protection started / ended
0404  * @status: 1 means success, 0 means failure
0405  * @start: 1 means the session protection started, 0 means it ended
0406  * @conf_id: see &enum iwl_mvm_session_prot_conf_id
0407  *
0408  * Note that any session protection will always get two notifications: start
0409  * and end even the firmware could not schedule it.
0410  */
0411 struct iwl_mvm_session_prot_notif {
0412     __le32 mac_id;
0413     __le32 status;
0414     __le32 start;
0415     __le32 conf_id;
0416 } __packed; /* SESSION_PROTECTION_NOTIFICATION_API_S_VER_2 */
0417
0418 #endif /* __iwl_fw_api_time_event_h__ */