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