Ubuntu Manpage: ieee80211_proto — 802.11 state machine support

Provided by: freebsd-manpages_12.2-1_all

NAME

       ieee80211_proto — 802.11 state machine support

SYNOPSIS

       #include <net80211/ieee80211_var.h>

       void
       ieee80211_start_all(struct ieee80211com *);

       void
       ieee80211_stop_all(struct ieee80211com *);

       void
       ieee80211_suspend_all(struct ieee80211com *);

       void
       ieee80211_resume_all(struct ieee80211com *);

       enum ieee80211_state;

       int
       ieee80211_new_state(struct ieee80211vap *, enum ieee80211_state, int);

       void
       ieee80211_wait_for_parent(struct ieee80211com *);

DESCRIPTION

The net80211 layer that supports 802.11 device drivers uses a state machine to control operation of vaps.
These state machines vary according to the vap operating mode. Station mode state machines follow the
802.11 MLME states in the protocol specification. Other state machines are simpler and reflect
operational work such as scanning for a BSS or automatically selecting a channel to operate on. When
multiple vaps are operational the state machines are used to coordinate operation such as choosing a
channel. The state machine mechanism also serves to bind the net80211 layer to a driver; this is
described more below.

The following states are defined for state machines:

IEEE80211_S_INIT Default/initial state. A vap in this state should not hold any dynamic state (e.g.
entries for associated stations in the node table). The driver must quiesce the
hardware; e.g. there should be no interrupts firing.

IEEE80211_S_SCAN Scanning for a BSS or choosing a channel to operate on. Note that scanning can also
take place in other states (e.g. when background scanning is active); this state is
entered when initially bringing a vap to an operational state or after an event such
as a beacon miss (in station mode).

IEEE80211_S_AUTH Authenticating to an access point (in station mode). This state is normally reached
from IEEE80211_S_SCAN after selecting a BSS, but may also be reached from
IEEE80211_S_ASSOC or IEEE80211_S_RUN if the authentication handshake fails.

IEEE80211_S_ASSOC Associating to an access point (in station mode). This state is reached from
IEEE80211_S_AUTH after successfully authenticating or from IEEE80211_S_RUN if a
DisAssoc frame is received.

IEEE80211_S_CAC Doing Channel Availability Check (CAC). This state is entered only when DFS is
enabled and the channel selected for operation requires CAC.

IEEE80211_S_RUN Operational. In this state a vap can transmit data frames, accept requests for
stations associating, etc. Beware that data traffic is also gated by whether the
associated “port” is authorized. When WPA/802.11i/802.1x is operational authorization
may happen separately; e.g. in station mode wpa_supplicant(8) must complete the
handshakes and plumb the necessary keys before a port is authorized. In this state a
BSS is operational and associated state is valid and may be used; e.g. ic_bss and
ic_bsschan are guaranteed to be usable.

IEEE80211_S_CSA Channel Switch Announcement (CSA) is pending. This state is reached only from
IEEE80211_S_RUN when either a CSA is received from an access point (in station mode)
or the local station is preparing to change channel. In this state traffic may be
muted depending on the Mute setting in the CSA.

IEEE80211_S_SLEEP Asleep to save power (in station mode). This state is reached only from
IEEE80211_S_RUN when power save operation is enabled and the local station is deemed
sufficiently idle to enter low power mode.

Note that states are ordered (as shown above); e.g. a vap must be in the IEEE80211_S_RUN or “greater”
before it can transmit frames. Certain net80211 data are valid only in certain states; e.g. the
iv_bsschan that specifies the channel for the operating BSS should never be used except in
IEEE80211_S_RUN or greater.

STATE CHANGES

State machine changes are typically handled internal to the net80211 layer in response to ioctl(2)
requests, received frames, or external events such as a beacon miss. The ieee80211_new_state() function
is used to initiate a state machine change on a vap. The new state and an optional argument are
supplied. The request is initially processed to handle coordination of multiple vaps. For example, only
one vap at a time can be scanning, if multiple vaps request a change to IEEE80211_S_SCAN the first will
be permitted to run and the others will be deferred until the scan operation completes at which time the
selected channel will be adopted. Similarly net80211 handles coordination of combinations of vaps such
as an AP and station vap where the station may need to roam to follow the AP it is associated to
(dragging along the AP vap to the new channel). Another important coordination is the handling of
IEEE80211_S_CAC and IEEE80211_S_CSA. No more than one vap can ever be actively changing state at a time.
In fact net80211 single-threads the state machine logic in a dedicated taskqueue(9) thread that is also
used to synchronize work such as scanning and beacon miss handling.

After multi-vap scheduling/coordination is done the per-vap iv_newstate method is called to carry out the
state change work. Drivers use this entry to setup private state and then dispatch the call to the
net80211 layer using the previously defined method pointer (in OOP-parlance they call the “super method”
).

net80211 handles two state changes specially. On transition to IEEE80211_S_RUN the IFF_DRV_OACTIVE bit
on the vap's transmit queue is cleared so traffic can flow. On transition to IEEE80211_S_INIT any state
in the scan cache associated with the vap is flushed and any frames pending on the transmit queue are
flushed.

DRIVER INTEGRATION

       Drivers are expected to override the iv_newstate method to interpose their own code and handle setup work
       required by state changes.  Otherwise drivers must call ieee80211_start_all() in response to being marked
       up   through   an   SIOCSIFFLAGS   ioctl   request   and  they  should  use  ieee80211_suspend_all()  and
       ieee80211_resume_all() to implement suspend/resume support.

       There is also an ieee80211_stop_all() call to force all vaps to an IEEE80211_S_INIT state but this should
       not be needed by a driver; control is usually handled by net80211 or, in the case of card  eject  or  vap
       destroy, work will be initiated outside the driver.

HISTORY