Add documentation for the ieee80211_node.c functions.

Submitted by:	Darron Broad

share/man/man9/ieee80211_node.9

@@ -27,7 +27,7 @@
 .\" $FreeBSD$
 .\" $Id: ieee80211_node.9,v 1.6 2004/03/04 12:33:27 bruce Exp $
 .\"
-.Dd March 2, 2004
+.Dd July 4, 2004
 .Dt ieee80211_node 9
 .Os
 .Sh NAME
@@ -74,6 +74,180 @@ 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