--- src/share/man/man9/ieee80211_node.9 2006/05/26 19:39:40 1.2 +++ src/share/man/man9/ieee80211_node.9 2006/06/28 19:41:59 1.3 @@ -26,146 +26,159 @@ .\" .\" $FreeBSD$ .\" $DragonFly$ -.\" $Id: ieee80211_node.9,v 1.2 2006/05/26 19:39:40 swildner Exp $ +.\" $Id: ieee80211_node.9,v 1.3 2006/06/28 19:41:59 swildner Exp $ .\" -.Dd July 4, 2004 +.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_node_attach , +.\" .Nm ieee80211_node_lateattach , +.\" .Nm ieee80211_node_detach , .Nm ieee80211_begin_scan , -.Nm ieee80211_next_scan , .Nm ieee80211_create_ibss , +.Nm ieee80211_next_scan , .Nm ieee80211_end_scan , -.Nm ieee80211_alloc_node , -.Nm ieee80211_dup_bss , +.\" .Nm ieee80211_alloc_node , +.\" .Nm ieee80211_dup_bss , +.Nm ieee80211_find_txnode , +.Nm ieee80211_find_rxnode , .Nm ieee80211_find_node , -.Nm ieee80211_lookup_node , .Nm ieee80211_free_node , -.Nm ieee80211_free_allnodes , -.Nm ieee80211_timeout_nodes , +.\" .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_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" +.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 ifnet *ifp" -.Ft struct ieee80211_node * -.Fn ieee80211_alloc_node "struct ieee80211com *ic" "u_int8_t *macaddr" +.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_dup_bss "struct ieee80211com *ic" "u_int8_t *macaddr" +.Fn ieee80211_find_txnode "struct ieee80211com *ic" "const uint8_t *macaddr" .Ft struct ieee80211_node * -.Fn ieee80211_find_node "struct ieee80211com *ic" "u_int8_t *macaddr" +.Fo ieee80211_find_rxnode +.Fa "struct ieee80211com *ic" "const struct ieee80211_frame_min *wh" +.Fc .Ft struct ieee80211_node * -.Fo ieee80211_lookup_node -.Fa "struct ieee80211com *ic" "u_int8_t *macaddr" -.Fa "struct ieee80211_channel *chan" +.Fo ieee80211_find_node +.Fa "struct ieee80211_node_table *nt" "const uint8_t *macaddr" .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" +.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 ieee80211com *ic" "ieee80211_iter_func *f" "void *arg" +.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 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_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 database in preparation of an active +function initialises the node databases in preparation of an active scan for an access point on the interface -.Fa ifp . +.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 ifp +.Fa ic 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. +.\" 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 @@ -176,106 +189,149 @@ when the state machine has peformed a fu all available radio channels. Internally, .Fn ieee80211_end_scan -will inspect the node cache associated with the interface -.Fa ifp +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_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 +.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 . -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 +.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 . -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 , +function will iterate through the node table +.Fa nt , 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 +If +.Fn ieee80211_find_txnode , +.Fn ieee80211_find_rxnode , +or .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. +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 remove the 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 -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 . +will be removed from the node table where it resides, +and any memory associated with the node will be freed. .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_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 database associated with the interface -.Fa ic . -The callback is invoked with the with the user-supplied value +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