mac80211 subsystem (advanced)¶
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.
LED support¶
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.
Error
kernel-doc missing
Powersave support¶
Error
kernel-doc missing
Access point mode support¶
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.
Supporting multiple virtual interfaces¶
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.
Error
kernel-doc missing
Aggregation¶
TX A-MPDU aggregation¶
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.
RX A-MPDU aggregation¶
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.
Error
kernel-doc missing
Spatial Multiplexing Powersave (SMPS)¶
Error
kernel-doc missing
Error
kernel-doc missing
TBD
This part of the book describes the rate control algorithm interface and how it relates to mac80211 and drivers.
Rate Control API¶
TBD
Error
kernel-doc missing
TBD
This part of the book describes mac80211 internals.
Key handling¶
Key handling basics¶
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.
MORE TBD¶
TBD
Receive processing¶
TBD
Transmit processing¶
TBD
Station info handling¶
Programming information¶
-
enum
ieee80211_sta_info_flags
¶ Stations flags
Constants
WLAN_STA_AUTH
Station is authenticated.
WLAN_STA_ASSOC
Station is associated.
WLAN_STA_PS_STA
Station is in power-save mode
WLAN_STA_AUTHORIZED
Station is authorized to send/receive traffic. This bit is always checked so needs to be enabled for all stations when virtual port control is not in use.
WLAN_STA_SHORT_PREAMBLE
Station is capable of receiving short-preamble frames.
WLAN_STA_WDS
Station is one of our WDS peers.
WLAN_STA_CLEAR_PS_FILT
Clear PS filter in hardware (using the IEEE80211_TX_CTL_CLEAR_PS_FILT control flag) when the next frame to this station is transmitted.
WLAN_STA_MFP
Management frame protection is used with this STA.
WLAN_STA_BLOCK_BA
Used to deny ADDBA requests (both TX and RX) during suspend/resume and station removal.
WLAN_STA_PS_DRIVER
driver requires keeping this station in power-save mode logically to flush frames that might still be in the queues
WLAN_STA_PSPOLL
Station sent PS-poll while driver was keeping station in power-save mode, reply when the driver unblocks.
WLAN_STA_TDLS_PEER
Station is a TDLS peer.
WLAN_STA_TDLS_PEER_AUTH
This TDLS peer is authorized to send direct packets. This means the link is enabled.
WLAN_STA_TDLS_INITIATOR
We are the initiator of the TDLS link with this station.
WLAN_STA_TDLS_CHAN_SWITCH
This TDLS peer supports TDLS channel-switching
WLAN_STA_TDLS_OFF_CHANNEL
The local STA is currently off-channel with this TDLS peer
WLAN_STA_TDLS_WIDER_BW
This TDLS peer supports working on a wider bw on the BSS base channel.
WLAN_STA_UAPSD
Station requested unscheduled SP while driver was keeping station in power-save mode, reply when the driver unblocks the station.
WLAN_STA_SP
Station is in a service period, so don’t try to reply to other uAPSD trigger frames or PS-Poll.
WLAN_STA_4ADDR_EVENT
4-addr event was already sent for this frame.
WLAN_STA_INSERTED
This station is inserted into the hash table.
WLAN_STA_RATE_CONTROL
rate control was initialized for this station.
WLAN_STA_TOFFSET_KNOWN
toffset calculated for this station is valid.
WLAN_STA_MPSP_OWNER
local STA is owner of a mesh Peer Service Period.
WLAN_STA_MPSP_RECIPIENT
local STA is recipient of a MPSP.
WLAN_STA_PS_DELIVER
station woke up, but we’re still blocking TX until pending frames are delivered
WLAN_STA_USES_ENCRYPTION
This station was configured for encryption, so drop all packets without a key later.
WLAN_STA_DECAP_OFFLOAD
This station uses rx decap offload
NUM_WLAN_STA_FLAGS
number of defined flags
Description
These flags are used with struct sta_info
’s flags member, but
only indirectly with set_sta_flag() and friends.
-
struct
sta_info
¶ STA information
Definition
struct sta_info {
struct list_head list, 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 + NUM_DEFAULT_BEACON_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;
u64 assoc_at;
long last_connected;
struct ieee80211_sta_rx_stats rx_stats;
struct {
struct ewma_signal signal;
struct ewma_signal chain_signal[IEEE80211_MAX_CHAINS];
} rx_stats_avg;
__le16 last_seq_ctrl[IEEE80211_NUM_TIDS + 1];
struct {
unsigned long filtered;
unsigned long retry_failed, retry_count;
unsigned int lost_packets;
unsigned long last_pkt_time;
u64 msdu_retries[IEEE80211_NUM_TIDS + 1];
u64 msdu_failed[IEEE80211_NUM_TIDS + 1];
unsigned long last_ack;
s8 last_ack_signal;
bool ack_signal_filled;
struct ewma_avg_signal avg_ack_signal;
} status_stats;
struct {
u64 packets[IEEE80211_NUM_ACS];
u64 bytes[IEEE80211_NUM_ACS];
struct ieee80211_tx_rate last_rate;
struct rate_info last_rate_info;
u64 msdu[IEEE80211_NUM_TIDS + 1];
} tx_stats;
u16 tid_seq[IEEE80211_QOS_CTL_TID_MASK + 1];
struct airtime_info airtime[IEEE80211_NUM_ACS];
struct sta_ampdu_mlme ampdu_mlme;
#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;
struct codel_params cparams;
u8 reserved_tid;
struct cfg80211_chan_def tdls_chandef;
struct ieee80211_fragment_cache frags;
struct ieee80211_sta sta;
};
Members
list
global linked list entry
free_list
list entry for keeping track of stations to free
rcu_head
RCU head used for freeing this station struct
hash_node
hash node for rhashtable
addr
station’s MAC address - duplicated from public part to let the hash table work with just a single cacheline
local
pointer to the global information
sdata
virtual interface this station belongs to
gtk
group keys negotiated with this station, if any
ptk
peer keys negotiated with this station, if any
ptk_idx
last installed peer key index
rate_ctrl
rate control algorithm reference
rate_ctrl_priv
rate control private per-STA pointer
rate_ctrl_lock
spinlock used to protect rate control data (data inside the algorithm, so serializes calls there)
lock
used for locking all fields that require locking, see comments in the header file.
fast_tx
TX fastpath information
fast_rx
RX fastpath information
pcpu_rx_stats
per-CPU RX statistics, assigned only if the driver needs this (by advertising the USES_RSS hw flag)
mesh
mesh STA information
drv_deliver_wk
used for delivering frames after driver PS unblocking
listen_interval
listen interval of this station, when we’re acting as AP
dead
set to true when sta is unlinked
removed
set to true when sta is being removed from sta_list
uploaded
set to true when sta is uploaded to the driver
sta_state
duplicates information about station state (for debug)
_flags
STA flags, see
enum ieee80211_sta_info_flags
, do not use directlyps_lock
used for powersave (when mac80211 is the AP) related locking
ps_tx_buf
buffers (per AC) of frames to transmit to this station when it leaves power saving state or polls
tx_filtered
buffers (per AC) of frames we already tried to transmit but were filtered by hardware due to STA having entered power saving state, these are also delivered to the station when it leaves powersave or polls for frames
driver_buffered_tids
bitmap of TIDs the driver has data buffered on
txq_buffered_tids
bitmap of TIDs that mac80211 has txq data buffered on
assoc_at
clock boottime (in ns) of last association
last_connected
time (in seconds) when a station got connected
rx_stats
RX statistics
rx_stats_avg
averaged RX statistics
rx_stats_avg.signal
averaged signal
rx_stats_avg.chain_signal
averaged per-chain signal
last_seq_ctrl
last received seq/frag number from this STA (per TID plus one for non-QoS frames)
status_stats
TX status statistics
status_stats.filtered
# of filtered frames
status_stats.retry_failed
# of frames that failed after retry
status_stats.retry_count
# of retries attempted
status_stats.lost_packets
# of lost packets
status_stats.last_pkt_time
timestamp of last ACKed packet
status_stats.msdu_retries
# of MSDU retries
status_stats.msdu_failed
# of failed MSDUs
status_stats.last_ack
last ack timestamp (jiffies)
status_stats.last_ack_signal
last ACK signal
status_stats.ack_signal_filled
last ACK signal validity
status_stats.avg_ack_signal
average ACK signal
tx_stats
TX statistics
tx_stats.packets
# of packets transmitted
tx_stats.bytes
# of bytes in all packets transmitted
tx_stats.last_rate
last TX rate
tx_stats.msdu
# of transmitted MSDUs per TID
tid_seq
per-TID sequence numbers for sending to this STA
airtime
per-AC struct airtime_info describing airtime statistics for this station
ampdu_mlme
A-MPDU state machine state
debugfs_dir
debug filesystem directory dentry
cur_max_bandwidth
maximum bandwidth to use for TX to the station, taken from HT/VHT capabilities or VHT operating mode notification
known_smps_mode
the smps_mode the client thinks we are in. Relevant for AP only.
cipher_scheme
optional cipher scheme for this station
cparams
CoDel parameters for this station.
reserved_tid
reserved TID (if any, otherwise IEEE80211_TID_UNRESERVED)
tdls_chandef
a TDLS peer can have a wider chandef that is compatible to the BSS one.
frags
fragment cache
sta
station information we share with the driver
Description
This structure collects information about a station that mac80211 is communicating with.
STA information lifetime rules¶
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.
Aggregation Functions¶
-
struct
tid_ampdu_tx
¶ 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;
struct sta_info *sta;
unsigned long state;
unsigned long last_tx;
u16 timeout;
u8 dialog_token;
u8 stop_initiator;
bool tx_stop;
u16 buf_size;
u16 ssn;
u16 failed_bar_ssn;
bool bar_pending;
bool amsdu;
u8 tid;
};
Members
rcu_head
rcu head for freeing structure
session_timer
check if we keep Tx-ing on the TID (by timeout value)
addba_resp_timer
timer for peer’s response to addba request
pending
pending frames queue – use sta’s spinlock to protect
sta
station we are attached to
state
session state (see above)
last_tx
jiffies of last tx activity
timeout
session timeout value to be filled in ADDBA requests
dialog_token
dialog token for aggregation session
stop_initiator
initiator of a session stop
tx_stop
TX DelBA frame when stopping
buf_size
reorder buffer size at receiver
failed_bar_ssn
ssn of the last failed BAR tx attempt
bar_pending
BAR needs to be re-sent
amsdu
support A-MSDU withing A-MDPU
tid
TID number
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.
-
struct
tid_ampdu_rx
¶ 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 sta_info *sta;
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 tid;
u8 auto_seq:1,removed:1, started:1;
};
Members
rcu_head
RCU head used for freeing this struct
reorder_lock
serializes access to reorder buffer, see below.
reorder_buf_filtered
bitmap indicating where there are filtered frames in the reorder buffer that should be ignored when releasing frames
reorder_buf
buffer to reorder incoming aggregated MPDUs. An MPDU may be an A-MSDU with individually reported subframes.
reorder_time
jiffies when skb was added
sta
station we are attached to
session_timer
check if peer keeps Tx-ing on the TID (by timeout value)
reorder_timer
releases expired frames from the reorder buffer.
last_rx
jiffies of last rx activity
head_seq_num
head sequence number in reordering buffer.
stored_mpdu_num
number of MPDUs in reordering buffer
ssn
Starting Sequence Number expected to be aggregated.
buf_size
buffer size for incoming A-MPDUs
timeout
reset timer value (in TUs).
tid
TID number
auto_seq
used for offloaded BA sessions to automatically pick head_seq_and and ssn.
removed
this session is removed (but might have been found due to RCU)
started
this session has started (head ssn or higher was received)
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).
-
struct
sta_ampdu_mlme
¶ 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 tid_rx_manage_offl[BITS_TO_LONGS(2 * 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
mtx
mutex to protect all TX data (except non-NULL assignments to tid_tx[idx], which are protected by the sta spinlock) tid_start_tx is also protected by sta->lock.
tid_rx
aggregation info for Rx per TID – RCU protected
tid_rx_token
dialog tokens for valid aggregation sessions
tid_rx_timer_expired
bitmap indicating on which TIDs the RX timer expired until the work for it runs
tid_rx_stop_requested
bitmap indicating which BA sessions per TID the driver requested to close until the work for it runs
tid_rx_manage_offl
bitmap indicating which BA sessions were requested to be treated as started/stopped due to offloading
agg_session_valid
bitmap indicating which TID has a rx BA session open on
unexpected_agg
bitmap indicating which TID already sent a delBA due to unexpected aggregation related frames outside a session
work
work struct for starting/stopping aggregation
tid_tx
aggregation info for Tx per TID
tid_start_tx
sessions where start was requested
last_addba_req_time
timestamp of the last addBA request.
addba_req_num
number of times addBA request has been sent.
dialog_token_allocator
dialog token enumerator for each new session;