2 .\" Copyright (c) 2009 Sam Leffler, Errno Consulting
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
26 .\" $FreeBSD: head/share/man/man9/ieee80211_proto.9 235693 2012-05-20 16:43:47Z gjb $
33 .Nd 802.11 state machine support
37 .In netproto/802_11/ieee80211_var.h
40 .Fn ieee80211_start_all "struct ieee80211com *"
42 .Fn ieee80211_stop_all "struct ieee80211com *"
44 .Fn ieee80211_suspend_all "struct ieee80211com *"
46 .Fn ieee80211_resume_all "struct ieee80211com *"
48 .Dv enum ieee80211_state ;
50 .Fn ieee80211_new_state "struct ieee80211vap *" "enum ieee80211_state" "int"
53 .Fn ieee80211_waitfor_parent "struct ieee80211com *"
57 layer that supports 802.11 device drivers uses a state machine
58 to control operation of vaps.
59 These state machines vary according to the vap operating mode.
60 Station mode state machines follow the 802.11 MLME states
61 in the protocol specification.
62 Other state machines are simpler and reflect operational work
63 such as scanning for a BSS or automatically selecting a channel to
65 When multiple vaps are operational the state machines are used to
66 coordinate operation such as choosing a channel.
67 The state machine mechanism also serves to bind the
69 layer to a driver; this is described more below.
71 The following states are defined for state machines:
72 .Bl -tag -width IEEE80211_S_ASSOC
73 .It Dv IEEE80211_S_INIT
74 Default/initial state.
75 A vap in this state should not hold any dynamic state (e.g. entries
76 for associated stations in the node table).
77 The driver must quiesce the hardware; e.g. there should be no
79 .It Dv IEEE80211_S_SCAN
80 Scanning for a BSS or choosing a channel to operate on.
81 Note that scanning can also take place in other states (e.g. when
82 background scanning is active); this state is entered when
83 initially bringing a vap to an operational state or after an
84 event such as a beacon miss (in station mode).
85 .It Dv IEEE80211_S_AUTH
86 Authenticating to an access point (in station mode).
87 This state is normally reached from
89 after selecting a BSS, but may also be reached from
93 if the authentication handshake fails.
94 .It Dv IEEE80211_S_ASSOC
95 Associating to an access point (in station mode).
96 This state is reached from
98 after successfully authenticating or from
100 if a DisAssoc frame is received.
101 .It Dv IEEE80211_S_CAC
102 Doing Channel Availability Check (CAC).
103 This state is entered only when DFS is enabled and the channel selected
104 for operation requires CAC.
105 .It Dv IEEE80211_S_RUN
107 In this state a vap can transmit data frames, accept requests for
108 stations associating, etc.
109 Beware that data traffic is also gated by whether the associated
112 When WPA/802.11i/802.1x is operational authorization may happen separately;
115 must complete the handshakes and plumb the necessary keys before a port
117 In this state a BSS is operational and associated state is valid and may
122 are guaranteed to be usable.
123 .It Dv IEEE80211_S_CSA
124 Channel Switch Announcement (CSA) is pending.
125 This state is reached only from
127 when either a CSA is received from an access point (in station mode)
128 or the local station is preparing to change channel.
129 In this state traffic may be muted depending on the Mute setting in the CSA.
130 .It Dv IEEE80211_S_SLEEP
131 Asleep to save power (in station mode).
132 This state is reached only from
134 when power save operation is enabled and the local station is deemed
135 sufficiently idle to enter low power mode.
138 Note that states are ordered (as shown above);
139 e.g. a vap must be in the
143 before it can transmit frames.
146 data are valid only in certain states; e.g. the
148 that specifies the channel for the operating BSS should never be used
153 State machine changes are typically handled internal to the
157 requests, received frames, or external events such as a beacon miss.
159 .Fn ieee80211_new_state
160 function is used to initiate a state machine change on a vap.
161 The new state and an optional argument are supplied.
162 The request is initially processed to handle coordination of multiple vaps.
163 For example, only one vap at a time can be scanning, if multiple vaps
166 the first will be permitted to run and the others will be
168 until the scan operation completes at which time the selected channel
172 handles coordination of combinations of vaps such as an AP and station vap
173 where the station may need to roam to follow the AP it is associated to
174 (dragging along the AP vap to the new channel).
175 Another important coordination is the handling of
178 .Dv IEEE80211_S_CSA .
179 No more than one vap can ever be actively changing state at a time.
182 single-threads the state machine logic in a dedicated
184 thread that is also used to synchronize work such as scanning and
185 beacon miss handling.
187 After multi-vap scheduling/coordination is done the per-vap
189 method is called to carry out the state change work.
190 Drivers use this entry to setup private state and then dispatch
193 layer using the previously defined method pointer (in OOP-parlance they
199 handles two state changes specially.
204 bit on the vap's transmit queue is cleared so traffic can flow.
207 any state in the scan cache associated with the vap is flushed
208 and any frames pending on the transmit queue are flushed.
209 .Sh DRIVER INTEGRATION
210 Drivers are expected to override the
212 method to interpose their own code and handle setup work required
214 Otherwise drivers must call
215 .Fn ieee80211_start_all
216 in response to being marked up through an
218 ioctl request and they should use
219 .Fn ieee80211_suspend_all
221 .Fn ieee80211_resume_all
222 to implement suspend/resume support.
225 .Fn ieee80211_stop_all
226 call to force all vaps to an
228 state but this should not be needed by a driver; control is usually
231 or, in the case of card eject or vap destroy,
232 work will be initiated outside the driver.
235 .Xr wpa_supplicant 8 ,
240 The state machine concept was part of the original
242 code base that first appeared in