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.1 2004/07/27 14:50:56 hmp Exp $ 29.\" $Id: ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $ 30.\" 31.Dd July 4, 2004 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_next_scan , 40.Nm ieee80211_create_ibss , 41.Nm ieee80211_end_scan , 42.Nm ieee80211_alloc_node , 43.Nm ieee80211_dup_bss , 44.Nm ieee80211_find_node , 45.Nm ieee80211_lookup_node , 46.Nm ieee80211_free_node , 47.Nm ieee80211_free_allnodes , 48.Nm ieee80211_timeout_nodes , 49.Nm ieee80211_iterate_nodes 50.Nd software 802.11 stack node management functions 51.Sh SYNOPSIS 52.In net80211/ieee80211_var.h 53.In net80211/ieee80211_proto.h 54.In net80211/ieee80211_node.h 55.Ft void 56.Fn ieee80211_node_attach "struct ifnet *ifp" 57.Ft void 58.Fn ieee80211_node_lateattach "struct ifnet *ifp" 59.Ft void 60.Fn ieee80211_node_detach "struct ifnet *ifp" 61.Ft void 62.Fn ieee80211_begin_scan "struct ifnet *ifp" 63.Ft void 64.Fn ieee80211_next_scan "struct ifnet *ifp" 65.Ft void 66.Fo ieee80211_create_ibss 67.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" 68.Fc 69.Ft void 70.Fn ieee80211_end_scan "struct ifnet *ifp" 71.Ft struct ieee80211_node * 72.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr" 73.Ft struct ieee80211_node * 74.Fn ieee80211_dup_bss "struct ieee80211com *ic" "u_int8_t *macaddr" 75.Ft struct ieee80211_node * 76.Fn ieee80211_find_node "struct ieee80211com *ic" "u_int8_t *macaddr" 77.Ft struct ieee80211_node * 78.Fo ieee80211_lookup_node 79.Fa "struct ieee80211com *ic" "u_int8_t *macaddr" 80.Fa "struct ieee80211_channel *chan" 81.Fc 82.Ft void 83.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni" 84.Ft void 85.Fn ieee80211_free_allnodes "struct ieee80211com *ic" 86.Ft void 87.Fn ieee80211_timeout_nodes "struct ieee80211com *ic" 88.Ft void 89.Fo ieee80211_iterate_nodes 90.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" 91.Fc 92.Sh DESCRIPTION 93These functions are used to manage node lists within the software 94802.11 stack. 95These lists are typically used for implementing host-mode AP functionality, 96or providing signal quality information about neighbouring nodes. 97.Pp 98.\" 99The 100.Fn ieee80211_node_attach 101function is called from 102.Xr ieee80211_ifattach 9 103to initialize node database management callbacks for the interface 104.Fa ifp 105(specifically for memory allocation, node copying and node 106signal inspection). 107These functions may be overridden in special circumstances, 108as long as this is done after calling 109.Xr ieee80211_ifattach 9 110and prior to any other call which may allocate a node. 111.Pp 112.\" 113The 114.Fn ieee80211_node_lateattach 115function initialises the 116.Va ic_bss 117node element of the interface 118.Fa ifp 119during 120.Xr ieee80211_media_init 9 . 121This late attachment is to account for certain special cases described under 122.Fn ieee80211_node_attach . 123.Pp 124.\" 125The 126.Fn ieee80211_node_detach 127function destroys all node database state associated with the interface 128.Fa ifp , 129and is usually called during device detach. 130.Pp 131.\" 132The 133.Fn ieee80211_begin_scan 134function initialises the node database in preparation of an active 135scan for an access point on the interface 136.Fa ifp . 137The scan begins on the next radio channel by calling 138.Fn ieee80211_next_scan 139internally. 140The actual scanning for an access point is not automated; 141the device driver itself only handles setting the radio frequency 142of the card and stepping through the channels. 143.Pp 144.\" 145The 146.Fn ieee80211_next_scan 147function is used to inform the 148.Xr ieee80211 9 149layer that the interface 150.Fa ifp 151is now scanning for an access point on the next radio channel. 152A device driver is expected to first call 153.Fn ieee80211_begin_scan , 154to initialize the node database, 155then set the radio channel on the device; 156then, after a certain time has elapsed (200ms for example), call 157.Fn ieee80211_next_scan 158to move to the next channel. 159Typically, a callout is used to automate this process; see 160.Xr callout_init 9 161for more information on how to use callouts. 162.Pp 163.\" 164The 165.Fn ieee80211_create_ibss 166function sets up the net80211-specific portion of an interface's softc, 167.Fa ic , 168for use in IBSS mode. 169.Pp 170.\" 171The 172.Fn ieee80211_end_scan 173function is called by 174.Fn ieee80211_next_scan 175when the state machine has peformed a full cycle of scanning on 176all available radio channels. 177Internally, 178.Fn ieee80211_end_scan 179will inspect the node cache associated with the interface 180.Fa ifp 181for suitable access points found during scanning, and associate with one, 182should the parameters of the node match those of the configuration 183requested from userland. 184.Pp 185.\" 186The 187.Fn ieee80211_alloc_node 188function allocates an instance of 189.Vt "struct ieee80211_node" 190for a node having the MAC address 191.Fa macaddr , 192and associates it with the interface 193.Fa ic . 194If the allocation is successful, the node structure is initialised by 195.Fn ieee80211_setup_node ; 196otherwise, 197.Dv NULL 198is returned. 199.Pp 200.\" 201The 202.Fn ieee80211_dup_bss 203function is similar to 204.Fn ieee80211_alloc_node , 205but is instead used to create a node database entry for the BSSID 206.Fa macaddr 207associated with the interface 208.Fa ic . 209If the allocation is successful, the node structure is initialised by 210.Fn ieee80211_setup_node ; 211otherwise, 212.Dv NULL 213is returned. 214.Pp 215.\" 216The 217.Fn ieee80211_find_node 218function will iterate through the node list associated with the interface 219.Fa ic , 220searching for a node entry which matches 221.Fa macaddr . 222If the entry is found, its reference count is incremented, and 223a pointer to the node is returned; otherwise, 224.Dv NULL 225will be returned. 226.Pp 227.\" 228The 229.Fn ieee80211_lookup_node 230function is similar to 231.Fn ieee80211_find_node , 232with an additional argument 233.Fa chan 234which is used to specify a channel for the match. 235If the entry is found, its reference count is incremented, and 236a pointer to the node is returned; otherwise, 237.Dv NULL 238will be returned. 239.Pp 240.\" 241The 242.Fn ieee80211_free_node 243function will remove the node 244.Fa ni 245from the node database entries associated with the interface 246.Fa ic , 247and free any memory associated with the node. 248This private method can be overridden in 249.Fn ieee80211_node_attach . 250.\" 251.Pp 252The 253.Fn ieee80211_free_allnodes 254function will iterate through the node list calling 255.Fn ieee80211_free_node 256for all nodes associated with the interface 257.Fa ic . 258.Pp 259.\" 260The 261.Fn ieee80211_timeout_nodes 262checks if the inactivity timer of each node associated with the interface 263.Fa ic 264has exceeded the pre-defined constant 265.Dv IEEE80211_INACT_MAX . 266If so, then the node is freed, after sending a deauthentication message. 267.Pp 268.\" 269The 270.Fn ieee80211_iterate_nodes 271function will call the user-defined callback function 272.Fa f 273for all nodes in the node database associated with the interface 274.Fa ic . 275The callback is invoked with the with the user-supplied value 276.Fa arg 277and a pointer to the current node. 278.\" 279.Sh SEE ALSO 280.Xr ieee80211 9 , 281.Xr ifnet 9 282.Sh HISTORY 283The 284.Nm ieee80211 285series of functions first appeared in 286.Nx 1.5 , 287and were later ported to 288.Fx 4.6 . 289.Sh AUTHORS 290.An -nosplit 291This man page was written by 292.An Bruce M. Simpson Aq bms@FreeBSD.org 293and 294.An Darron Broad Aq darron@kewl.org . 295