Next round of fixing all kinds of spelling mistakes.
[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$
28 .\" $DragonFly: src/share/man/man9/ieee80211_node.9,v 1.5 2007/05/17 08:19:02 swildner Exp $
29 .\" $Id: ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
30 .\"
31 .Dd June 28, 2006
32 .Dt IEEE80211_NODE 9
33 .Os
34 .Sh NAME
35 .\" .Nm ieee80211_node_attach ,
36 .\" .Nm ieee80211_node_lateattach ,
37 .\" .Nm ieee80211_node_detach ,
38 .Nm ieee80211_begin_scan ,
39 .Nm ieee80211_create_ibss ,
40 .Nm ieee80211_next_scan ,
41 .Nm ieee80211_end_scan ,
42 .\" .Nm ieee80211_alloc_node ,
43 .\" .Nm ieee80211_dup_bss ,
44 .Nm ieee80211_find_txnode ,
45 .Nm ieee80211_find_rxnode ,
46 .Nm ieee80211_find_node ,
47 .Nm ieee80211_free_node ,
48 .\" .Nm ieee80211_free_allnodes ,
49 .Nm ieee80211_iterate_nodes
50 .Nd software 802.11 stack node management functions
51 .Sh SYNOPSIS
52 .In netproto/802_11/ieee80211_var.h
53 .In netproto/802_11/ieee80211_proto.h
54 .In netproto/802_11/ieee80211_node.h
55 .\" .Ft void
56 .\" .Fn ieee80211_node_attach "struct ieee80211com *ic"
57 .\" .Ft void
58 .\" .Fn ieee80211_node_lateattach "struct ieee80211com *ic"
59 .\" .Ft void
60 .\" .Fn ieee80211_node_detach "struct ieee80211com *ic"
61 .Ft void
62 .Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
63 .Ft void
64 .Fo ieee80211_create_ibss
65 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
66 .Fc
67 .Ft int
68 .Fn ieee80211_next_scan "struct ieee80211com *ic"
69 .Ft void
70 .Fn ieee80211_end_scan "struct ieee80211com *ic"
71 .\" .Ft struct ieee80211_node *
72 .\" .Fo ieee80211_alloc_node
73 .\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
74 .\" .Fc
75 .\" .Ft struct ieee80211_node *
76 .\" .Fo ieee80211_dup_bss
77 .\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
78 .\" .Fc
79 .Ft struct ieee80211_node *
80 .Fn ieee80211_find_txnode "struct ieee80211com *ic" "const uint8_t *macaddr"
81 .Ft struct ieee80211_node *
82 .Fo ieee80211_find_rxnode
83 .Fa "struct ieee80211com *ic" "const struct ieee80211_frame_min *wh"
84 .Fc
85 .Ft struct ieee80211_node *
86 .Fo ieee80211_find_node
87 .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
88 .Fc
89 .Ft void
90 .Fn ieee80211_free_node "struct ieee80211_node *ni"
91 .\" .Ft void
92 .\" .Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
93 .Ft void
94 .Fo ieee80211_iterate_nodes
95 .Fa "struct ieee80211_node_table *nt" "ieee80211_iter_func *f" "void *arg"
96 .Fc
97 .Sh DESCRIPTION
98 These functions are used to manage node lists within the software
99 802.11 stack.
100 These lists are typically used for implementing host-mode AP functionality,
101 implementing transmission rate control algorithms,
102 or providing signal quality information about neighbouring nodes.
103 .Pp
104 .\"
105 .\" The
106 .\" .Fn ieee80211_node_attach
107 .\" function is called from
108 .\" .Xr ieee80211_ifattach 9
109 .\" to initialize node databases management callbacks and control variables
110 .\" for the interface
111 .\" .Fa ic
112 .\" (specifically for memory allocation,
113 .\" node copying,
114 .\" node signal inspection, and station inactivity timer).
115 .\" .Pp
116 .\"
117 .\" The
118 .\" .Fn ieee80211_node_lateattach
119 .\" function initialises the
120 .\" node databases,
121 .\" crypto and authentication settings of
122 .\" .Va ic_bss
123 .\" associated with the interface
124 .\" .Fa ic
125 .\" during
126 .\" .Xr ieee80211_media_init 9 .
127 .\" .Pp
128 .\"
129 .\" The
130 .\" .Fn ieee80211_node_detach
131 .\" function destroys all node databases associated with the interface
132 .\" .Fa ic .
133 .\" .Pp
134 .\"
135 The
136 .Fn ieee80211_begin_scan
137 function initialises the node databases in preparation of an active
138 scan for an access point on the interface
139 .Fa ic .
140 The scan begins on the next radio channel by calling
141 .Fn ieee80211_next_scan
142 internally.
143 If
144 .Fa reset
145 is non-zero, the interface
146 .Fa ic Ap s
147 node table
148 .Va ic_scan ,
149 which holds previously detected access points,
150 will be cleared.
151 The actual scanning for an access point is not automated;
152 the device driver itself only handles setting the radio frequency
153 of the card and stepping through the channels.
154 .Pp
155 .\"
156 The
157 .Fn ieee80211_create_ibss
158 function sets up the net80211-specific portion of an interface's softc
159 .Fa ic ,
160 for use in IBSS mode or HOSTAP mode.
161 .Pp
162 .\"
163 The
164 .Fn ieee80211_next_scan
165 function is used to inform the
166 .Xr ieee80211 9
167 layer that the interface
168 .Fa ic
169 is now scanning for an access point on the next radio channel.
170 .\" XXX should call ieee80211_new_state(ic, IEEE80211_S_SCAN)
171 .\" XXX we may need a manpage to describe ieee80211_new_state()
172 .\" A device driver is expected to first call
173 .\" .Fn ieee80211_begin_scan ,
174 .\" to initialize the node database,
175 .\" then set the radio channel on the device;
176 .\" then, after a certain time has elapsed (200ms for example), call
177 .\" .Fn ieee80211_next_scan
178 .\" to move to the next channel.
179 .\" Typically, a callout is used to automate this process; see
180 .\" .Xr callout_init 9
181 .\" for more information on how to use callouts.
182 .Pp
183 .\"
184 The
185 .Fn ieee80211_end_scan
186 function is called by
187 .Fn ieee80211_next_scan
188 when the state machine has performed a full cycle of scanning on
189 all available radio channels.
190 Internally,
191 .Fn ieee80211_end_scan
192 will inspect the node table
193 .Va ic_scan
194 of the interface
195 .Fa ic
196 for suitable access points found during scanning, and associate with one,
197 should the parameters of the node match those of the configuration
198 requested from userland.
199 .Pp
200 .\"
201 .\" The
202 .\" .Fn ieee80211_alloc_node
203 .\" function allocates an instance of
204 .\" .Vt "struct ieee80211_node"
205 .\" for a node having the MAC address
206 .\" .Fa macaddr ,
207 .\" and associates it with the node table
208 .\" .Fa nt .
209 .\" If the allocation is successful, the node structure is initialised by
210 .\" .Fn ieee80211_setup_node ;
211 .\" otherwise,
212 .\" .Dv NULL
213 .\" is returned.
214 .\" .Pp
215 .\"
216 .\" The
217 .\" .Fn ieee80211_dup_bss
218 .\" function is similar to
219 .\" .Fn ieee80211_alloc_node ,
220 .\" but is instead used to create a node database entry for the BSSID
221 .\" .Fa macaddr
222 .\" associated with the node table
223 .\" .Fa nt .
224 .\" If the allocation is successful, the node structure is initialised by
225 .\" .Fn ieee80211_setup_node ;
226 .\" otherwise,
227 .\" .Dv NULL
228 .\" is returned.
229 .\" .Pp
230 .\"
231 The
232 .Fn ieee80211_find_txnode
233 function will locate a suitable node entry for a frame to be delivered to
234 .Fa macaddr
235 through the interface
236 .Fa ic .
237 .Pp
238 .\"
239 The
240 .Fn ieee80211_find_rxnode
241 function will find the node entry which represents the sender of
242 .Fa wh ,
243 which is received on the interface
244 .Fa ic .
245 .Pp
246 .\"
247 The
248 .Fn ieee80211_find_node
249 function will iterate through the node table
250 .Fa nt ,
251 searching for a node entry which matches
252 .Fa macaddr .
253 .Pp
254 .\"
255 If
256 .Fn ieee80211_find_txnode ,
257 .Fn ieee80211_find_rxnode ,
258 or
259 .Fn ieee80211_find_node ,
260 returns a non-NULL node entry,
261 the node entry's reference count is incremented,
262 so the caller of these functions is responsible to call
263 .Fn ieee80211_free_node .
264 .Pp
265 .\"
266 The
267 .Fn ieee80211_free_node
268 function will decrement the reference count of the node
269 .Fa ni .
270 If either the reference count drops to zero or
271 the last reference left is from
272 .Va nt_keyixmap
273 then
274 .Fa ni
275 will be removed from the node table where it resides,
276 and any memory associated with the node will be freed.
277 .Pp
278 .\"
279 .\" The
280 .\" .Fn ieee80211_free_allnodes
281 .\" function will iterate through the node table
282 .\" .Fa nt ,
283 .\" either calling
284 .\" .Fn ieee80211_free_node
285 .\" for all nodes that reside in
286 .\" .Fa nt
287 .\" or just remove them from
288 .\" .Fa nt .
289 .\" .Pp
290 .\"
291 The
292 .Fn ieee80211_iterate_nodes
293 function will call the user-defined callback function
294 .Fa f
295 for all nodes in the node table
296 .Fa nt .
297 The callback is invoked with the user-supplied value
298 .Fa arg
299 and a pointer to the current node.
300 .\"
301 .Sh RETURN VALUES
302 The function
303 .Fn ieee80211_next_scan
304 returns 0,
305 if a full cycle of scanning on all available radio channels is done.
306 Otherwise, 1 is returned.
307 .Pp
308 .\"
309 The function
310 .Fn ieee80211_find_txnode
311 returns a node entry that is suitable to be used to send a frame to
312 .Fa macaddr .
313 If there is no suitable node found,
314 .Dv NULL
315 is returned.
316 .Pp
317 .\"
318 The function
319 .Fn ieee80211_find_rxnode
320 returns a node entry that represents the sender of
321 .Fa wh .
322 If no suitable node entry can be found,
323 .Va ic_bss
324 is returned.
325 .Pp
326 .\"
327 The function
328 .Fn ieee80211_find_node
329 returns a pointer to the node entry which matches
330 .Fa macaddr .
331 If no match is found,
332 .Dv NULL
333 is returned.
334 .\"
335 .Sh SEE ALSO
336 .Xr ieee80211 9 ,
337 .Xr ifnet 9
338 .Sh HISTORY
339 The
340 .Nm ieee80211
341 series of functions first appeared in
342 .Nx 1.5 ,
343 and were later ported to
344 .Fx 4.6 .
345 .Sh AUTHORS
346 .An -nosplit
347 This man page was written by
348 .An Bruce M. Simpson Aq bms@FreeBSD.org
349 and
350 .An Darron Broad Aq darron@kewl.org .