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.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.7 2010/03/29 17:39:38 trasz Exp $ 28.\" 29.Dd April 28, 2010 30.Dt IEEE80211_NODE 9 31.Os 32.Sh NAME 33.Nm ieee80211_node 34.Nd software 802.11 stack node management functions 35.Sh SYNOPSIS 36.In net/if.h 37.In net/if_media.h 38.In netproto/802_11/ieee80211_var.h 39.\" 40.Ft struct ieee80211_node * 41.Fo ieee80211_find_rxnode 42.Fa "struct ieee80211com *" 43.Fa "const struct ieee80211_frame_min *" 44.Fc 45.\" 46.Ft struct ieee80211_node * 47.Fo ieee80211_find_rxnode_withkey 48.Fa "struct ieee80211com *" 49.Fa "const struct ieee80211_frame_min *" 50.Fa "ieee80211_keyix" 51.Fc 52.\" 53.Ft struct ieee80211_node * 54.Fn ieee80211_ref_node "struct ieee80211_node *" 55.\" 56.Ft void 57.Fn ieee80211_unref_node "struct ieee80211_node *" 58.\" 59.Ft void 60.Fn ieee80211_free_node "struct ieee80211_node *" 61.\" 62.Ft void 63.Fo ieee80211_iterate_nodes 64.Fa "struct ieee80211_node_table *" 65.Fa "ieee80211_iter_func *f" 66.Fa "void *arg" 67.Fc 68.\" 69.Ft void 70.Fo ieee80211_dump_nodes 71.Fa "struct ieee80211_node_table *" 72.Fc 73.\" 74.Ft void 75.Fo ieee80211_dump_node 76.Fa "struct ieee80211_node *" 77.Fc 78.Sh DESCRIPTION 79The 80.Nm net80211 81layer that supports 802.11 device drivers maintains a database of 82peer stations called the 83.Dq node table 84in the 85.Vt ic_sta 86entry of the 87.Vt ieee80211com 88structure. 89Station mode vaps create an entry for the access point 90the station is associated to. 91AP mode vaps create entries for associated stations. 92Adhoc and mesh mode vaps create entries for neighbor stations. 93WDS mode vaps create an entry for the peer station. 94Stations for all vaps reside in the same table; each node 95entry has a 96.Vt ni_vap 97field that identifies the vap that created it. 98In some instances an entry is used by multiple vaps (e.g. for 99dynamic WDS a station associated to an ap vap may also be the peer 100of a WDS vap). 101.Pp 102Node table entries are reference counted. 103That is, there is a count of all long term references that determines 104when an entry may be reclaimed. 105References are held by every in-flight frame sent to a station to 106insure the entry is not reclaimed while the frame is queued or otherwise 107held by a driver. 108Routines that lookup a table entry return a 109.Dq held reference 110(i.e. a pointer to a table entry with the reference count incremented). 111The 112.Fn ieee80211_ref_node 113and 114.Fn ieee80211_unref_node 115calls explicitly increment/decrement the reference count of a node, 116but are rarely used. 117Instead most callers use 118.Fn ieee80211_free_node 119to release a reference and, if the count goes to zero, reclaim the 120table entry. 121.Pp 122The station table and its entries are exposed to drivers in several ways. 123Each frame transmitted to a station includes a reference to the 124associated node in the 125.Vt m_pkthdr.rcvif 126field. 127This reference must be reclaimed by the driver when transmit processing 128is done. 129For each frame received the driver must lookup the table entry to 130use in dispatching the frame 131.Dq up the stack . 132This lookup implicitly obtains a reference to the table entry and 133the driver must reclaim the reference when frame processing is completed. 134Otherwise drivers frequently inspect the contents of the 135.Vt iv_bss 136node when handling state machine changes as important information 137is maintained in the data structure. 138.Pp 139The node table is opaque to drivers. 140Entries may be looked up using one of the pre-defined API's or the 141.Fn ieee80211_iterate_nodes 142call may be used to iterate through all entries to do per-node 143processing or implement some non-standard search mechanism. 144Note that 145.Fn ieee80211_iterate_nodes 146is single-threaded per-device 147and the effort processing involved is fairly 148substantial so it should be used carefully. 149.Pp 150Two routines are provided to print the contents of nodes to the console 151for debugging: 152.Fn ieee80211_dump_node 153displays the contents of a single node while 154.Fn ieee80211_dump_nodes 155displays the contents of the specified node table. 156Nodes may also be displayed using 157.Xr ddb 4 158with the 159.Dq show node 160directive and the station node table can be displayed with 161.Dq show statab . 162.Sh DRIVER PRIVATE STATE 163Node data structures may be extended by the driver to include 164driver-private state. 165This is done by overriding the 166.Vt ic_node_alloc 167method used to allocate a node table entry. 168The driver method must allocate a structure that is an extension 169of the 170.Vt ieee80211_node 171structure. 172For example the 173.Xr iwi 4 174driver defines a private node structure as: 175.Bd -literal -offset indent 176struct iwi_node { 177 struct ieee80211_node in_node; 178 int in_station; 179}; 180.Ed 181.Pp 182and then provides a private allocation routine that does this: 183.Bd -literal -offset indent 184static struct ieee80211_node * 185iwi_node_alloc(struct ieee80211vap *vap, 186 const uint8_t mac[IEEE80211_ADDR_LEN]) 187{ 188 struct iwi_node *in; 189 190 in = malloc(sizeof (struct iwi_node), M_80211_NODE, 191 M_NOWAIT | M_ZERO); 192 if (in == NULL) 193 return NULL; 194 in->in_station = -1; 195 return &in->in_node; 196} 197.Ed 198.Pp 199Note that when reclaiming a node allocated by the driver the 200.Dq parent method 201must be called to ensure 202.Nm net80211 203state is reclaimed; for example: 204.Bd -literal -offset indent 205static void 206iwi_node_free(struct ieee80211_node *ni) 207{ 208 struct ieee80211com *ic = ni->ni_ic; 209 struct iwi_softc *sc = ic->ic_ifp->if_softc; 210 struct iwi_node *in = (struct iwi_node *)ni; 211 212 if (in->in_station != -1) 213 free_unr(sc->sc_unr, in->in_station); 214 sc->sc_node_free(ni); /* invoke net80211 free handler */ 215} 216.Ed 217.Pp 218Beware that care must be taken to avoid holding references that 219might cause nodes from being reclaimed. 220.Nm net80211 221will reclaim a node when the last reference is reclaimed in 222its data structures. 223However if a driver holds additional references then 224.Nm net80211 225will not recognize this and table entries will not be reclaimed. 226Such references should not be needed if the driver overrides the 227.Vt ic_node_cleanup 228and/or 229.Vt ic_node_free 230methods. 231.Sh KEY TABLE SUPPORT 232Node table lookups are typically done using a hash of the stations' 233mac address. 234When receiving frames this is sufficient to find the node table entry 235for the transmitter. 236But some devices also identify the sending station in the device 237state received with each frame and this data can be used to optimize 238lookups on receive using a companion table called the 239.Dq keytab . 240This table records a separate node table reference that can be fetched 241without any locking using the table index. 242This logic is handled with the 243.Fn ieee80211_find_rxnode_withkey 244call: if a keytab entry is found using the specified index then it is 245returned directly; otherwise a normal lookup is done and the keytab 246entry is written using the specified index. 247If the specified index is 248.Dv IEEE80211_KEYIX_NONE 249then a normal lookup is done without a table update. 250.Sh SEE ALSO 251.Xr ddb 4 , 252.Xr ieee80211 9 , 253.Xr ieee80211_proto 9 254