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!

sta 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 assocation response from the AP. For IBSS this occurs when we receive a probe response or a beacon from target IBSS network. For WDS we add the sta for the peer imediately upon device open. When using AP mode we add stations for each respective station upon request from userspace through nl80211.

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.