1.\" $OpenBSD: ieee80211_node.9,v 1.6 2009/12/15 07:34:58 jmc Exp $ 2.\" 3.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> 4.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" $FreeBSD: src/share/man/man9/ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $ 29.\" $Id: ieee80211_node.9,v 1.6 2009/12/15 07:34:58 jmc Exp $ 30.\" 31.Dd $Mdocdate: December 15 2009 $ 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_release_node , 46.Nm ieee80211_free_node , 47.Nm ieee80211_free_allnodes , 48.Nm ieee80211_iterate_nodes 49.Nd software 802.11 stack node management functions 50.Sh SYNOPSIS 51.In net80211/ieee80211_var.h 52.In net80211/ieee80211_proto.h 53.In net80211/ieee80211_node.h 54.Ft void 55.Fn ieee80211_node_attach "struct ifnet *ifp" 56.Ft void 57.Fn ieee80211_node_lateattach "struct ifnet *ifp" 58.Ft void 59.Fn ieee80211_node_detach "struct ifnet *ifp" 60.Ft void 61.Fn ieee80211_begin_scan "struct ifnet *ifp" 62.Ft void 63.Fn ieee80211_next_scan "struct ifnet *ifp" 64.Ft void 65.Fo ieee80211_create_ibss 66.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" 67.Fc 68.Ft void 69.Fn ieee80211_end_scan "struct ifnet *ifp" 70.Ft struct ieee80211_node * 71.Fn ieee80211_alloc_node "struct ieee80211com *ic" "const u_int8_t *macaddr" 72.Ft struct ieee80211_node * 73.Fn ieee80211_dup_bss "struct ieee80211com *ic" "const u_int8_t *macaddr" 74.Ft struct ieee80211_node * 75.Fn ieee80211_find_node "struct ieee80211com *ic" "const u_int8_t *macaddr" 76.Ft struct ieee80211_node * 77.Ft void 78.Fn ieee80211_release_node "struct ieee80211com *ic" "struct ieee80211_node *ni" 79.Ft void 80.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni" 81.Ft void 82.Fn ieee80211_free_allnodes "struct ieee80211com *ic" 83.Ft void 84.Fo ieee80211_iterate_nodes 85.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" 86.Fc 87.Sh DESCRIPTION 88These functions are used to manage node lists within the software 89802.11 stack. 90These lists are typically used for implementing host-mode AP functionality, 91or providing signal quality information about neighbouring nodes. 92.Pp 93.\" 94The 95.Fn ieee80211_node_attach 96function is called from 97.Xr ieee80211_ifattach 9 98to initialize node database management callbacks for the interface 99.Fa ifp 100(specifically for memory allocation, node copying and node 101signal inspection). 102These functions may be overridden in special circumstances, 103as long as this is done after calling 104.Xr ieee80211_ifattach 9 105and prior to any other call which may allocate a node. 106.Pp 107.\" 108The 109.Fn ieee80211_node_lateattach 110function initialises the 111.Va ic_bss 112node element of the interface 113.Fa ifp 114during 115.Xr ieee80211_media_init 9 . 116This late attachment is to account for certain special cases described under 117.Fn ieee80211_node_attach . 118.Pp 119.\" 120The 121.Fn ieee80211_node_detach 122function destroys all node database state associated with the interface 123.Fa ifp , 124and is usually called during device detach. 125.Pp 126.\" 127The 128.Fn ieee80211_begin_scan 129function initialises the node database in preparation of an active 130scan for an access point on the interface 131.Fa ifp . 132The scan begins on the next radio channel by calling 133.Fn ieee80211_next_scan 134internally. 135The actual scanning for an access point is not automated; 136the device driver itself only handles setting the radio frequency 137of the card and stepping through the channels. 138.Pp 139.\" 140The 141.Fn ieee80211_next_scan 142function is used to inform the 143.Xr ieee80211 9 144layer that the interface 145.Fa ifp 146is now scanning for an access point on the next radio channel. 147A device driver is expected to first call 148.Fn ieee80211_begin_scan , 149to initialize the node database, 150then set the radio channel on the device; 151then, after a certain time has elapsed (200ms for example), call 152.Fn ieee80211_next_scan 153to move to the next channel. 154Typically, a timeout is used to automate this process; see 155.Xr timeout 9 156for more information on how to use timeouts. 157.Pp 158.\" 159The 160.Fn ieee80211_create_ibss 161function sets up the net80211-specific portion of an interface's softc, 162.Fa ic , 163for use in IBSS mode. 164.Pp 165.\" 166The 167.Fn ieee80211_end_scan 168function is called by 169.Fn ieee80211_next_scan 170when the state machine has performed a full cycle of scanning on 171all available radio channels. 172Internally, 173.Fn ieee80211_end_scan 174will inspect the node cache associated with the interface 175.Fa ifp 176for suitable access points found during scanning, and associate with one, 177should the parameters of the node match those of the configuration 178requested from userland. 179.Pp 180.\" 181The 182.Fn ieee80211_alloc_node 183function allocates an instance of 184.Vt "struct ieee80211_node" 185for a node having the MAC address 186.Fa macaddr , 187and associates it with the interface 188.Fa ic . 189If the allocation is successful, the node structure is initialised by 190.Fn ieee80211_setup_node ; 191otherwise, 192.Dv NULL 193is returned. 194.Pp 195.\" 196The 197.Fn ieee80211_dup_bss 198function is similar to 199.Fn ieee80211_alloc_node , 200but is instead used to create a node database entry for the BSSID 201.Fa macaddr 202associated with the interface 203.Fa ic . 204If the allocation is successful, the node structure is initialised by 205.Fn ieee80211_setup_node ; 206otherwise, 207.Dv NULL 208is returned. 209.Pp 210.\" 211The 212.Fn ieee80211_find_node 213function will iterate through the node list associated with the interface 214.Fa ic , 215searching for a node entry which matches 216.Fa macaddr . 217If the entry is found, its reference count is incremented, and 218a pointer to the node is returned; otherwise, 219.Dv NULL 220will be returned. 221.Pp 222.\" 223The 224.Fn ieee80211_free_node 225function will remove the node 226.Fa ni 227from the node database entries associated with the interface 228.Fa ic , 229and free any memory associated with the node. 230This private method can be overridden in 231.Fn ieee80211_node_attach . 232.\" 233.Pp 234The 235.Fn ieee80211_free_allnodes 236function will iterate through the node list calling 237.Fn ieee80211_free_node 238for all nodes associated with the interface 239.Fa ic . 240.Pp 241.\" 242The 243.Fn ieee80211_iterate_nodes 244function will call the user-defined callback function 245.Fa f 246for all nodes in the node database associated with the interface 247.Fa ic . 248The callback is invoked with the with the user-supplied value 249.Fa arg 250and a pointer to the current node. 251.\" 252.Sh SEE ALSO 253.Xr ieee80211 9 254.Sh HISTORY 255The 256.Nm ieee80211 257series of functions first appeared in 258.Nx 1.5 , 259and were later ported to 260.Fx 4.6 261and 262.Ox 3.6 . 263.Sh AUTHORS 264.An -nosplit 265This man page was written by 266.An Bruce M. Simpson Aq bms@FreeBSD.org 267and 268.An Darron Broad Aq darron@kewl.org . 269