mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-22 02:37:15 +00:00
![Bjoern A. Zeeb](/assets/img/avatar_default.png)
ieee80211_unref_node() was only used in two error cases in ieee80211_send_nulldata(). There we do not need to guard against ni pointer reuse after decrementing the refcount of the ni as we only update the stats and return. Update the man page and remove the link for the now gone function. Sponsored by: The FreeBSD Foundation X-MFC: never Reviewed by: adrian, emaste Differential Revision: https://reviews.freebsd.org/D42035
243 lines
7.9 KiB
Groff
243 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.
|
|
.\"
|
|
.Dd October 2, 2023
|
|
.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
|
|
.\"
|
|
.Ft struct ieee80211_node *
|
|
.Fo ieee80211_find_rxnode
|
|
.Fa "struct ieee80211com *"
|
|
.Fa "const struct ieee80211_frame_min *"
|
|
.Fc
|
|
.\"
|
|
.Ft struct ieee80211_node *
|
|
.Fo ieee80211_find_rxnode_withkey
|
|
.Fa "struct ieee80211com *"
|
|
.Fa "const struct ieee80211_frame_min *"
|
|
.Fa "ieee80211_keyix"
|
|
.Fc
|
|
.\"
|
|
.Ft struct ieee80211_node *
|
|
.Fn ieee80211_ref_node "struct ieee80211_node *"
|
|
.\"
|
|
.Ft void
|
|
.Fn ieee80211_free_node "struct ieee80211_node *"
|
|
.\"
|
|
.Ft void
|
|
.Fo ieee80211_iterate_nodes
|
|
.Fa "struct ieee80211_node_table *"
|
|
.Fa "ieee80211_iter_func *f"
|
|
.Fa "void *arg"
|
|
.Fc
|
|
.\"
|
|
.Ft void
|
|
.Fo ieee80211_dump_nodes
|
|
.Fa "struct ieee80211_node_table *"
|
|
.Fc
|
|
.\"
|
|
.Ft void
|
|
.Fo ieee80211_dump_node
|
|
.Fa "struct ieee80211_node *"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm net80211
|
|
layer that supports 802.11 device drivers maintains a database of
|
|
peer stations called the
|
|
.Dq node table
|
|
in the
|
|
.Vt ic_sta
|
|
entry of the
|
|
.Vt 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
|
|
.Vt 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).
|
|
.Pp
|
|
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
|
|
.Dq held reference
|
|
(i.e. a pointer to a table entry with the reference count incremented).
|
|
The
|
|
.Fn ieee80211_ref_node
|
|
call explicitly increments the reference count of a node.
|
|
.Fn ieee80211_free_node
|
|
decrements the reference count of a node and if the count goes to zero
|
|
reclaims the table entry.
|
|
.Pp
|
|
The station table and its entries are exposed to drivers in several ways.
|
|
Each frame transmitted to a station includes a reference to the
|
|
associated node in the
|
|
.Vt 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
|
|
.Dq 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
|
|
.Vt iv_bss
|
|
node when handling state machine changes as important information
|
|
is maintained in the data structure.
|
|
.Pp
|
|
The node table is opaque to drivers.
|
|
Entries may be looked up using one of the pre-defined API's or the
|
|
.Fn 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
|
|
.Fn ieee80211_iterate_nodes
|
|
is single-threaded per-device
|
|
and the effort processing involved is fairly
|
|
substantial so it should be used carefully.
|
|
.Pp
|
|
Two routines are provided to print the contents of nodes to the console
|
|
for debugging:
|
|
.Fn ieee80211_dump_node
|
|
displays the contents of a single node while
|
|
.Fn ieee80211_dump_nodes
|
|
displays the contents of the specified node table.
|
|
Nodes may also be displayed using
|
|
.Xr ddb 4
|
|
with the
|
|
.Dq show node
|
|
directive and the station node table can be displayed with
|
|
.Dq show statab .
|
|
.Sh DRIVER PRIVATE STATE
|
|
Node data structures may be extended by the driver to include
|
|
driver-private state.
|
|
This is done by overriding the
|
|
.Vt ic_node_alloc
|
|
method used to allocate a node table entry.
|
|
The driver method must allocate a structure that is an extension
|
|
of the
|
|
.Vt ieee80211_node
|
|
structure.
|
|
For example the
|
|
.Xr iwi 4
|
|
driver defines a private node structure as:
|
|
.Bd -literal -offset indent
|
|
struct iwi_node {
|
|
struct ieee80211_node in_node;
|
|
int in_station;
|
|
};
|
|
.Ed
|
|
.Pp
|
|
and then provides a private allocation routine that does this:
|
|
.Bd -literal -offset indent
|
|
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;
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Note that when reclaiming a node allocated by the driver the
|
|
.Dq parent method
|
|
must be called to ensure
|
|
.Nm net80211
|
|
state is reclaimed; for example:
|
|
.Bd -literal -offset indent
|
|
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 */
|
|
}
|
|
.Ed
|
|
.Pp
|
|
Beware that care must be taken to avoid holding references that
|
|
might cause nodes from being reclaimed.
|
|
.Nm net80211
|
|
will reclaim a node when the last reference is reclaimed in
|
|
its data structures.
|
|
However if a driver holds additional references then
|
|
.Nm net80211
|
|
will not recognize this and table entries will not be reclaimed.
|
|
Such references should not be needed if the driver overrides the
|
|
.Vt ic_node_cleanup
|
|
and/or
|
|
.Vt ic_node_free
|
|
methods.
|
|
.Sh 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
|
|
.Dq 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
|
|
.Fn 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
|
|
.Dv IEEE80211_KEYIX_NONE
|
|
then a normal lookup is done without a table update.
|
|
.Sh SEE ALSO
|
|
.Xr ddb 4 ,
|
|
.Xr ieee80211 9 ,
|
|
.Xr ieee80211_proto 9
|