266 lines
7.9 KiB
Groff
266 lines
7.9 KiB
Groff
.\"
|
|
.\" 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
|
|
.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
|
|
.Fn ieee80211_create_ibss "struct ieee80211com *ic" "struct ieee80211_channel *chan"
|
|
.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 *
|
|
.Fn ieee80211_lookup_node "struct ieee80211com *ic" "u_int8_t *macaddr" "struct ieee80211_channel *chan"
|
|
.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
|
|
.Fn ieee80211_iterate_nodes "struct ieee80211com *ic" "ieee80211_iter_func *f" "void *arg"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
collection of 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
|
|
.Dv 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
|
|
.Xr ieee80211_node_attach 9 .
|
|
.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
|
|
.Dv 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, 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, 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, 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, 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 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.
|
|
.Pp
|
|
.\"
|
|
.Sh SEE ALSO
|
|
.Xr ieee80211 9 ,
|
|
.Xr ifnet 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
series of functions first appeared in
|
|
.Nx 1.5 ,
|
|
and were later ported to
|
|
.Fx 4.6 .
|
|
.Sh AUTHORS
|
|
This man page was written by
|
|
.An Bruce M. Simpson Aq bms@FreeBSD.org
|
|
and
|
|
.An Darron Broad Aq darron@kewl.org .
|