2 .\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
3 .\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
34 .Nd software 802.11 stack node management functions
36 .In net80211/ieee80211_var.h
38 .Ft struct ieee80211_node *
39 .Fo ieee80211_find_rxnode
40 .Fa "struct ieee80211com *"
41 .Fa "const struct ieee80211_frame_min *"
44 .Ft struct ieee80211_node *
45 .Fo ieee80211_find_rxnode_withkey
46 .Fa "struct ieee80211com *"
47 .Fa "const struct ieee80211_frame_min *"
51 .Ft struct ieee80211_node *
52 .Fn ieee80211_ref_node "struct ieee80211_node *"
55 .Fn ieee80211_unref_node "struct ieee80211_node *"
58 .Fn ieee80211_free_node "struct ieee80211_node *"
61 .Fo ieee80211_iterate_nodes
62 .Fa "struct ieee80211_node_table *"
63 .Fa "ieee80211_iter_func *f"
68 .Fo ieee80211_dump_nodes
69 .Fa "struct ieee80211_node_table *"
73 .Fo ieee80211_dump_node
74 .Fa "struct ieee80211_node *"
79 layer that supports 802.11 device drivers maintains a database of
80 peer stations called the
87 Station mode vaps create an entry for the access point
88 the station is associated to.
89 AP mode vaps create entries for associated stations.
90 Adhoc and mesh mode vaps create entries for neighbor stations.
91 WDS mode vaps create an entry for the peer station.
92 Stations for all vaps reside in the same table; each node
95 field that identifies the vap that created it.
96 In some instances an entry is used by multiple vaps (e.g. for
97 dynamic WDS a station associated to an ap vap may also be the peer
100 Node table entries are reference counted.
101 That is, there is a count of all long term references that determines
102 when an entry may be reclaimed.
103 References are held by every in-flight frame sent to a station to
104 ensure the entry is not reclaimed while the frame is queued or otherwise
106 Routines that lookup a table entry return a
108 (i.e. a pointer to a table entry with the reference count incremented).
110 .Fn ieee80211_ref_node
112 .Fn ieee80211_unref_node
113 calls explicitly increment/decrement the reference count of a node,
115 Instead most callers use
116 .Fn ieee80211_free_node
117 to release a reference and, if the count goes to zero, reclaim the
120 The station table and its entries are exposed to drivers in several ways.
121 Each frame transmitted to a station includes a reference to the
122 associated node in the
125 This reference must be reclaimed by the driver when transmit processing
127 For each frame received the driver must lookup the table entry to
128 use in dispatching the frame
130 This lookup implicitly obtains a reference to the table entry and
131 the driver must reclaim the reference when frame processing is completed.
132 Otherwise drivers frequently inspect the contents of the
134 node when handling state machine changes as important information
135 is maintained in the data structure.
137 The node table is opaque to drivers.
138 Entries may be looked up using one of the pre-defined API's or the
139 .Fn ieee80211_iterate_nodes
140 call may be used to iterate through all entries to do per-node
141 processing or implement some non-standard search mechanism.
143 .Fn ieee80211_iterate_nodes
144 is single-threaded per-device
145 and the effort processing involved is fairly
146 substantial so it should be used carefully.
148 Two routines are provided to print the contents of nodes to the console
150 .Fn ieee80211_dump_node
151 displays the contents of a single node while
152 .Fn ieee80211_dump_nodes
153 displays the contents of the specified node table.
154 Nodes may also be displayed using
158 directive and the station node table can be displayed with
160 .Sh DRIVER PRIVATE STATE
161 Node data structures may be extended by the driver to include
162 driver-private state.
163 This is done by overriding the
165 method used to allocate a node table entry.
166 The driver method must allocate a structure that is an extension
172 driver defines a private node structure as:
173 .Bd -literal -offset indent
175 struct ieee80211_node in_node;
180 and then provides a private allocation routine that does this:
181 .Bd -literal -offset indent
182 static struct ieee80211_node *
183 iwi_node_alloc(struct ieee80211vap *vap,
184 const uint8_t mac[IEEE80211_ADDR_LEN])
188 in = malloc(sizeof(struct iwi_node), M_80211_NODE,
197 Note that when reclaiming a node allocated by the driver the
199 must be called to ensure
201 state is reclaimed; for example:
202 .Bd -literal -offset indent
204 iwi_node_free(struct ieee80211_node *ni)
206 struct ieee80211com *ic = ni->ni_ic;
207 struct iwi_softc *sc = ic->ic_ifp->if_softc;
208 struct iwi_node *in = (struct iwi_node *)ni;
210 if (in->in_station != -1)
211 free_unr(sc->sc_unr, in->in_station);
212 sc->sc_node_free(ni); /* invoke net80211 free handler */
216 Beware that care must be taken to avoid holding references that
217 might cause nodes from being reclaimed.
219 will reclaim a node when the last reference is reclaimed in
221 However if a driver holds additional references then
223 will not recognize this and table entries will not be reclaimed.
224 Such references should not be needed if the driver overrides the
229 .Sh KEY TABLE SUPPORT
230 Node table lookups are typically done using a hash of the stations'
232 When receiving frames this is sufficient to find the node table entry
234 But some devices also identify the sending station in the device
235 state received with each frame and this data can be used to optimize
236 lookups on receive using a companion table called the
238 This table records a separate node table reference that can be fetched
239 without any locking using the table index.
240 This logic is handled with the
241 .Fn ieee80211_find_rxnode_withkey
242 call: if a keytab entry is found using the specified index then it is
243 returned directly; otherwise a normal lookup is done and the keytab
244 entry is written using the specified index.
245 If the specified index is
246 .Dv IEEE80211_KEYIX_NONE
247 then a normal lookup is done without a table update.
251 .Xr ieee80211_proto 9