1.\" 2.\" Copyright (c) 2009 Sam Leffler, Errno Consulting 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd August 4, 2009 27.Dt IEEE80211_PROTO 9 28.Os 29.Sh NAME 30.Nm ieee80211_proto 31.Nd 802.11 state machine support 32.Sh SYNOPSIS 33.In net80211/ieee80211_var.h 34.Pp 35.Ft void 36.Fn ieee80211_start_all "struct ieee80211com *" 37.Ft void 38.Fn ieee80211_stop_all "struct ieee80211com *" 39.Ft void 40.Fn ieee80211_suspend_all "struct ieee80211com *" 41.Ft void 42.Fn ieee80211_resume_all "struct ieee80211com *" 43.Pp 44.Dv enum ieee80211_state ; 45.Ft int 46.Fn ieee80211_new_state "struct ieee80211vap *" "enum ieee80211_state" "int" 47.Pp 48.Ft void 49.Fn ieee80211_wait_for_parent "struct ieee80211com *" 50.Sh DESCRIPTION 51The 52.Nm net80211 53layer that supports 802.11 device drivers uses a state machine 54to control operation of vaps. 55These state machines vary according to the vap operating mode. 56Station mode state machines follow the 802.11 MLME states 57in the protocol specification. 58Other state machines are simpler and reflect operational work 59such as scanning for a BSS or automatically selecting a channel to 60operate on. 61When multiple vaps are operational the state machines are used to 62coordinate operation such as choosing a channel. 63The state machine mechanism also serves to bind the 64.Nm net80211 65layer to a driver; this is described more below. 66.Pp 67The following states are defined for state machines: 68.Bl -tag -width IEEE80211_S_ASSOC 69.It Dv IEEE80211_S_INIT 70Default/initial state. 71A vap in this state should not hold any dynamic state (e.g. entries 72for associated stations in the node table). 73The driver must quiesce the hardware; e.g. there should be no 74interrupts firing. 75.It Dv IEEE80211_S_SCAN 76Scanning for a BSS or choosing a channel to operate on. 77Note that scanning can also take place in other states (e.g. when 78background scanning is active); this state is entered when 79initially bringing a vap to an operational state or after an 80event such as a beacon miss (in station mode). 81.It Dv IEEE80211_S_AUTH 82Authenticating to an access point (in station mode). 83This state is normally reached from 84.Dv IEEE80211_S_SCAN 85after selecting a BSS, but may also be reached from 86.Dv IEEE80211_S_ASSOC 87or 88.Dv IEEE80211_S_RUN 89if the authentication handshake fails. 90.It Dv IEEE80211_S_ASSOC 91Associating to an access point (in station mode). 92This state is reached from 93.Dv IEEE80211_S_AUTH 94after successfully authenticating or from 95.Dv IEEE80211_S_RUN 96if a DisAssoc frame is received. 97.It Dv IEEE80211_S_CAC 98Doing Channel Availability Check (CAC). 99This state is entered only when DFS is enabled and the channel selected 100for operation requires CAC. 101.It Dv IEEE80211_S_RUN 102Operational. 103In this state a vap can transmit data frames, accept requests for 104stations associating, etc. 105Beware that data traffic is also gated by whether the associated 106.Dq port 107is authorized. 108When WPA/802.11i/802.1x is operational authorization may happen separately; 109e.g. in station mode 110.Xr wpa_supplicant 8 111must complete the handshakes and plumb the necessary keys before a port 112is authorized. 113In this state a BSS is operational and associated state is valid and may 114be used; e.g. 115.Vt ic_bss 116and 117.Vt ic_bsschan 118are guaranteed to be usable. 119.It Dv IEEE80211_S_CSA 120Channel Switch Announcement (CSA) is pending. 121This state is reached only from 122.Dv IEEE80211_S_RUN 123when either a CSA is received from an access point (in station mode) 124or the local station is preparing to change channel. 125In this state traffic may be muted depending on the Mute setting in the CSA. 126.It Dv IEEE80211_S_SLEEP 127Asleep to save power (in station mode). 128This state is reached only from 129.Dv IEEE80211_S_RUN 130when power save operation is enabled and the local station is deemed 131sufficiently idle to enter low power mode. 132.El 133.Pp 134Note that states are ordered (as shown above); 135e.g. a vap must be in the 136.Dv IEEE80211_S_RUN 137or 138.Dq greater 139before it can transmit frames. 140Certain 141.Nm net80211 142data are valid only in certain states; e.g. the 143.Vt iv_bsschan 144that specifies the channel for the operating BSS should never be used 145except in 146.Dv IEEE80211_S_RUN 147or greater. 148.Sh STATE CHANGES 149State machine changes are typically handled internal to the 150.Nm net80211 151layer in response to 152.Xr ioctl 2 153requests, received frames, or external events such as a beacon miss. 154The 155.Fn ieee80211_new_state 156function is used to initiate a state machine change on a vap. 157The new state and an optional argument are supplied. 158The request is initially processed to handle coordination of multiple vaps. 159For example, only one vap at a time can be scanning, if multiple vaps 160request a change to 161.Dv IEEE80211_S_SCAN 162the first will be permitted to run and the others will be 163.Em deferred 164until the scan operation completes at which time the selected channel 165will be adopted. 166Similarly 167.Nm net80211 168handles coordination of combinations of vaps such as an AP and station vap 169where the station may need to roam to follow the AP it is associated to 170(dragging along the AP vap to the new channel). 171Another important coordination is the handling of 172.Dv IEEE80211_S_CAC 173and 174.Dv IEEE80211_S_CSA . 175No more than one vap can ever be actively changing state at a time. 176In fact 177.Nm net80211 178single-threads the state machine logic in a dedicated 179.Xr taskqueue 9 180thread that is also used to synchronize work such as scanning and 181beacon miss handling. 182.Pp 183After multi-vap scheduling/coordination is done the per-vap 184.Vt iv_newstate 185method is called to carry out the state change work. 186Drivers use this entry to setup private state and then dispatch 187the call to the 188.Nm net80211 189layer using the previously defined method pointer (in OOP-parlance they 190call the 191.Dq super method 192). 193.Pp 194.Nm net80211 195handles two state changes specially. 196On transition to 197.Dv IEEE80211_S_RUN 198the 199.Dv IFF_DRV_OACTIVE 200bit on the vap's transmit queue is cleared so traffic can flow. 201On transition to 202.Dv IEEE80211_S_INIT 203any state in the scan cache associated with the vap is flushed 204and any frames pending on the transmit queue are flushed. 205.Sh DRIVER INTEGRATION 206Drivers are expected to override the 207.Vt iv_newstate 208method to interpose their own code and handle setup work required 209by state changes. 210Otherwise drivers must call 211.Fn ieee80211_start_all 212in response to being marked up through an 213.Dv SIOCSIFFLAGS 214ioctl request and they should use 215.Fn ieee80211_suspend_all 216and 217.Fn ieee80211_resume_all 218to implement suspend/resume support. 219.Pp 220There is also an 221.Fn ieee80211_stop_all 222call to force all vaps to an 223.Dv IEEE80211_S_INIT 224state but this should not be needed by a driver; control is usually 225handled by 226.Nm net80211 227or, in the case of card eject or vap destroy, 228work will be initiated outside the driver. 229.Sh SEE ALSO 230.Xr ioctl 2 , 231.Xr wpa_supplicant 8 , 232.Xr ieee80211 9 , 233.Xr ifnet 9 , 234.Xr taskqueue 9 235.Sh HISTORY 236The state machine concept was part of the original 237.Nm ieee80211 238code base that first appeared in 239.Nx 1.5 . 240