Information contained within this part of the book is of interest only for advanced interaction of mac80211 with drivers to exploit more hardware capabilities and improve performance.
Mac80211 supports various ways of blinking LEDs. Wherever possible, device LEDs should be exposed as LED class devices and hooked up to the appropriate trigger, which will then be triggered appropriately by mac80211.
get name of TX LED
Parameters
Description
mac80211 creates a transmit LED trigger for each wireless hardware that can be used to drive LEDs if your driver registers a LED device. This function returns the name (or NULL if not configured for LEDs) of the trigger so you can automatically link the LED device.
Return
The name of the LED trigger. NULL if not configured for LEDs.
get name of RX LED
Parameters
Description
mac80211 creates a receive LED trigger for each wireless hardware that can be used to drive LEDs if your driver registers a LED device. This function returns the name (or NULL if not configured for LEDs) of the trigger so you can automatically link the LED device.
Return
The name of the LED trigger. NULL if not configured for LEDs.
get name of association LED
Parameters
Description
mac80211 creates a association LED trigger for each wireless hardware that can be used to drive LEDs if your driver registers a LED device. This function returns the name (or NULL if not configured for LEDs) of the trigger so you can automatically link the LED device.
Return
The name of the LED trigger. NULL if not configured for LEDs.
get name of radio LED
Parameters
Description
mac80211 creates a radio change LED trigger for each wireless hardware that can be used to drive LEDs if your driver registers a LED device. This function returns the name (or NULL if not configured for LEDs) of the trigger so you can automatically link the LED device.
Return
The name of the LED trigger. NULL if not configured for LEDs.
throughput blink description
Definition
struct ieee80211_tpt_blink {
int throughput;
int blink_time;
};
Members
throughput trigger flags
Constants
create throughput LED trigger
Parameters
Return
NULL (in case of error, or if no LED triggers are configured) or the name of the new trigger.
Note
This function must be called before ieee80211_register_hw().
mac80211 is capable of taking advantage of many hardware acceleration designs for encryption and decryption operations.
The set_key() callback in the struct ieee80211_ops for a given device is called to enable hardware acceleration of encryption and decryption. The callback takes a sta parameter that will be NULL for default keys or keys used for transmission only, or point to the station information for the peer for individual keys. Multiple transmission keys with the same key index may be used when VLANs are configured for an access point.
When transmitting, the TX control data will use the hw_key_idx selected by the driver by modifying the struct ieee80211_key_conf pointed to by the key parameter to the set_key() function.
The set_key() call for the SET_KEY command should return 0 if the key is now in use, -EOPNOTSUPP or -ENOSPC if it couldn’t be added; if you return 0 then hw_key_idx must be assigned to the hardware key index, you are free to use the full u8 range.
Note that in the case that the IEEE80211_HW_SW_CRYPTO_CONTROL flag is set, mac80211 will not automatically fall back to software crypto if enabling hardware crypto failed. The set_key() call may also return the value 1 to permit this specific key/algorithm to be done in software.
When the cmd is DISABLE_KEY then it must succeed.
Note that it is permissible to not decrypt a frame even if a key for it has been uploaded to hardware, the stack will not make any decision based on whether a key has been uploaded or not but rather based on the receive flags.
The struct ieee80211_key_conf structure pointed to by the key parameter is guaranteed to be valid until another call to set_key() removes it, but it can only be used as a cookie to differentiate keys.
In TKIP some HW need to be provided a phase 1 key, for RX decryption acceleration (i.e. iwlwifi). Those drivers should provide update_tkip_key handler. The update_tkip_key() call updates the driver with the new phase 1 key. This happens every time the iv16 wraps around (every 65536 packets). The set_key() call will happen only once for each key (unless the AP did rekeying), it will not include a valid phase 1 key. The valid phase 1 key is provided by update_tkip_key only. The trigger that makes mac80211 call this handler is software decryption with wrap around of iv16.
The set_default_unicast_key() call updates the default WEP key index configured to the hardware for WEP encryption type. This is required for devices that support offload of data packets (e.g. ARP responses).
key command
Constants
Description
Used with the set_key() callback in struct ieee80211_ops, this indicates whether a key is being removed or added.
key information
Definition
struct ieee80211_key_conf {
atomic64_t tx_pn;
u32 cipher;
u8 icv_len;
u8 iv_len;
u8 hw_key_idx;
u8 flags;
s8 keyidx;
u8 keylen;
u8 key[0];
};
Members
Description
This key information is given by mac80211 to the driver by the set_key() callback in struct ieee80211_ops.
key flags
Constants
Description
These flags are used for communication about keys between the driver and mac80211, with the flags parameter of struct ieee80211_key_conf.
get a TKIP phase 1 key
Parameters
Description
This function returns the TKIP phase 1 key for the IV32 taken from the given packet.
get a TKIP phase 1 key for IV32
Parameters
Description
This function returns the TKIP phase 1 key for the given IV32.
get a TKIP phase 2 key
Parameters
Description
This function computes the TKIP RC4 key for the IV values in the packet.
mac80211 has support for various powersave implementations.
First, it can support hardware that handles all powersaving by itself, such hardware should simply set the IEEE80211_HW_SUPPORTS_PS hardware flag. In that case, it will be told about the desired powersave mode with the IEEE80211_CONF_PS flag depending on the association status. The hardware must take care of sending nullfunc frames when necessary, i.e. when entering and leaving powersave mode. The hardware is required to look at the AID in beacons and signal to the AP that it woke up when it finds traffic directed to it.
IEEE80211_CONF_PS flag enabled means that the powersave mode defined in IEEE 802.11-2007 section 11.2 is enabled. This is not to be confused with hardware wakeup and sleep states. Driver is responsible for waking up the hardware before issuing commands to the hardware and putting it back to sleep at appropriate times.
When PS is enabled, hardware needs to wakeup for beacons and receive the buffered multicast/broadcast frames after the beacon. Also it must be possible to send frames and receive the acknowledment frame.
Other hardware designs cannot send nullfunc frames by themselves and also need software support for parsing the TIM bitmap. This is also supported by mac80211 by combining the IEEE80211_HW_SUPPORTS_PS and IEEE80211_HW_PS_NULLFUNC_STACK flags. The hardware is of course still required to pass up beacons. The hardware is still required to handle waking up for multicast traffic; if it cannot the driver must handle that as best as it can, mac80211 is too slow to do that.
Dynamic powersave is an extension to normal powersave in which the hardware stays awake for a user-specified period of time after sending a frame so that reply frames need not be buffered and therefore delayed to the next wakeup. It’s compromise of getting good enough latency when there’s data traffic and still saving significantly power in idle periods.
Dynamic powersave is simply supported by mac80211 enabling and disabling PS based on traffic. Driver needs to only set IEEE80211_HW_SUPPORTS_PS flag and mac80211 will handle everything automatically. Additionally, hardware having support for the dynamic PS feature may set the IEEE80211_HW_SUPPORTS_DYNAMIC_PS flag to indicate that it can support dynamic PS mode itself. The driver needs to look at the dynamic_ps_timeout hardware configuration value and use it that value whenever IEEE80211_CONF_PS is set. In this case mac80211 will disable dynamic PS feature in stack and will just keep IEEE80211_CONF_PS enabled whenever user has enabled powersave.
Driver informs U-APSD client support by enabling IEEE80211_VIF_SUPPORTS_UAPSD flag. The mode is configured through the uapsd parameter in conf_tx() operation. Hardware needs to send the QoS Nullfunc frames and stay awake until the service period has ended. To utilize U-APSD, dynamic powersave is disabled for voip AC and all frames from that AC are transmitted with powersave enabled.
Note: U-APSD client mode is not yet supported with IEEE80211_HW_PS_NULLFUNC_STACK.
Some hardware have beacon filter support to reduce host cpu wakeups which will reduce system power consumption. It usually works so that the firmware creates a checksum of the beacon but omits all constantly changing elements (TSF, TIM etc). Whenever the checksum changes the beacon is forwarded to the host, otherwise it will be just dropped. That way the host will only receive beacons where some relevant information (for example ERP protection or WMM settings) have changed.
Beacon filter support is advertised with the IEEE80211_VIF_BEACON_FILTER interface capability. The driver needs to enable beacon filter support whenever power save is enabled, that is IEEE80211_CONF_PS is set. When power save is enabled, the stack will not check for beacon loss and the driver needs to notify about loss of beacons with ieee80211_beacon_loss().
The time (or number of beacons missed) until the firmware notifies the driver of a beacon loss event (which in turn causes the driver to call ieee80211_beacon_loss()) should be configurable and will be controlled by mac80211 and the roaming algorithm in the future.
Since there may be constantly changing information elements that nothing in the software stack cares about, we will, in the future, have mac80211 tell the driver which information elements are interesting in the sense that we want to see changes in them. This will include
- a list of information element IDs
- a list of OUIs for the vendor information element
Ideally, the hardware would filter out any beacons without changes in the requested elements, but if it cannot support that it may, at the expense of some efficiency, filter out only a subset. For example, if the device doesn’t support checking for OUIs it should pass up all changes in all vendor information elements.
Note that change, for the sake of simplification, also includes information elements appearing or disappearing from the beacon.
Some hardware supports an “ignore list” instead, just make sure nothing that was requested is on the ignore list, and include commonly changing information element IDs in the ignore list, for example 11 (BSS load) and the various vendor-assigned IEs with unknown contents (128, 129, 133-136, 149, 150, 155, 156, 173, 176, 178, 179, 219); for forward compatibility it could also include some currently unused IDs.
In addition to these capabilities, hardware should support notifying the host of changes in the beacon RSSI. This is relevant to implement roaming when no traffic is flowing (when traffic is flowing we see the RSSI of the received data packets). This can consist in notifying the host when the RSSI changes significantly or when it drops below or rises above configurable thresholds. In the future these thresholds will also be configured by mac80211 (which gets them from userspace) to implement them as the roaming algorithm requires.
If the hardware cannot implement this, the driver should ask it to periodically pass beacon frames to the host so that software can do the signal strength threshold checking.
inform hardware does not receive beacons
Parameters
Description
When beacon filtering is enabled with IEEE80211_VIF_BEACON_FILTER and IEEE80211_CONF_PS is set, the driver needs to inform whenever the hardware is not receiving beacons with this function.
TBD
transmit queue configuration
Definition
struct ieee80211_tx_queue_params {
u16 txop;
u16 cw_min;
u16 cw_max;
u8 aifs;
bool acm;
bool uapsd;
};
Members
Description
The information provided in this structure is required for QoS transmit queue configuration. Cf. IEEE 802.11 7.3.2.29.
TBD
Some parts of the if_conf should be discussed here instead
Insert notes about VLAN interfaces with hw crypto here or in the hw crypto chapter.
In order to implement AP and P2P GO modes, mac80211 has support for client powersaving, both “legacy” PS (PS-Poll/null data) and uAPSD. There currently is no support for sAPSD.
There is one assumption that mac80211 makes, namely that a client will not poll with PS-Poll and trigger with uAPSD at the same time. Both are supported, and both can be used by the same client, but they can’t be used concurrently by the same client. This simplifies the driver code.
The first thing to keep in mind is that there is a flag for complete driver implementation: IEEE80211_HW_AP_LINK_PS. If this flag is set, mac80211 expects the driver to handle most of the state machine for powersaving clients and will ignore the PM bit in incoming frames. Drivers then use ieee80211_sta_ps_transition() to inform mac80211 of stations’ powersave transitions. In this mode, mac80211 also doesn’t handle PS-Poll/uAPSD.
In the mode without IEEE80211_HW_AP_LINK_PS, mac80211 will check the PM bit in incoming frames for client powersave transitions. When a station goes to sleep, we will stop transmitting to it. There is, however, a race condition: a station might go to sleep while there is data buffered on hardware queues. If the device has support for this it will reject frames, and the driver should give the frames back to mac80211 with the IEEE80211_TX_STAT_TX_FILTERED flag set which will cause mac80211 to retry the frame when the station wakes up. The driver is also notified of powersave transitions by calling its sta_notify callback.
When the station is asleep, it has three choices: it can wake up, it can PS-Poll, or it can possibly start a uAPSD service period. Waking up is implemented by simply transmitting all buffered (and filtered) frames to the station. This is the easiest case. When the station sends a PS-Poll or a uAPSD trigger frame, mac80211 will inform the driver of this with the allow_buffered_frames callback; this callback is optional. mac80211 will then transmit the frames as usual and set the IEEE80211_TX_CTL_NO_PS_BUFFER on each frame. The last frame in the service period (or the only response to a PS-Poll) also has IEEE80211_TX_STATUS_EOSP set to indicate that it ends the service period; as this frame must have TX status report it also sets IEEE80211_TX_CTL_REQ_TX_STATUS. When TX status is reported for this frame, the service period is marked has having ended and a new one can be started by the peer.
Additionally, non-bufferable MMPDUs can also be transmitted by mac80211 with the IEEE80211_TX_CTL_NO_PS_BUFFER set in them.
Another race condition can happen on some devices like iwlwifi when there are frames queued for the station and it wakes up or polls; the frames that are already queued could end up being transmitted first instead, causing reordering and/or wrong processing of the EOSP. The cause is that allowing frames to be transmitted to a certain station is out-of-band communication to the device. To allow this problem to be solved, the driver can call ieee80211_sta_block_awake() if frames are buffered when it is notified that the station went to sleep. When all these frames have been filtered (see above), it must call the function again to indicate that the station is no longer blocked.
If the driver buffers frames in the driver for aggregation in any way, it must use the ieee80211_sta_set_buffered() call when it is notified of the station going to sleep to inform mac80211 of any TIDs that have frames buffered. Note that when a station wakes up this information is reset (hence the requirement to call it when informed of the station going to sleep). Then, when a service period starts for any reason, release_buffered_frames is called with the number of frames to be released and which TIDs they are to come from. In this case, the driver is responsible for setting the EOSP (for uAPSD) and MORE_DATA bits in the released frames, to help the more_data parameter is passed to tell the driver if there is more data on other TIDs – the TIDs to release frames from are ignored since mac80211 doesn’t know how many frames the buffers for those TIDs contain.
If the driver also implement GO mode, where absence periods may shorten service periods (or abort PS-Poll responses), it must filter those response frames except in the case of frames that are buffered in the driver – those must remain buffered to avoid reordering. Because it is possible that no frames are released in this case, the driver must call ieee80211_sta_eosp() to indicate to mac80211 that the service period ended anyway.
Finally, if frames from multiple TIDs are released from mac80211 but the driver might reorder them, it must clear & set the flags appropriately (only the last frame may have IEEE80211_TX_STATUS_EOSP) and also take care of the EOSP and MORE_DATA bits in the frame. The driver may also use ieee80211_sta_eosp() in this case.
Note that if the driver ever buffers frames other than QoS-data frames, it must take care to never send a non-QoS-data frame as the last frame in a service period, adding a QoS-nulldata frame after a non-QoS-data frame if needed.
accessing buffered broadcast and multicast frames
Parameters
Description
Function for accessing buffered broadcast and multicast frames. If hardware/firmware does not implement buffering of broadcast/multicast frames when power saving is used, 802.11 code buffers them in the host memory. The low-level driver uses this function to fetch next buffered frame. In most cases, this is used when generating beacon frame.
Return
A pointer to the next buffered skb or NULL if no more buffered frames are available.
Note
buffered frames are returned only after DTIM beacon frame was generated with ieee80211_beacon_get() and the low-level driver must thus call ieee80211_beacon_get() first. ieee80211_get_buffered_bc() returns NULL if the previous generated beacon was not DTIM, so the low-level driver does not need to check for DTIM beacons separately and should be able to use common code for all beacons.
beacon generation function
Parameters
Description
See ieee80211_beacon_get_tim().
Return
See ieee80211_beacon_get_tim().
notify mac80211 about end of SP
Parameters
Description
When a device transmits frames in a way that it can’t tell mac80211 in the TX status about the EOSP, it must clear the IEEE80211_TX_STATUS_EOSP bit and call this function instead. This applies for PS-Poll as well as uAPSD.
Note that just like with _tx_status() and _rx() drivers must not mix calls to irqsafe/non-irqsafe versions, this function must not be mixed with those either. Use the all irqsafe, or all non-irqsafe, don’t mix!
frame release reason
Constants
PS transition for connected sta
Parameters
Description
When operating in AP mode with the IEEE80211_HW_AP_LINK_PS flag set, use this function to inform mac80211 about a connected station entering/leaving PS mode.
This function may not be called in IRQ context or with softirqs enabled.
Calls to this function for a single hardware must be synchronized against each other.
Return
0 on success. -EINVAL when the requested PS mode is already set.
PS transition for connected sta (in process context)
Parameters
Description
Like ieee80211_sta_ps_transition() but can be called in process context (internally disables bottom halves). Concurrent call restriction still applies.
Return
Like ieee80211_sta_ps_transition().
inform mac80211 about driver-buffered frames
Parameters
Description
If a driver buffers frames for a powersave station instead of passing them back to mac80211 for retransmission, the station may still need to be told that there are buffered frames via the TIM bit.
This function informs mac80211 whether or not there are frames that are buffered in the driver for a given TID; mac80211 can then use this data to set the TIM bit (NOTE: This may call back into the driver’s set_tim call! Beware of the locking!)
If all frames are released to the station (due to PS-poll or uAPSD) then the driver needs to inform mac80211 that there no longer are frames buffered. However, when the station wakes up mac80211 assumes that all buffered frames will be transmitted and clears this data, drivers need to make sure they inform mac80211 about all buffered frames on the sleep transition (sta_notify() with STA_NOTIFY_SLEEP).
Note that technically mac80211 only needs to know this per AC, not per TID, but since driver buffering will inevitably happen per TID (since it is related to aggregation) it is easier to make mac80211 map the TID to the AC as required instead of keeping track in all drivers that use this API.
block station from waking up
Parameters
Description
Some devices require that all frames that are on the queues for a specific station that went to sleep are flushed before a poll response or frames after the station woke up can be delivered to that it. Note that such frames must be rejected by the driver as filtered, with the appropriate status flag.
This function allows implementing this mode in a race-free manner.
To do this, a driver must keep track of the number of frames still enqueued for a specific station. If this number is not zero when the station goes to sleep, the driver must call this function to force mac80211 to consider the station to be asleep regardless of the station’s actual state. Once the number of outstanding frames reaches zero, the driver must call this function again to unblock the station. That will cause mac80211 to be able to send ps-poll responses, and if the station queried in the meantime then frames will also be sent out as a result of this. Additionally, the driver will be notified that the station woke up some time after it is unblocked, regardless of whether the station actually woke up while blocked or not.
TBD
Note: WDS with identical MAC address should almost always be OK
Insert notes about having multiple virtual interfaces with different MAC addresses here, note which configurations are supported by mac80211, add notes about supporting hw crypto with it.
iterate active interfaces
Parameters
Description
This function iterates over the interfaces associated with a given hardware that are currently active and calls the callback for them. This function allows the iterator function to sleep, when the iterator function is atomic ieee80211_iterate_active_interfaces_atomic can be used. Does not iterate over a new interface during add_interface().
iterate active interfaces
Parameters
Description
This function iterates over the interfaces associated with a given hardware that are currently active and calls the callback for them. This function requires the iterator callback function to be atomic, if that is not desired, use ieee80211_iterate_active_interfaces instead. Does not iterate over a new interface during add_interface().
TODO
station table entry
Definition
struct ieee80211_sta {
u32 supp_rates[NUM_NL80211_BANDS];
u8 addr[ETH_ALEN];
u16 aid;
struct ieee80211_sta_ht_cap ht_cap;
struct ieee80211_sta_vht_cap vht_cap;
u8 max_rx_aggregation_subframes;
bool wme;
u8 uapsd_queues;
u8 max_sp;
u8 rx_nss;
enum ieee80211_sta_rx_bandwidth bandwidth;
enum ieee80211_smps_mode smps_mode;
struct ieee80211_sta_rates __rcu * rates;
bool tdls;
bool tdls_initiator;
bool mfp;
u8 max_amsdu_subframes;
u16 max_amsdu_len;
bool support_p2p_ps;
u16 max_rc_amsdu_len;
struct ieee80211_txq * txq[IEEE80211_NUM_TIDS];
u8 drv_priv[0];
};
Members
indicates the maximal length of an A-MSDU in bytes. This field is always valid for packets with a VHT preamble. For packets with a HT preamble, additional limits apply:
Both additional HT limits must be enforced by the low level driver. This is defined by the spec (IEEE 802.11-2012 section 8.3.2.2 NOTE 2).
Description
A station table entry represents a station we are possibly communicating with. Since stations are RCU-managed in mac80211, any ieee80211_sta pointer you get access to must either be protected by rcu_read_lock() explicitly or implicitly, or you must take good care to not use such a pointer after a call to your sta_remove callback that removed it.
sta notify command
Constants
Description
Used with the sta_notify() callback in struct ieee80211_ops, this indicates if an associated station made a power state transition.
find a station
Parameters
Return
The station, if found. NULL otherwise.
Note
This function must be called under RCU lock and the resulting pointer is only valid under RCU lock as well.
find a station on hardware
Parameters
Return
The station, if found. NULL otherwise.
Note
This function must be called under RCU lock and the resulting pointer is only valid under RCU lock as well.
NOTE
DO NOT USE THIS FUNCTION with localaddr NULL if at all possible.
TBD
completed hardware scan
Parameters
Description
When hardware scan offload is used (i.e. the hw_scan() callback is assigned) this function needs to be called by the driver to notify mac80211 that the scan finished. This function can be called from any context, including hardirq context.
Aggregation on the TX side requires setting the hardware flag IEEE80211_HW_AMPDU_AGGREGATION. The driver will then be handed packets with a flag indicating A-MPDU aggregation. The driver or device is responsible for actually aggregating the frames, as well as deciding how many and which to aggregate.
When TX aggregation is started by some subsystem (usually the rate control algorithm would be appropriate) by calling the ieee80211_start_tx_ba_session() function, the driver will be notified via its ampdu_action function, with the IEEE80211_AMPDU_TX_START action.
In response to that, the driver is later required to call the ieee80211_start_tx_ba_cb_irqsafe() function, which will really start the aggregation session after the peer has also responded. If the peer responds negatively, the session will be stopped again right away. Note that it is possible for the aggregation session to be stopped before the driver has indicated that it is done setting it up, in which case it must not indicate the setup completion.
Also note that, since we also need to wait for a response from the peer, the driver is notified of the completion of the handshake by the IEEE80211_AMPDU_TX_OPERATIONAL action to the ampdu_action callback.
Similarly, when the aggregation session is stopped by the peer or something calling ieee80211_stop_tx_ba_session(), the driver’s ampdu_action function will be called with the action IEEE80211_AMPDU_TX_STOP. In this case, the call must not fail, and the driver must later call ieee80211_stop_tx_ba_cb_irqsafe(). Note that the sta can get destroyed before the BA tear down is complete.
Aggregation on the RX side requires only implementing the ampdu_action callback that is invoked to start/stop any block-ack sessions for RX aggregation.
When RX aggregation is started by the peer, the driver is notified via ampdu_action function, with the IEEE80211_AMPDU_RX_START action, and may reject the request in which case a negative response is sent to the peer, if it accepts it a positive response is sent.
While the session is active, the device/driver are required to de-aggregate frames and pass them up one by one to mac80211, which will handle the reorder buffer.
When the aggregation session is stopped again by the peer or ourselves, the driver’s ampdu_action function will be called with the action IEEE80211_AMPDU_RX_STOP. In this case, the call must not fail.
A-MPDU actions
Constants
Description
These flags are used with the ampdu_action() callback in struct ieee80211_ops to indicate which action is needed.
Note that drivers MUST be able to deal with a TX aggregation session being stopped even before they OK’ed starting it by calling ieee80211_start_tx_ba_cb_irqsafe, because the peer might receive the addBA frame and send a delBA right away!
SMPS (Spatial multiplexing power save) is a mechanism to conserve power in an 802.11n implementation. For details on the mechanism and rationale, please refer to 802.11 (as amended by 802.11n-2009) “11.2.3 SM power save”.
The mac80211 implementation is capable of sending action frames to update the AP about the station’s SMPS mode, and will instruct the driver to enter the specific mode. It will also announce the requested SMPS mode during the association handshake. Hardware support for this feature is required, and can be indicated by hardware flags.
The default mode will be “automatic”, which nl80211/cfg80211 defines to be dynamic SMPS in (regular) powersave, and SMPS turned off otherwise.
To support this feature, the driver must set the appropriate hardware support flags, and handle the SMPS flag to the config() operation. It will then with this mechanism be instructed to enter the requested SMPS mode while associated to an HT AP.
request SM PS transition
Parameters
Description
This allows the driver to request an SM PS transition in managed mode. This is useful when the driver has more information than the stack about possible interference, for example by bluetooth.
spatial multiplexing power save mode
Constants
TBD
This part of the book describes the rate control algorithm interface and how it relates to mac80211 and drivers.
TBD
Start a tx Block Ack session.
Parameters
Return
success if addBA request was sent, failure otherwise
Although mac80211/low level driver/user space application can estimate the need to start aggregation on a certain RA/TID, the session level will be managed by the mac80211.
low level driver ready to aggregate.
Parameters
Description
This function must be called by low level driver once it has finished with preparations for the BA session. It can be called from any context.
Stop a Block Ack session.
Parameters
Return
negative error if the TID is invalid, or no aggregation active
Although mac80211/low level driver/user space application can estimate the need to stop aggregation on a certain RA/TID, the session level will be managed by the mac80211.
low level driver ready to stop aggregate.
Parameters
Description
This function must be called by low level driver once it has finished with preparations for the BA session tear down. It can be called from any context.
flags to indicate what changed
Constants
rate control information for/from RC algo
Definition
struct ieee80211_tx_rate_control {
struct ieee80211_hw * hw;
struct ieee80211_supported_band * sband;
struct ieee80211_bss_conf * bss_conf;
struct sk_buff * skb;
struct ieee80211_tx_rate reported_rate;
bool rts;
bool short_preamble;
u8 max_rate_idx;
u32 rate_idx_mask;
u8 * rate_idx_mcs_mask;
bool bss;
};
Members
helper for drivers for management/no-ack frames
Parameters
Description
Rate control algorithms that agree to use the lowest rate to send management frames and NO_ACK data with the respective hw retries should use this in the beginning of their mac80211 get_rate callback. If true is returned the rate control can simply return. If false is returned we guarantee that sta and sta and priv_sta is not null.
Rate control algorithms wishing to do more intelligent selection of rate for multicast/broadcast frames may choose to not use this.
TBD
This part of the book describes mac80211 internals.
Key handling in mac80211 is done based on per-interface (sub_if_data) keys and per-station keys. Since each station belongs to an interface, each station key also belongs to that interface.
Hardware acceleration is done on a best-effort basis for algorithms that are implemented in software, for each key the hardware is asked to enable that key for offloading but if it cannot do that the key is simply kept for software encryption (unless it is for an algorithm that isn’t implemented in software). There is currently no way of knowing whether a key is handled in SW or HW except by looking into debugfs.
All key management is internally protected by a mutex. Within all other parts of mac80211, key references are, just as STA structure references, protected by RCU. Note, however, that some things are unprotected, namely the key->sta dereferences within the hardware acceleration functions. This means that sta_info_destroy() must remove the key which waits for an RCU grace period.
TBD
TBD
TBD
STA information
Definition
struct sta_info {
struct list_head list;
struct list_head free_list;
struct rcu_head rcu_head;
struct rhlist_head hash_node;
u8 addr[ETH_ALEN];
struct ieee80211_local * local;
struct ieee80211_sub_if_data * sdata;
struct ieee80211_key __rcu * gtk[NUM_DEFAULT_KEYS + NUM_DEFAULT_MGMT_KEYS];
struct ieee80211_key __rcu * ptk[NUM_DEFAULT_KEYS];
u8 ptk_idx;
struct rate_control_ref * rate_ctrl;
void * rate_ctrl_priv;
spinlock_t rate_ctrl_lock;
spinlock_t lock;
struct ieee80211_fast_tx __rcu * fast_tx;
struct ieee80211_fast_rx __rcu * fast_rx;
struct ieee80211_sta_rx_stats __percpu * pcpu_rx_stats;
#ifdef CONFIG_MAC80211_MESH
struct mesh_sta * mesh;
#endif
struct work_struct drv_deliver_wk;
u16 listen_interval;
bool dead;
bool removed;
bool uploaded;
enum ieee80211_sta_state sta_state;
unsigned long _flags;
spinlock_t ps_lock;
struct sk_buff_head ps_tx_buf[IEEE80211_NUM_ACS];
struct sk_buff_head tx_filtered[IEEE80211_NUM_ACS];
unsigned long driver_buffered_tids;
unsigned long txq_buffered_tids;
long last_connected;
struct ieee80211_sta_rx_stats rx_stats;
struct tx_stats;
u16 tid_seq[IEEE80211_QOS_CTL_TID_MASK + 1];
struct sta_ampdu_mlme ampdu_mlme;
u8 timer_to_tid[IEEE80211_NUM_TIDS];
#ifdef CONFIG_MAC80211_DEBUGFS
struct dentry * debugfs_dir;
#endif
enum ieee80211_sta_rx_bandwidth cur_max_bandwidth;
enum ieee80211_smps_mode known_smps_mode;
const struct ieee80211_cipher_scheme * cipher_scheme;
u8 reserved_tid;
struct cfg80211_chan_def tdls_chandef;
struct ieee80211_sta sta;
};
Members
Description
This structure collects information about a station that mac80211 is communicating with.
Stations flags
Constants
Description
These flags are used with struct sta_info‘s flags member, but only indirectly with set_sta_flag() and friends.
STA info structures (struct sta_info) are managed in a hash table for faster lookup and a list for iteration. They are managed using RCU, i.e. access to the list and hash table is protected by RCU.
Upon allocating a STA info structure with sta_info_alloc(), the caller owns that structure. It must then insert it into the hash table using either sta_info_insert() or sta_info_insert_rcu(); only in the latter case (which acquires an rcu read section but must not be called from within one) will the pointer still be valid after the call. Note that the caller may not do much with the STA info before inserting it, in particular, it may not start any mesh peer link management or add encryption keys.
When the insertion fails (sta_info_insert()) returns non-zero), the structure will have been freed by sta_info_insert()!
Station entries are added by mac80211 when you establish a link with a peer. This means different things for the different type of interfaces we support. For a regular station this mean we add the AP sta when we receive an association response from the AP. For IBSS this occurs when get to know about a peer on the same IBSS. For WDS we add the sta for the peer immediately upon device open. When using AP mode we add stations for each respective station upon request from userspace through nl80211.
In order to remove a STA info structure, various sta_info_destroy_*() calls are available.
There is no concept of ownership on a STA entry, each structure is owned by the global hash table/list until it is removed. All users of the structure need to be RCU protected so that the structure won’t be freed before they are done using it.
STA aggregation information.
Definition
struct sta_ampdu_mlme {
struct mutex mtx;
struct tid_ampdu_rx __rcu * tid_rx[IEEE80211_NUM_TIDS];
u8 tid_rx_token[IEEE80211_NUM_TIDS];
unsigned long tid_rx_timer_expired[BITS_TO_LONGS(IEEE80211_NUM_TIDS)];
unsigned long tid_rx_stop_requested[BITS_TO_LONGS(IEEE80211_NUM_TIDS)];
unsigned long agg_session_valid[BITS_TO_LONGS(IEEE80211_NUM_TIDS)];
unsigned long unexpected_agg[BITS_TO_LONGS(IEEE80211_NUM_TIDS)];
struct work_struct work;
struct tid_ampdu_tx __rcu * tid_tx[IEEE80211_NUM_TIDS];
struct tid_ampdu_tx * tid_start_tx[IEEE80211_NUM_TIDS];
unsigned long last_addba_req_time[IEEE80211_NUM_TIDS];
u8 addba_req_num[IEEE80211_NUM_TIDS];
u8 dialog_token_allocator;
};
Members
TID aggregation information (Tx).
Definition
struct tid_ampdu_tx {
struct rcu_head rcu_head;
struct timer_list session_timer;
struct timer_list addba_resp_timer;
struct sk_buff_head pending;
unsigned long state;
unsigned long last_tx;
u16 timeout;
u8 dialog_token;
u8 stop_initiator;
bool tx_stop;
u8 buf_size;
u16 failed_bar_ssn;
bool bar_pending;
bool amsdu;
};
Members
Description
This structure’s lifetime is managed by RCU, assignments to the array holding it must hold the aggregation mutex.
The TX path can access it under RCU lock-free if, and only if, the state has the flag HT_AGG_STATE_OPERATIONAL set. Otherwise, the TX path must also acquire the spinlock and re-check the state, see comments in the tx code touching it.
TID aggregation information (Rx).
Definition
struct tid_ampdu_rx {
struct rcu_head rcu_head;
spinlock_t reorder_lock;
u64 reorder_buf_filtered;
struct sk_buff_head * reorder_buf;
unsigned long * reorder_time;
struct timer_list session_timer;
struct timer_list reorder_timer;
unsigned long last_rx;
u16 head_seq_num;
u16 stored_mpdu_num;
u16 ssn;
u16 buf_size;
u16 timeout;
u8 auto_seq:1;
u8 removed:1;
u8 started:1;
};
Members
Description
This structure’s lifetime is managed by RCU, assignments to the array holding it must hold the aggregation mutex.
The reorder_lock is used to protect the members of this struct, except for timeout, buf_size and dialog_token, which are constant across the lifetime of the struct (the dialog token being used only for debugging).