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