Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IEEE80211_NODE(9)	 BSD Kernel Developer's	Manual	     IEEE80211_NODE(9)

NAME
     ieee80211_node -- software	802.11 stack node management functions

SYNOPSIS
     #include <net80211/ieee80211_var.h>

     struct ieee80211_node *
     ieee80211_find_rxnode(struct ieee80211com *,
	 const struct ieee80211_frame_min *);

     struct ieee80211_node *
     ieee80211_find_rxnode_withkey(struct ieee80211com *,
	 const struct ieee80211_frame_min *, ieee80211_keyix);

     struct ieee80211_node *
     ieee80211_ref_node(struct ieee80211_node *);

     void
     ieee80211_unref_node(struct ieee80211_node	*);

     void
     ieee80211_free_node(struct	ieee80211_node *);

     void
     ieee80211_iterate_nodes(struct ieee80211_node_table *,
	 ieee80211_iter_func *f, void *arg);

     void
     ieee80211_dump_nodes(struct ieee80211_node_table *);

     void
     ieee80211_dump_node(struct	ieee80211_node *);

DESCRIPTION
     The net80211 layer	that supports 802.11 device drivers maintains a	data-
     base of peer stations called the "node table" in the ic_sta entry of the
     ieee80211com structure.  Station mode vaps	create an entry	for the	access
     point the station is associated to.  AP mode vaps create entries for as-
     sociated stations.	 Adhoc and mesh	mode vaps create entries for neighbor
     stations.	WDS mode vaps create an	entry for the peer station.  Stations
     for all vaps reside in the	same table; each node entry has	a ni_vap field
     that identifies the vap that created it.  In some instances an entry is
     used by multiple vaps (e.g. for dynamic WDS a station associated to an ap
     vap may also be the peer of a WDS vap).

     Node table	entries	are reference counted.	That is, there is a count of
     all long term references that determines when an entry may	be reclaimed.
     References	are held by every in-flight frame sent to a station to ensure
     the entry is not reclaimed	while the frame	is queued or otherwise held by
     a driver.	Routines that lookup a table entry return a "held reference"
     (i.e. a pointer to	a table	entry with the reference count incremented).
     The ieee80211_ref_node() and ieee80211_unref_node() calls explicitly in-
     crement/decrement the reference count of a	node, but are rarely used.
     Instead most callers use ieee80211_free_node() to release a reference
     and, if the count goes to zero, reclaim the table entry.

     The station table and its entries are exposed to drivers in several ways.
     Each frame	transmitted to a station includes a reference to the associ-
     ated node in the m_pkthdr.rcvif field.  This reference must be reclaimed
     by	the driver when	transmit processing is done.  For each frame received
     the driver	must lookup the	table entry to use in dispatching the frame
     "up the stack".  This lookup implicitly obtains a reference to the	table
     entry and the driver must reclaim the reference when frame	processing is
     completed.	 Otherwise drivers frequently inspect the contents of the
     iv_bss node when handling state machine changes as	important information
     is	maintained in the data structure.

     The node table is opaque to drivers.  Entries may be looked up using one
     of	the pre-defined	API's or the ieee80211_iterate_nodes() call may	be
     used to iterate through all entries to do per-node	processing or imple-
     ment some non-standard search mechanism.  Note that
     ieee80211_iterate_nodes() is single-threaded per-device and the effort
     processing	involved is fairly substantial so it should be used carefully.

     Two routines are provided to print	the contents of	nodes to the console
     for debugging: ieee80211_dump_node() displays the contents	of a single
     node while	ieee80211_dump_nodes() displays	the contents of	the specified
     node table.  Nodes	may also be displayed using ddb(4) with	the "show
     node" directive and the station node table	can be displayed with "show
     statab".

DRIVER PRIVATE STATE
     Node data structures may be extended by the driver	to include driver-pri-
     vate state.  This is done by overriding the ic_node_alloc method used to
     allocate a	node table entry.  The driver method must allocate a structure
     that is an	extension of the ieee80211_node	structure.  For	example	the
     iwi(4) driver defines a private node structure as:

	   struct iwi_node {
		   struct ieee80211_node   in_node;
		   int			   in_station;
	   };

     and then provides a private allocation routine that does this:

	   static struct ieee80211_node	*
	   iwi_node_alloc(struct ieee80211vap *vap,
	       const uint8_t mac[IEEE80211_ADDR_LEN])
	   {
		   struct iwi_node *in;

		   in =	malloc(sizeof(struct iwi_node),	M_80211_NODE,
			   M_NOWAIT | M_ZERO);
		   if (in == NULL)
			   return NULL;
		   in->in_station = -1;
		   return &in->in_node;
	   }

     Note that when reclaiming a node allocated	by the driver the "parent
     method" must be called to ensure net80211 state is	reclaimed; for exam-
     ple:

	   static void
	   iwi_node_free(struct	ieee80211_node *ni)
	   {
		   struct ieee80211com *ic = ni->ni_ic;
		   struct iwi_softc *sc	= ic->ic_ifp->if_softc;
		   struct iwi_node *in = (struct iwi_node *)ni;

		   if (in->in_station != -1)
			   free_unr(sc->sc_unr,	in->in_station);
		   sc->sc_node_free(ni);   /* invoke net80211 free handler */
	   }

     Beware that care must be taken to avoid holding references	that might
     cause nodes from being reclaimed.	net80211 will reclaim a	node when the
     last reference is reclaimed in its	data structures.  However if a driver
     holds additional references then net80211 will not	recognize this and ta-
     ble entries will not be reclaimed.	 Such references should	not be needed
     if	the driver overrides the ic_node_cleanup and/or	ic_node_free methods.

KEY TABLE SUPPORT
     Node table	lookups	are typically done using a hash	of the stations' mac
     address.  When receiving frames this is sufficient	to find	the node table
     entry for the transmitter.	 But some devices also identify	the sending
     station in	the device state received with each frame and this data	can be
     used to optimize lookups on receive using a companion table called	the
     "keytab".	This table records a separate node table reference that	can be
     fetched without any locking using the table index.	 This logic is handled
     with the ieee80211_find_rxnode_withkey() call: if a keytab	entry is found
     using the specified index then it is returned directly; otherwise a nor-
     mal lookup	is done	and the	keytab entry is	written	using the specified
     index.  If	the specified index is IEEE80211_KEYIX_NONE then a normal
     lookup is done without a table update.

SEE ALSO
     ddb(4), ieee80211(9), ieee80211_proto(9)

BSD				April 28, 2010				   BSD

NAME | SYNOPSIS | DESCRIPTION | DRIVER PRIVATE STATE | KEY TABLE SUPPORT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ieee80211_node&sektion=9&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help