FreeBSD manual
download PDF document: ieee80211_ref_node.9.pdf
IEEE80211_NODE(9) FreeBSD 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
database 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 associated 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
increment/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.
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
implement 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-
private 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
example:
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 */
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
normal 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)
FreeBSD 14.0-RELEASE-p11 April 28, 2010 FreeBSD 14.0-RELEASE-p11