/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$
 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 .