1.\" 2.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> 3.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd April 28, 2010 28.Dt IEEE80211_NODE 9 29.Os 30.Sh NAME 31.Nm ieee80211_node 32.Nd software 802.11 stack node management functions 33.Sh SYNOPSIS 34.In net80211/ieee80211_var.h 35.\" 36.Ft struct ieee80211_node * 37.Fo ieee80211_find_rxnode 38.Fa "struct ieee80211com *" 39.Fa "const struct ieee80211_frame_min *" 40.Fc 41.\" 42.Ft struct ieee80211_node * 43.Fo ieee80211_find_rxnode_withkey 44.Fa "struct ieee80211com *" 45.Fa "const struct ieee80211_frame_min *" 46.Fa "ieee80211_keyix" 47.Fc 48.\" 49.Ft struct ieee80211_node * 50.Fn ieee80211_ref_node "struct ieee80211_node *" 51.\" 52.Ft void 53.Fn ieee80211_unref_node "struct ieee80211_node *" 54.\" 55.Ft void 56.Fn ieee80211_free_node "struct ieee80211_node *" 57.\" 58.Ft void 59.Fo ieee80211_iterate_nodes 60.Fa "struct ieee80211_node_table *" 61.Fa "ieee80211_iter_func *f" 62.Fa "void *arg" 63.Fc 64.\" 65.Ft void 66.Fo ieee80211_dump_nodes 67.Fa "struct ieee80211_node_table *" 68.Fc 69.\" 70.Ft void 71.Fo ieee80211_dump_node 72.Fa "struct ieee80211_node *" 73.Fc 74.Sh DESCRIPTION 75The 76.Nm net80211 77layer that supports 802.11 device drivers maintains a database of 78peer stations called the 79.Dq node table 80in the 81.Vt ic_sta 82entry of the 83.Vt ieee80211com 84structure. 85Station mode vaps create an entry for the access point 86the station is associated to. 87AP mode vaps create entries for associated stations. 88Adhoc and mesh mode vaps create entries for neighbor stations. 89WDS mode vaps create an entry for the peer station. 90Stations for all vaps reside in the same table; each node 91entry has a 92.Vt ni_vap 93field that identifies the vap that created it. 94In some instances an entry is used by multiple vaps (e.g. for 95dynamic WDS a station associated to an ap vap may also be the peer 96of a WDS vap). 97.Pp 98Node table entries are reference counted. 99That is, there is a count of all long term references that determines 100when an entry may be reclaimed. 101References are held by every in-flight frame sent to a station to 102ensure the entry is not reclaimed while the frame is queued or otherwise 103held by a driver. 104Routines that lookup a table entry return a 105.Dq held reference 106(i.e. a pointer to a table entry with the reference count incremented). 107The 108.Fn ieee80211_ref_node 109and 110.Fn ieee80211_unref_node 111calls explicitly increment/decrement the reference count of a node, 112but are rarely used. 113Instead most callers use 114.Fn ieee80211_free_node 115to release a reference and, if the count goes to zero, reclaim the 116table entry. 117.Pp 118The station table and its entries are exposed to drivers in several ways. 119Each frame transmitted to a station includes a reference to the 120associated node in the 121.Vt m_pkthdr.rcvif 122field. 123This reference must be reclaimed by the driver when transmit processing 124is done. 125For each frame received the driver must lookup the table entry to 126use in dispatching the frame 127.Dq up the stack . 128This lookup implicitly obtains a reference to the table entry and 129the driver must reclaim the reference when frame processing is completed. 130Otherwise drivers frequently inspect the contents of the 131.Vt iv_bss 132node when handling state machine changes as important information 133is maintained in the data structure. 134.Pp 135The node table is opaque to drivers. 136Entries may be looked up using one of the pre-defined API's or the 137.Fn ieee80211_iterate_nodes 138call may be used to iterate through all entries to do per-node 139processing or implement some non-standard search mechanism. 140Note that 141.Fn ieee80211_iterate_nodes 142is single-threaded per-device 143and the effort processing involved is fairly 144substantial so it should be used carefully. 145.Pp 146Two routines are provided to print the contents of nodes to the console 147for debugging: 148.Fn ieee80211_dump_node 149displays the contents of a single node while 150.Fn ieee80211_dump_nodes 151displays the contents of the specified node table. 152Nodes may also be displayed using 153.Xr ddb 4 154with the 155.Dq show node 156directive and the station node table can be displayed with 157.Dq show statab . 158.Sh DRIVER PRIVATE STATE 159Node data structures may be extended by the driver to include 160driver-private state. 161This is done by overriding the 162.Vt ic_node_alloc 163method used to allocate a node table entry. 164The driver method must allocate a structure that is an extension 165of the 166.Vt ieee80211_node 167structure. 168For example the 169.Xr iwi 4 170driver defines a private node structure as: 171.Bd -literal -offset indent 172struct iwi_node { 173 struct ieee80211_node in_node; 174 int in_station; 175}; 176.Ed 177.Pp 178and then provides a private allocation routine that does this: 179.Bd -literal -offset indent 180static struct ieee80211_node * 181iwi_node_alloc(struct ieee80211vap *vap, 182 const uint8_t mac[IEEE80211_ADDR_LEN]) 183{ 184 struct iwi_node *in; 185 186 in = malloc(sizeof(struct iwi_node), M_80211_NODE, 187 M_NOWAIT | M_ZERO); 188 if (in == NULL) 189 return NULL; 190 in->in_station = -1; 191 return &in->in_node; 192} 193.Ed 194.Pp 195Note that when reclaiming a node allocated by the driver the 196.Dq parent method 197must be called to ensure 198.Nm net80211 199state is reclaimed; for example: 200.Bd -literal -offset indent 201static void 202iwi_node_free(struct ieee80211_node *ni) 203{ 204 struct ieee80211com *ic = ni->ni_ic; 205 struct iwi_softc *sc = ic->ic_ifp->if_softc; 206 struct iwi_node *in = (struct iwi_node *)ni; 207 208 if (in->in_station != -1) 209 free_unr(sc->sc_unr, in->in_station); 210 sc->sc_node_free(ni); /* invoke net80211 free handler */ 211} 212.Ed 213.Pp 214Beware that care must be taken to avoid holding references that 215might cause nodes from being reclaimed. 216.Nm net80211 217will reclaim a node when the last reference is reclaimed in 218its data structures. 219However if a driver holds additional references then 220.Nm net80211 221will not recognize this and table entries will not be reclaimed. 222Such references should not be needed if the driver overrides the 223.Vt ic_node_cleanup 224and/or 225.Vt ic_node_free 226methods. 227.Sh KEY TABLE SUPPORT 228Node table lookups are typically done using a hash of the stations' 229mac address. 230When receiving frames this is sufficient to find the node table entry 231for the transmitter. 232But some devices also identify the sending station in the device 233state received with each frame and this data can be used to optimize 234lookups on receive using a companion table called the 235.Dq keytab . 236This table records a separate node table reference that can be fetched 237without any locking using the table index. 238This logic is handled with the 239.Fn ieee80211_find_rxnode_withkey 240call: if a keytab entry is found using the specified index then it is 241returned directly; otherwise a normal lookup is done and the keytab 242entry is written using the specified index. 243If the specified index is 244.Dv IEEE80211_KEYIX_NONE 245then a normal lookup is done without a table update. 246.Sh SEE ALSO 247.Xr ddb 4 , 248.Xr ieee80211 9 , 249.Xr ieee80211_proto 9 250