This kerneldoc is updated daily based on the wireless-2.6 everything branch.
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 either destroy it using sta_info_destroy (which is pretty useless) or insert it into the hash table using sta_info_insert which demotes the reference from ownership to a regular RCU-protected reference; if the function is called without protection by an RCU critical section the reference is instantly invalidated. 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!
Because there are debugfs entries for each station, and adding those must be able to sleep, it is also possible to "pin" a station entry, that means it can be removed from the hash table but not be freed. See the comment in __sta_info_unlink for more information, this is an internal capability only.
In order to remove a STA info structure, the caller needs to first unlink it (sta_info_unlink) from the list and hash tables and then destroy it; sta_info_destroy will wait for an RCU grace period to elapse before actually freeing it. Due to the pinning and the possibility of multiple callers trying to remove the same STA info at the same time, sta_info_unlink can clear the STA info pointer it is passed to indicate that the STA info is owned by somebody else now.
If sta_info_unlink did not clear the pointer then the caller owns the STA info structure now and is responsible of destroying it with a call to sta_info_destroy.
In all other cases, 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_info_free - internal STA free helper
void __sta_info_free (struct ieee80211_local * local, struct sta_info * sta)Arguments
- local
- pointer to the global information
- sta
- STA info to free
Description
This function must undo everything done by sta_info_alloc that may happen before sta_info_insert.
sta_info_flush - flush matching STA entries from the STA table
int sta_info_flush (struct ieee80211_local * local, struct ieee80211_sub_if_data * sdata)Arguments
- local
- local interface data
- sdata
- matching rule for the net device (sta->dev) or NULL to match all STAs
Description
Returns the number of removed STA entries.
sta_info_flush_delayed - flush matching STA entries from the STA table
void sta_info_flush_delayed (struct ieee80211_sub_if_data * sdata)Arguments
- sdata
- the interface
Description
This function unlinks all stations for a given interface and queues them for freeing. Note that the workqueue function scheduled here has to run before any new keys can be added to the system to avoid set_key callback ordering issues.