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
28 .\" $Id: ieee80211_node.9,v 1.6 2004/03/04 12:33:27 bruce Exp $
34 .Nm ieee80211_node_attach ,
35 .Nm ieee80211_node_lateattach ,
36 .Nm ieee80211_node_detach ,
37 .Nm ieee80211_begin_scan ,
38 .Nm ieee80211_next_scan ,
39 .Nm ieee80211_create_ibss ,
40 .Nm ieee80211_end_scan ,
41 .Nm ieee80211_alloc_node ,
42 .Nm ieee80211_dup_bss ,
43 .Nm ieee80211_find_node ,
44 .Nm ieee80211_lookup_node ,
45 .Nm ieee80211_free_node ,
46 .Nm ieee80211_free_allnodes ,
47 .Nm ieee80211_timeout_nodes ,
48 .Nm ieee80211_iterate_nodes
49 .Nd software 802.11 stack node management functions
51 .In net80211/ieee80211_var.h
52 .In net80211/ieee80211_proto.h
53 .In net80211/ieee80211_node.h
55 .Fn ieee80211_node_attach "struct ifnet *ifp"
57 .Fn ieee80211_node_lateattach "struct ifnet *ifp"
59 .Fn ieee80211_node_detach "struct ifnet *ifp"
61 .Fn ieee80211_begin_scan "struct ifnet *ifp"
63 .Fn ieee80211_next_scan "struct ifnet *ifp"
65 .Fo ieee80211_create_ibss
66 .Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
69 .Fn ieee80211_end_scan "struct ifnet *ifp"
70 .Ft struct ieee80211_node *
71 .Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr"
72 .Ft struct ieee80211_node *
73 .Fn ieee80211_dup_bss "struct ieee80211com *ic" "u_int8_t *macaddr"
74 .Ft struct ieee80211_node *
75 .Fn ieee80211_find_node "struct ieee80211com *ic" "u_int8_t *macaddr"
76 .Ft struct ieee80211_node *
77 .Fo ieee80211_lookup_node
78 .Fa "struct ieee80211com *ic" "u_int8_t *macaddr"
79 .Fa "struct ieee80211_channel *chan"
82 .Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni"
84 .Fn ieee80211_free_allnodes "struct ieee80211com *ic"
86 .Fn ieee80211_timeout_nodes "struct ieee80211com *ic"
88 .Fo ieee80211_iterate_nodes
89 .Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg"
92 These functions are used to manage node lists within the software
94 These lists are typically used for implementing host-mode AP functionality,
95 or providing signal quality information about neighbouring nodes.
99 .Fn ieee80211_node_attach
100 function is called from
101 .Xr ieee80211_ifattach 9
102 to initialize node database management callbacks for the interface
104 (specifically for memory allocation, node copying and node
106 These functions may be overridden in special circumstances,
107 as long as this is done after calling
108 .Xr ieee80211_ifattach 9
109 and prior to any other call which may allocate a node.
113 .Fn ieee80211_node_lateattach
114 function initialises the
116 node element of the interface
119 .Xr ieee80211_media_init 9 .
120 This late attachment is to account for certain special cases described under
121 .Fn ieee80211_node_attach .
125 .Fn ieee80211_node_detach
126 function destroys all node database state associated with the interface
128 and is usually called during device detach.
132 .Fn ieee80211_begin_scan
133 function initialises the node database in preparation of an active
134 scan for an access point on the interface
136 The scan begins on the next radio channel by calling
137 .Fn ieee80211_next_scan
139 The actual scanning for an access point is not automated;
140 the device driver itself only handles setting the radio frequency
141 of the card and stepping through the channels.
145 .Fn ieee80211_next_scan
146 function is used to inform the
148 layer that the interface
150 is now scanning for an access point on the next radio channel.
151 A device driver is expected to first call
152 .Fn ieee80211_begin_scan ,
153 to initialize the node database,
154 then set the radio channel on the device;
155 then, after a certain time has elapsed (200ms for example), call
156 .Fn ieee80211_next_scan
157 to move to the next channel.
158 Typically, a callout is used to automate this process; see
160 for more information on how to use callouts.
164 .Fn ieee80211_create_ibss
165 function sets up the net80211-specific portion of an interface's softc,
167 for use in IBSS mode.
171 .Fn ieee80211_end_scan
172 function is called by
173 .Fn ieee80211_next_scan
174 when the state machine has peformed a full cycle of scanning on
175 all available radio channels.
177 .Fn ieee80211_end_scan
178 will inspect the node cache associated with the interface
180 for suitable access points found during scanning, and associate with one,
181 should the parameters of the node match those of the configuration
182 requested from userland.
186 .Fn ieee80211_alloc_node
187 function allocates an instance of
188 .Vt "struct ieee80211_node"
189 for a node having the MAC address
191 and associates it with the interface
193 If the allocation is successful, the node structure is initialised by
194 .Fn ieee80211_setup_node ;
201 .Fn ieee80211_dup_bss
202 function is similar to
203 .Fn ieee80211_alloc_node ,
204 but is instead used to create a node database entry for the BSSID
206 associated with the interface
208 If the allocation is successful, the node structure is initialised by
209 .Fn ieee80211_setup_node ;
216 .Fn ieee80211_find_node
217 function will iterate through the node list associated with the interface
219 searching for a node entry which matches
221 If the entry is found, its reference count is incremented, and
222 a pointer to the node is returned; otherwise,
228 .Fn ieee80211_lookup_node
229 function is similar to
230 .Fn ieee80211_find_node ,
231 with an additional argument
233 which is used to specify a channel for the match.
234 If the entry is found, its reference count is incremented, and
235 a pointer to the node is returned; otherwise,
241 .Fn ieee80211_free_node
242 function will remove the node
244 from the node database entries associated with the interface
246 and free any memory associated with the node.
247 This private method can be overridden in
248 .Fn ieee80211_node_attach .
252 .Fn ieee80211_free_allnodes
253 function will iterate through the node list calling
254 .Fn ieee80211_free_node
255 for all nodes associated with the interface
260 .Fn ieee80211_timeout_nodes
261 checks if the inactivity timer of each node associated with the interface
263 has exceeded the pre-defined constant
264 .Dv IEEE80211_INACT_MAX .
265 If so, then the node is freed, after sending a deauthentication message.
269 .Fn ieee80211_iterate_nodes
270 function will call the user-defined callback function
272 for all nodes in the node database associated with the interface
274 The callback is invoked with the with the user-supplied value
276 and a pointer to the current node.
284 series of functions first appeared in
286 and were later ported to
290 This manual page was written by
291 .An Bruce M. Simpson Aq bms@FreeBSD.org
293 .An Darron Broad Aq darron@kewl.org .