diff options
Diffstat (limited to 'share/man/man9/ieee80211_node.9')
| -rw-r--r-- | share/man/man9/ieee80211_node.9 | 293 |
1 files changed, 293 insertions, 0 deletions
diff --git a/share/man/man9/ieee80211_node.9 b/share/man/man9/ieee80211_node.9 new file mode 100644 index 000000000000..c9d142a31a3c --- /dev/null +++ b/share/man/man9/ieee80211_node.9 @@ -0,0 +1,293 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" $Id: ieee80211_node.9,v 1.6 2004/03/04 12:33:27 bruce Exp $ +.\" +.Dd July 4, 2004 +.Dt IEEE80211_NODE 9 +.Os +.Sh NAME +.Nm ieee80211_node_attach , +.Nm ieee80211_node_lateattach , +.Nm ieee80211_node_detach , +.Nm ieee80211_begin_scan , +.Nm ieee80211_next_scan , +.Nm ieee80211_create_ibss , +.Nm ieee80211_end_scan , +.Nm ieee80211_alloc_node , +.Nm ieee80211_dup_bss , +.Nm ieee80211_find_node , +.Nm ieee80211_lookup_node , +.Nm ieee80211_free_node , +.Nm ieee80211_free_allnodes , +.Nm ieee80211_timeout_nodes , +.Nm ieee80211_iterate_nodes +.Nd software 802.11 stack node management functions +.Sh SYNOPSIS +.In net80211/ieee80211_var.h +.In net80211/ieee80211_proto.h +.In net80211/ieee80211_node.h +.Ft void +.Fn ieee80211_node_attach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_node_lateattach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_node_detach "struct ifnet *ifp" +.Ft void +.Fn ieee80211_begin_scan "struct ifnet *ifp" +.Ft void +.Fn ieee80211_next_scan "struct ifnet *ifp" +.Ft void +.Fo ieee80211_create_ibss +.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" +.Fc +.Ft void +.Fn ieee80211_end_scan "struct ifnet *ifp" +.Ft struct ieee80211_node * +.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr" +.Ft struct ieee80211_node * +.Fn ieee80211_dup_bss "struct ieee80211com *ic" "u_int8_t *macaddr" +.Ft struct ieee80211_node * +.Fn ieee80211_find_node "struct ieee80211com *ic" "u_int8_t *macaddr" +.Ft struct ieee80211_node * +.Fo ieee80211_lookup_node +.Fa "struct ieee80211com *ic" "u_int8_t *macaddr" +.Fa "struct ieee80211_channel *chan" +.Fc +.Ft void +.Fn ieee80211_free_node "struct ieee80211com *ic" "struct ieee80211_node *ni" +.Ft void +.Fn ieee80211_free_allnodes "struct ieee80211com *ic" +.Ft void +.Fn ieee80211_timeout_nodes "struct ieee80211com *ic" +.Ft void +.Fo ieee80211_iterate_nodes +.Fa "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" +.Fc +.Sh DESCRIPTION +These functions are used to manage node lists within the software +802.11 stack. +These lists are typically used for implementing host-mode AP functionality, +or providing signal quality information about neighbouring nodes. +.Pp +.\" +The +.Fn ieee80211_node_attach +function is called from +.Xr ieee80211_ifattach 9 +to initialize node database management callbacks for the interface +.Fa ifp +(specifically for memory allocation, node copying and node +signal inspection). +These functions may be overridden in special circumstances, +as long as this is done after calling +.Xr ieee80211_ifattach 9 +and prior to any other call which may allocate a node. +.Pp +.\" +The +.Fn ieee80211_node_lateattach +function initialises the +.Va ic_bss +node element of the interface +.Fa ifp +during +.Xr ieee80211_media_init 9 . +This late attachment is to account for certain special cases described under +.Fn ieee80211_node_attach . +.Pp +.\" +The +.Fn ieee80211_node_detach +function destroys all node database state associated with the interface +.Fa ifp , +and is usually called during device detach. +.Pp +.\" +The +.Fn ieee80211_begin_scan +function initialises the node database in preparation of an active +scan for an access point on the interface +.Fa ifp . +The scan begins on the next radio channel by calling +.Fn ieee80211_next_scan +internally. +The actual scanning for an access point is not automated; +the device driver itself only handles setting the radio frequency +of the card and stepping through the channels. +.Pp +.\" +The +.Fn ieee80211_next_scan +function is used to inform the +.Xr ieee80211 9 +layer that the interface +.Fa ifp +is now scanning for an access point on the next radio channel. +A device driver is expected to first call +.Fn ieee80211_begin_scan , +to initialize the node database, +then set the radio channel on the device; +then, after a certain time has elapsed (200ms for example), call +.Fn ieee80211_next_scan +to move to the next channel. +Typically, a callout is used to automate this process; see +.Xr callout_init 9 +for more information on how to use callouts. +.Pp +.\" +The +.Fn ieee80211_create_ibss +function sets up the net80211-specific portion of an interface's softc, +.Fa ic , +for use in IBSS mode. +.Pp +.\" +The +.Fn ieee80211_end_scan +function is called by +.Fn ieee80211_next_scan +when the state machine has peformed a full cycle of scanning on +all available radio channels. +Internally, +.Fn ieee80211_end_scan +will inspect the node cache associated with the interface +.Fa ifp +for suitable access points found during scanning, and associate with one, +should the parameters of the node match those of the configuration +requested from userland. +.Pp +.\" +The +.Fn ieee80211_alloc_node +function allocates an instance of +.Vt "struct ieee80211_node" +for a node having the MAC address +.Fa macaddr , +and associates it with the interface +.Fa ic . +If the allocation is successful, the node structure is initialised by +.Fn ieee80211_setup_node ; +otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_dup_bss +function is similar to +.Fn ieee80211_alloc_node , +but is instead used to create a node database entry for the BSSID +.Fa macaddr +associated with the interface +.Fa ic . +If the allocation is successful, the node structure is initialised by +.Fn ieee80211_setup_node ; +otherwise, +.Dv NULL +is returned. +.Pp +.\" +The +.Fn ieee80211_find_node +function will iterate through the node list associated with the interface +.Fa ic , +searching for a node entry which matches +.Fa macaddr . +If the entry is found, its reference count is incremented, and +a pointer to the node is returned; otherwise, +.Dv NULL +will be returned. +.Pp +.\" +The +.Fn ieee80211_lookup_node +function is similar to +.Fn ieee80211_find_node , +with an additional argument +.Fa chan +which is used to specify a channel for the match. +If the entry is found, its reference count is incremented, and +a pointer to the node is returned; otherwise, +.Dv NULL +will be returned. +.Pp +.\" +The +.Fn ieee80211_free_node +function will remove the node +.Fa ni +from the node database entries associated with the interface +.Fa ic , +and free any memory associated with the node. +This private method can be overridden in +.Fn ieee80211_node_attach . +.\" +.Pp +The +.Fn ieee80211_free_allnodes +function will iterate through the node list calling +.Fn ieee80211_free_node +for all nodes associated with the interface +.Fa ic . +.Pp +.\" +The +.Fn ieee80211_timeout_nodes +checks if the inactivity timer of each node associated with the interface +.Fa ic +has exceeded the pre-defined constant +.Dv IEEE80211_INACT_MAX . +If so, then the node is freed, after sending a deauthentication message. +.Pp +.\" +The +.Fn ieee80211_iterate_nodes +function will call the user-defined callback function +.Fa f +for all nodes in the node database associated with the interface +.Fa ic . +The callback is invoked with the with the user-supplied value +.Fa arg +and a pointer to the current node. +.\" +.Sh SEE ALSO +.Xr ieee80211 9 , +.Xr ifnet 9 +.Sh HISTORY +The +.Nm ieee80211 +series of functions first appeared in +.Nx 1.5 , +and were later ported to +.Fx 4.6 . +.Sh AUTHORS +.An -nosplit +This manual page was written by +.An Bruce M. Simpson Aq bms@FreeBSD.org +and +.An Darron Broad Aq darron@kewl.org . |