<?xml version="1.0" encoding="ANSI_X3.4-1968" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968" /><title>STA information lifetime rules</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2" /><link rel="home" href="index.html" title="The mac80211 subsystem for kernel developers" /><link rel="up" href="ch17.html" title="Chapter 17. Station info handling" /><link rel="prev" href="re45.html" title="enum ieee80211_sta_info_flags" /><link rel="next" href="ch18.html" title="Chapter 18. Synchronisation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">STA information lifetime rules</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re45.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Station info handling</th><td width="20%" align="right"> <a accesskey="n" href="ch18.html">Next</a></td></tr></table><hr /></div><div class="sect1" title="STA information lifetime rules"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="id2713582"></a>STA information lifetime rules</h2></div></div></div><p> </p><p> STA info structures (<span class="structname">struct sta_info</span>) 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. </p><p> Upon allocating a STA info structure with <code class="function">sta_info_alloc</code>, the caller owns that structure. It must then either destroy it using <code class="function">sta_info_destroy</code> (which is pretty useless) or insert it into the hash table using <code class="function">sta_info_insert</code> 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. </p><p> When the insertion fails (<code class="function">sta_info_insert</code>) returns non-zero), the structure will have been freed by <code class="function">sta_info_insert</code>! </p><p> 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. </p><p> Because there are debugfs entries for each station, and adding those must be able to sleep, it is also possible to <span class="quote">“<span class="quote">pin</span>”</span> a station entry, that means it can be removed from the hash table but not be freed. See the comment in <code class="function">__sta_info_unlink</code> for more information, this is an internal capability only. </p><p> In order to remove a STA info structure, the caller needs to first unlink it (<code class="function">sta_info_unlink</code>) from the list and hash tables and then destroy it; <code class="function">sta_info_destroy</code> 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, <code class="function">sta_info_unlink</code> can clear the STA info pointer it is passed to indicate that the STA info is owned by somebody else now. </p><p> If <code class="function">sta_info_unlink</code> did not clear the pointer then the caller owns the STA info structure now and is responsible of destroying it with a call to <code class="function">sta_info_destroy</code>. </p><p> 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. </p></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re45.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch17.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch18.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span>enum ieee80211_sta_info_flags</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 18. Synchronisation</td></tr></table></div></body></html>
