AP SUPPORT FOR POWERSAVING CLIENTS(9)

📦 version 7.3.1, in nixpkgs unstable

AP support for powersaving clients(9) 💅✨

okay bestie, welcome to the Kernel API Manual entry for AP support for powersaving clients — the (9) one, and this is part 1. 🫶

So, 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. Not a thing rn, periodt. 💀

vibe check — the one assumption: mac80211 makes exactly one assumption, bestie: 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, no cap. fr fr.

First thing to keep in mind, and it's lowkey huge: 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, the driver is main character energy; 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.

race condition alert 🚨 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
  • 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 as 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 implements 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. 🎀

SEE ALSO 🌸

okay bestie, this is the part where they hand you the entire guest list 😭 literally every cross-reference in the mac80211 universe is down here, and we are not skipping a single one. consider this your group chat roster. iykyk 💅

where everything lives

  • ./include/net/mac80211.h — the kernel file that started it all, home of every declaration below 🎀
  • Introduction(9)
  • Calling mac80211 from interrupts(9)
  • Warning(9)
  • Frame format(9)
  • mac80211 workqueue(9)
  • mac80211 software tx queueing(9)
  • HW timestamping(9)

queues, channels & contexts

  • enum ieee80211_max_queues(9)
  • enum ieee80211_ac_numbers(9)
  • struct ieee80211_tx_queue_params(9)
  • enum ieee80211_chanctx_change(9)
  • struct ieee80211_chan_req(9)
  • struct ieee80211_chanctx_conf(9)
  • enum ieee80211_chanctx_switch_mode(9)
  • struct ieee80211_vif_chanctx_switch(9)
  • enum ieee80211_bss_change(9)

events, all the events 🦋

  • enum ieee80211_event_type(9)
  • enum ieee80211_rssi_event_data(9)
  • struct ieee80211_rssi_event(9)
  • enum ieee80211_mlme_event_data(9)
  • enum ieee80211_mlme_event_status(9)
  • struct ieee80211_mlme_event(9)
  • struct ieee80211_ba_event(9)
  • struct ieee80211_event(9)

BSS conf era ✨

  • struct ieee80211_mu_group_data(9)
  • struct ieee80211_ftm_responder_params(9)
  • struct ieee80211_fils_discovery(9)
  • struct ieee80211_parsed_tpe(9)
  • struct ieee80211_bss_npca_params(9)
  • struct ieee80211_bss_conf(9)
  • struct ieee80211_nan_channel(9)
  • struct ieee80211_nan_peer_map(9)
  • struct ieee80211_nan_peer_sched(9)

tx info & status vibes

  • enum mac80211_tx_info_flags(9)
  • enum mac80211_tx_control_flags(9)
  • enum mac80211_tx_status_flags(9)
  • enum mac80211_rate_control_flags(9)
  • struct ieee80211_tx_rate(9)
  • struct ieee80211_tx_info(9)
  • struct ieee80211_tx_status(9)
  • struct ieee80211_scan_ies(9)
  • ieee80211_tx_info_clear_status(9)

rx side, no cap

  • enum mac80211_rx_flags(9)
  • enum mac80211_rx_encoding_flags(9)
  • struct ieee80211_rx_status(9)

conf & smps 🧚

  • enum ieee80211_conf_flags(9)
  • enum ieee80211_conf_changed(9)
  • enum ieee80211_smps_mode(9)
  • struct ieee80211_conf(9)
  • struct ieee80211_channel_switch(9)

the VIF cinematic universe 👑

keys & stations 🔑

  • enum ieee80211_key_flags(9)
  • struct ieee80211_key_conf(9)
  • struct ieee80211_key_seq(9)
  • enum set_key_cmd(9)
  • enum ieee80211_sta_state(9)
  • enum ieee80211_sta_rx_bandwidth(9)
  • struct ieee80211_sta_rates(9)
  • struct ieee80211_sta_txpwr(9)
  • struct ieee80211_sta_aggregates(9)
  • struct ieee80211_link_sta(9)
  • struct ieee80211_sta(9)
  • enum sta_notify_cmd(9)
  • struct ieee80211_tx_control(9)
  • struct ieee80211_txq(9)

hardware & friends 💻

the "support" explainers (yes, your page's siblings) 🫶

  • Hardware crypto acceleration(9)
  • Powersave support(9)
  • Beacon filter support(9)
  • Spatial multiplexing power save(9)
  • Frame filtering(9)
  • HW queue control(9)

ops & registration 🎀

  • enum ieee80211_filter_flags(9)
  • enum ieee80211_ampdu_mlme_action(9)
  • struct ieee80211_ampdu_params(9)
  • enum ieee80211_frame_release_type(9)
  • enum ieee80211_rate_control_changed(9)
  • enum ieee80211_roc_type(9)
  • enum ieee80211_reconfig_type(9)
  • struct ieee80211_prep_tx_info(9)
  • struct ieee80211_ops(9)
  • ieee80211_alloc_hw_nm(9)
  • ieee80211_alloc_hw(9)
  • ieee80211_register_hw(9)

LED trigger slay 🌈

receive path besties

powersave & buffering (the actual theme of the page 💖)

tx rates & tx status 🔥

beacon stuff ⭐

frame getters & duration math 🧚

tkip era 💀

key seq & GTK rekey 🔑

queue control 🎀

scan reporting 🌸

iteration nation 🦋

workqueue helpers

block-ack (tx) sessions ✨

finding stations & airtime 💅

iterating keys & chanctxs

things going wrong (loss, disconnect, radar) 😭

rx block-ack offload 💀

rate control 🎀

capability lookups & helpers 🧚

P2P NOA & TDLS 🦋

txq scheduling, main character energy 👑

NAN functions 🌈

airtime, templates & the finale ⭐

bestie that was a lot of names and every single one of them made it in, no cap 💀🫶

and that's a wrap on part 2!! this page comes to you from the kernel source path ./include/net, dated October 2026 — genuinely iconic of it. go read some of those (9) pages, i'll be right here cheering you on 🎀✨💖

📦 where this page comes from