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