xref: /dflybsd-src/share/man/man9/ieee80211_node.9 (revision 1102a27e1141baf846d4f8ced2aecee4870b4260)

.\"
.\" 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$
.\" $DragonFly: src/share/man/man9/ieee80211_node.9,v 1.3 2006/06/28 19:41:59 swildner Exp $
.\" $Id: ieee80211_node.9,v 1.3 2004/07/07 12:59:39 ru Exp $
.\"
.Dd June 28, 2006
.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_create_ibss ,
.Nm ieee80211_next_scan ,
.Nm ieee80211_end_scan ,
.\" .Nm ieee80211_alloc_node ,
.\" .Nm ieee80211_dup_bss ,
.Nm ieee80211_find_txnode ,
.Nm ieee80211_find_rxnode ,
.Nm ieee80211_find_node ,
.Nm ieee80211_free_node ,
.\" .Nm ieee80211_free_allnodes ,
.Nm ieee80211_iterate_nodes
.Nd software 802.11 stack node management functions
.Sh SYNOPSIS
.In netproto/802_11/ieee80211_var.h
.In netproto/802_11/ieee80211_proto.h
.In netproto/802_11/ieee80211_node.h
.\" .Ft void
.\" .Fn ieee80211_node_attach "struct ieee80211com *ic"
.\" .Ft void
.\" .Fn ieee80211_node_lateattach "struct ieee80211com *ic"
.\" .Ft void
.\" .Fn ieee80211_node_detach "struct ieee80211com *ic"
.Ft void
.Fn ieee80211_begin_scan "struct ieee80211com *ic" "int reset"
.Ft void
.Fo ieee80211_create_ibss
.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan"
.Fc
.Ft int
.Fn ieee80211_next_scan "struct ieee80211com *ic"
.Ft void
.Fn ieee80211_end_scan "struct ieee80211com *ic"
.\" .Ft struct ieee80211_node *
.\" .Fo ieee80211_alloc_node
.\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
.\" .Fc
.\" .Ft struct ieee80211_node *
.\" .Fo ieee80211_dup_bss
.\" .Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
.\" .Fc
.Ft struct ieee80211_node *
.Fn ieee80211_find_txnode "struct ieee80211com *ic" "const uint8_t *macaddr"
.Ft struct ieee80211_node *
.Fo ieee80211_find_rxnode
.Fa "struct ieee80211com *ic" "const struct ieee80211_frame_min *wh"
.Fc
.Ft struct ieee80211_node *
.Fo ieee80211_find_node
.Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr"
.Fc
.Ft void
.Fn ieee80211_free_node "struct ieee80211_node *ni"
.\" .Ft void
.\" .Fn ieee80211_free_allnodes "struct ieee80211_node_table *nt"
.Ft void
.Fo ieee80211_iterate_nodes
.Fa "struct ieee80211_node_table *nt" "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,
implementing transmission rate control algorithms,
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 databases management callbacks and control variables
.\" for the interface
.\" .Fa ic
.\" (specifically for memory allocation,
.\" node copying,
.\" node signal inspection, and station inactivity timer).
.\" .Pp
.\"
.\" The
.\" .Fn ieee80211_node_lateattach
.\" function initialises the
.\" node databases,
.\" crypto and authentication settings of
.\" .Va ic_bss
.\" associated with the interface
.\" .Fa ic
.\" during
.\" .Xr ieee80211_media_init 9 .
.\" .Pp
.\"
.\" The
.\" .Fn ieee80211_node_detach
.\" function destroys all node databases associated with the interface
.\" .Fa ic .
.\" .Pp
.\"
The
.Fn ieee80211_begin_scan
function initialises the node databases in preparation of an active
scan for an access point on the interface
.Fa ic .
The scan begins on the next radio channel by calling
.Fn ieee80211_next_scan
internally.
If
.Fa reset
is non-zero, the interface
.Fa ic Ap s
node table
.Va ic_scan ,
which holds previously detected access points,
will be cleared.
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_create_ibss
function sets up the net80211-specific portion of an interface's softc
.Fa ic ,
for use in IBSS mode or HOSTAP mode.
.Pp
.\"
The
.Fn ieee80211_next_scan
function is used to inform the
.Xr ieee80211 9
layer that the interface
.Fa ic
is now scanning for an access point on the next radio channel.
.\" XXX should call ieee80211_new_state(ic, IEEE80211_S_SCAN)
.\" XXX we may need a manpage to describe ieee80211_new_state()
.\" 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_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 table
.Va ic_scan
of the interface
.Fa ic
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 node table
.\" .Fa nt .
.\" 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 node table
.\" .Fa nt .
.\" 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_txnode
function will locate a suitable node entry for a frame to be delivered to
.Fa macaddr
through the interface
.Fa ic .
.Pp
.\"
The
.Fn ieee80211_find_rxnode
function will find the node entry which represents the sender of
.Fa wh ,
which is received on the interface
.Fa ic .
.Pp
.\"
The
.Fn ieee80211_find_node
function will iterate through the node table
.Fa nt ,
searching for a node entry which matches
.Fa macaddr .
.Pp
.\"
If
.Fn ieee80211_find_txnode ,
.Fn ieee80211_find_rxnode ,
or
.Fn ieee80211_find_node ,
returns a non-NULL node entry,
the node entry's reference count is incremented,
so the caller of these functions is responsible to call
.Fn ieee80211_free_node .
.Pp
.\"
The
.Fn ieee80211_free_node
function will decrement the reference count of the node
.Fa ni .
If either the reference count drops to zero or
the last reference left is from
.Va nt_keyixmap
then
.Fa ni
will be removed from the node table where it resides,
and any memory associated with the node will be freed.
.Pp
.\"
.\" The
.\" .Fn ieee80211_free_allnodes
.\" function will iterate through the node table
.\" .Fa nt ,
.\" either calling
.\" .Fn ieee80211_free_node
.\" for all nodes that reside in
.\" .Fa nt
.\" or just remove them from
.\" .Fa nt .
.\" .Pp
.\"
The
.Fn ieee80211_iterate_nodes
function will call the user-defined callback function
.Fa f
for all nodes in the node table
.Fa nt .
The callback is invoked with the user-supplied value
.Fa arg
and a pointer to the current node.
.\"
.Sh RETURN VALUES
The function
.Fn ieee80211_next_scan
returns 0,
if a full cycle of scanning on all available radio channels is done.
Otherwise, 1 is returned.
.Pp
.\"
The fucntion
.Fn ieee80211_find_txnode
returns a node entry that is suitable to be used to send a frame to
.Fa macaddr .
If there is no suitable node found,
.Dv NULL
is returned.
.Pp
.\"
The function
.Fn ieee80211_find_rxnode
returns a node entry that represents the sender of
.Fa wh .
If no suitable node entry can be found,
.Va ic_bss
is returned.
.Pp
.\"
The function
.Fn ieee80211_find_node
returns a pointer to the node entry which matches
.Fa macaddr .
If no match is found,
.Dv NULL
is returned.
.\"
.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 man page was written by
.An Bruce M. Simpson Aq bms@FreeBSD.org
and
.An Darron Broad Aq darron@kewl.org .