1.\" $OpenBSD: ieee80211_node.9,v 1.9 2015/11/23 17:53:57 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.9 2015/11/23 17:53:57 jmc Exp $ 30.\" 31.Dd $Mdocdate: November 23 2015 $ 32.Dt IEEE80211_NODE_ATTACH 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 void 77.Fn ieee80211_release_node "struct ieee80211com *ic" "struct ieee80211_node *ni" 78.Ft void 79.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni" 80.Ft void 81.Fn ieee80211_free_allnodes "struct ieee80211com *ic" 82.Ft void 83.Fo ieee80211_iterate_nodes 84.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" 85.Fc 86.Sh DESCRIPTION 87These functions are used to manage node lists within the software 88802.11 stack. 89These lists are typically used for implementing host-mode AP functionality, 90or providing signal quality information about neighbouring nodes. 91.Pp 92.\" 93The 94.Fn ieee80211_node_attach 95function is called from 96.Xr ieee80211_ifattach 9 97to initialize node database management callbacks for the interface 98.Fa ifp 99(specifically for memory allocation, node copying and node 100signal inspection). 101These functions may be overridden in special circumstances, 102as long as this is done after calling 103.Xr ieee80211_ifattach 9 104and prior to any other call which may allocate a node. 105.Pp 106.\" 107The 108.Fn ieee80211_node_lateattach 109function initialises the 110.Va ic_bss 111node element of the interface 112.Fa ifp 113during 114.Xr ieee80211_media_init 9 . 115This late attachment is to account for certain special cases described under 116.Fn ieee80211_node_attach . 117.Pp 118.\" 119The 120.Fn ieee80211_node_detach 121function destroys all node database state associated with the interface 122.Fa ifp , 123and is usually called during device detach. 124.Pp 125.\" 126The 127.Fn ieee80211_begin_scan 128function initialises the node database in preparation of an active 129scan for an access point on the interface 130.Fa ifp . 131The scan begins on the next radio channel by calling 132.Fn ieee80211_next_scan 133internally. 134The actual scanning for an access point is not automated; 135the device driver itself only handles setting the radio frequency 136of the card and stepping through the channels. 137.Pp 138.\" 139The 140.Fn ieee80211_next_scan 141function is used to inform the 142.Xr ieee80211 9 143layer that the interface 144.Fa ifp 145is now scanning for an access point on the next radio channel. 146A device driver is expected to first call 147.Fn ieee80211_begin_scan , 148to initialize the node database, 149then set the radio channel on the device; 150then, after a certain time has elapsed (200ms for example), call 151.Fn ieee80211_next_scan 152to move to the next channel. 153Typically, a timeout is used to automate this process; see 154.Xr timeout 9 155for more information on how to use timeouts. 156.Pp 157.\" 158The 159.Fn ieee80211_create_ibss 160function sets up the net80211-specific portion of an interface's softc, 161.Fa ic , 162for use in IBSS mode. 163.Pp 164.\" 165The 166.Fn ieee80211_end_scan 167function is called by 168.Fn ieee80211_next_scan 169when the state machine has performed a full cycle of scanning on 170all available radio channels. 171Internally, 172.Fn ieee80211_end_scan 173will inspect the node cache associated with the interface 174.Fa ifp 175for suitable access points found during scanning, and associate with one, 176should the parameters of the node match those of the configuration 177requested from userland. 178.Pp 179.\" 180The 181.Fn ieee80211_alloc_node 182function allocates an instance of 183.Vt "struct ieee80211_node" 184for a node having the MAC address 185.Fa macaddr , 186and associates it with the interface 187.Fa ic . 188If the allocation is successful, the node structure is initialised by 189.Fn ieee80211_setup_node ; 190otherwise, 191.Dv NULL 192is returned. 193.Pp 194.\" 195The 196.Fn ieee80211_dup_bss 197function is similar to 198.Fn ieee80211_alloc_node , 199but is instead used to create a node database entry for the BSSID 200.Fa macaddr 201associated with the interface 202.Fa ic . 203If the allocation is successful, the node structure is initialised by 204.Fn ieee80211_setup_node ; 205otherwise, 206.Dv NULL 207is returned. 208.Pp 209.\" 210The 211.Fn ieee80211_find_node 212function will iterate through the node list associated with the interface 213.Fa ic , 214searching for a node entry which matches 215.Fa macaddr . 216If the entry is found, its reference count is incremented, and 217a pointer to the node is returned; otherwise, 218.Dv NULL 219will be returned. 220.Pp 221.\" 222The 223.Fn ieee80211_free_node 224function will remove the node 225.Fa ni 226from the node database entries associated with the interface 227.Fa ic , 228and free any memory associated with the node. 229This private method can be overridden in 230.Fn ieee80211_node_attach . 231.\" 232.Pp 233The 234.Fn ieee80211_free_allnodes 235function will iterate through the node list calling 236.Fn ieee80211_free_node 237for all nodes associated with the interface 238.Fa ic . 239.Pp 240.\" 241The 242.Fn ieee80211_iterate_nodes 243function will call the user-defined callback function 244.Fa f 245for all nodes in the node database associated with the interface 246.Fa ic . 247The callback is invoked with the with the user-supplied value 248.Fa arg 249and a pointer to the current node. 250.\" 251.Sh SEE ALSO 252.Xr ieee80211 9 253.Sh HISTORY 254The 255.Nm ieee80211 256series of functions first appeared in 257.Nx 1.5 , 258and were later ported to 259.Fx 4.6 260and 261.Ox 3.6 . 262.Sh AUTHORS 263.An -nosplit 264This man page was written by 265.An Bruce M. Simpson Aq Mt bms@FreeBSD.org 266and 267.An Darron Broad Aq Mt darron@kewl.org . 268