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.3 2006/06/28 19:41:59 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 98These functions are used to manage node lists within the software 99802.11 stack. 100These lists are typically used for implementing host-mode AP functionality, 101implementing transmission rate control algorithms, 102or 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.\" 135The 136.Fn ieee80211_begin_scan 137function initialises the node databases in preparation of an active 138scan for an access point on the interface 139.Fa ic . 140The scan begins on the next radio channel by calling 141.Fn ieee80211_next_scan 142internally. 143If 144.Fa reset 145is non-zero, the interface 146.Fa ic Ap s 147node table 148.Va ic_scan , 149which holds previously detected access points, 150will be cleared. 151The actual scanning for an access point is not automated; 152the device driver itself only handles setting the radio frequency 153of the card and stepping through the channels. 154.Pp 155.\" 156The 157.Fn ieee80211_create_ibss 158function sets up the net80211-specific portion of an interface's softc 159.Fa ic , 160for use in IBSS mode or HOSTAP mode. 161.Pp 162.\" 163The 164.Fn ieee80211_next_scan 165function is used to inform the 166.Xr ieee80211 9 167layer that the interface 168.Fa ic 169is 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.\" 184The 185.Fn ieee80211_end_scan 186function is called by 187.Fn ieee80211_next_scan 188when the state machine has peformed a full cycle of scanning on 189all available radio channels. 190Internally, 191.Fn ieee80211_end_scan 192will inspect the node table 193.Va ic_scan 194of the interface 195.Fa ic 196for suitable access points found during scanning, and associate with one, 197should the parameters of the node match those of the configuration 198requested 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.\" 231The 232.Fn ieee80211_find_txnode 233function will locate a suitable node entry for a frame to be delivered to 234.Fa macaddr 235through the interface 236.Fa ic . 237.Pp 238.\" 239The 240.Fn ieee80211_find_rxnode 241function will find the node entry which represents the sender of 242.Fa wh , 243which is received on the interface 244.Fa ic . 245.Pp 246.\" 247The 248.Fn ieee80211_find_node 249function will iterate through the node table 250.Fa nt , 251searching for a node entry which matches 252.Fa macaddr . 253.Pp 254.\" 255If 256.Fn ieee80211_find_txnode , 257.Fn ieee80211_find_rxnode , 258or 259.Fn ieee80211_find_node , 260returns a non-NULL node entry, 261the node entry's reference count is incremented, 262so the caller of these functions is responsible to call 263.Fn ieee80211_free_node . 264.Pp 265.\" 266The 267.Fn ieee80211_free_node 268function will decrement the reference count of the node 269.Fa ni . 270If either the reference count drops to zero or 271the last reference left is from 272.Va nt_keyixmap 273then 274.Fa ni 275will be removed from the node table where it resides, 276and 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.\" 291The 292.Fn ieee80211_iterate_nodes 293function will call the user-defined callback function 294.Fa f 295for all nodes in the node table 296.Fa nt . 297The callback is invoked with the user-supplied value 298.Fa arg 299and a pointer to the current node. 300.\" 301.Sh RETURN VALUES 302The function 303.Fn ieee80211_next_scan 304returns 0, 305if a full cycle of scanning on all available radio channels is done. 306Otherwise, 1 is returned. 307.Pp 308.\" 309The fucntion 310.Fn ieee80211_find_txnode 311returns a node entry that is suitable to be used to send a frame to 312.Fa macaddr . 313If there is no suitable node found, 314.Dv NULL 315is returned. 316.Pp 317.\" 318The function 319.Fn ieee80211_find_rxnode 320returns a node entry that represents the sender of 321.Fa wh . 322If no suitable node entry can be found, 323.Va ic_bss 324is returned. 325.Pp 326.\" 327The function 328.Fn ieee80211_find_node 329returns a pointer to the node entry which matches 330.Fa macaddr . 331If no match is found, 332.Dv NULL 333is returned. 334.\" 335.Sh SEE ALSO 336.Xr ieee80211 9 , 337.Xr ifnet 9 338.Sh HISTORY 339The 340.Nm ieee80211 341series of functions first appeared in 342.Nx 1.5 , 343and were later ported to 344.Fx 4.6 . 345.Sh AUTHORS 346.An -nosplit 347This man page was written by 348.An Bruce M. Simpson Aq bms@FreeBSD.org 349and 350.An Darron Broad Aq darron@kewl.org . 351