iwi(4): Hook it into the build again and enable it everywhere else.
[dragonfly.git] / share / man / man9 / ieee80211_node.9
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 netproto/802_11/ieee80211_var.h
37 .\"
38 .Ft struct ieee80211_node *
39 .Fo ieee80211_find_rxnode
40 .Fa "struct ieee80211com *"
41 .Fa "const struct ieee80211_frame_min *"
42 .Fc
43 .\"
44 .Ft struct ieee80211_node *
45 .Fo ieee80211_find_rxnode_withkey
46 .Fa "struct ieee80211com *"
47 .Fa "const struct ieee80211_frame_min *"
48 .Fa "ieee80211_keyix"
49 .Fc
50 .\"
51 .Ft struct ieee80211_node *
52 .Fn ieee80211_ref_node "struct ieee80211_node *"
53 .\"
54 .Ft void
55 .Fn ieee80211_unref_node "struct ieee80211_node *"
56 .\"
57 .Ft void
58 .Fn ieee80211_free_node "struct ieee80211_node *"
59 .\"
60 .Ft void
61 .Fo ieee80211_iterate_nodes
62 .Fa "struct ieee80211_node_table *"
63 .Fa "ieee80211_iter_func *f"
64 .Fa "void *arg"
65 .Fc
66 .\"
67 .Ft void
68 .Fo ieee80211_dump_nodes
69 .Fa "struct ieee80211_node_table *"
70 .Fc
71 .\"
72 .Ft void
73 .Fo ieee80211_dump_node
74 .Fa "struct ieee80211_node *"
75 .Fc
76 .Sh DESCRIPTION
77 The
78 .Nm net80211
79 layer that supports 802.11 device drivers maintains a database of
80 peer stations called the
81 .Dq node table
82 in the
83 .Vt ic_sta
84 entry of the
85 .Vt ieee80211com
86 structure.
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
93 entry has a
94 .Vt ni_vap
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
98 of a WDS vap).
99 .Pp
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 insure the entry is not reclaimed while the frame is queued or otherwise
105 held by a driver.
106 Routines that lookup a table entry return a
107 .Dq held reference
108 (i.e. a pointer to a table entry with the reference count incremented).
109 The
110 .Fn ieee80211_ref_node
111 and
112 .Fn ieee80211_unref_node
113 calls explicitly increment/decrement the reference count of a node,
114 but are rarely used.
115 Instead most callers use
116 .Fn ieee80211_free_node
117 to release a reference and, if the count goes to zero, reclaim the
118 table entry.
119 .Pp
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
123 .Vt m_pkthdr.rcvif
124 field.
125 This reference must be reclaimed by the driver when transmit processing
126 is done.
127 For each frame received the driver must lookup the table entry to
128 use in dispatching the frame
129 .Dq up the stack .
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
133 .Vt iv_bss
134 node when handling state machine changes as important information
135 is maintained in the data structure.
136 .Pp
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.
142 Note that
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.
147 .Pp
148 Two routines are provided to print the contents of nodes to the console
149 for debugging:
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
155 .Xr ddb 4
156 with the
157 .Dq show node
158 directive and the station node table can be displayed with
159 .Dq show statab .
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
164 .Vt ic_node_alloc
165 method used to allocate a node table entry.
166 The driver method must allocate a structure that is an extension
167 of the
168 .Vt ieee80211_node
169 structure.
170 For example the
171 .Xr iwi 4
172 driver defines a private node structure as:
173 .Bd -literal -offset indent
174 struct iwi_node {
175         struct ieee80211_node   in_node;
176         int                     in_station;
177 };
178 .Ed
179 .Pp
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])
185 {
186         struct iwi_node *in;
187
188         in = malloc(sizeof (struct iwi_node), M_80211_NODE,
189                 M_NOWAIT | M_ZERO);
190         if (in == NULL)
191                 return NULL;
192         in->in_station = -1;
193         return &in->in_node;
194 }
195 .Ed
196 .Pp
197 Note that when reclaiming a node allocated by the driver the
198 .Dq parent method
199 must be called to ensure
200 .Nm net80211
201 state is reclaimed; for example:
202 .Bd -literal -offset indent
203 static void
204 iwi_node_free(struct ieee80211_node *ni)
205 {
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;
209
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 */
213 }
214 .Ed
215 .Pp
216 Beware that care must be taken to avoid holding references that
217 might cause nodes from being reclaimed.
218 .Nm net80211
219 will reclaim a node when the last reference is reclaimed in
220 its data structures.
221 However if a driver holds additional references then
222 .Nm net80211
223 will not recognize this and table entries will not be reclaimed.
224 Such references should not be needed if the driver overrides the
225 .Vt ic_node_cleanup
226 and/or
227 .Vt ic_node_free
228 methods.
229 .Sh KEY TABLE SUPPORT
230 Node table lookups are typically done using a hash of the stations'
231 mac address.
232 When receiving frames this is sufficient to find the node table entry
233 for the transmitter.
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
237 .Dq keytab .
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.
248 .Sh SEE ALSO
249 .Xr ddb 4 ,
250 .Xr ieee80211 9 ,
251 .Xr ieee80211_proto 9