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 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
  55 The
  56 .Nm net80211
  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
  64 operate on.
  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
  68 .Nm net80211
  69 layer to a driver; this is described more below.
  70 .Pp
  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
  78 interrupts firing.
  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
  88 .Dv IEEE80211_S_SCAN
  89 after selecting a BSS, but may also be reached from
  90 .Dv IEEE80211_S_ASSOC
  91 or
  92 .Dv IEEE80211_S_RUN
  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
  97 .Dv IEEE80211_S_AUTH
  98 after successfully authenticating or from
  99 .Dv IEEE80211_S_RUN
 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
 106 Operational.
 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
 110 .Dq port
 111 is authorized.
 112 When WPA/802.11i/802.1x is operational authorization may happen separately;
 113 e.g. in station mode
 114 .Xr wpa_supplicant 8
 115 must complete the handshakes and plumb the necessary keys before a port
 116 is authorized.
 117 In this state a BSS is operational and associated state is valid and may
 118 be used; e.g.
 119 .Vt ic_bss
 120 and
 121 .Vt ic_bsschan
 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
 126 .Dv IEEE80211_S_RUN
 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
 133 .Dv IEEE80211_S_RUN
 134 when power save operation is enabled and the local station is deemed
 135 sufficiently idle to enter low power mode.
 136 .El
 137 .Pp
 138 Note that states are ordered (as shown above);
 139 e.g. a vap must be in the
 140 .Dv IEEE80211_S_RUN
 141 or
 142 .Dq greater
 143 before it can transmit frames.
 144 Certain
 145 .Nm net80211
 146 data are valid only in certain states; e.g. the
 147 .Vt iv_bsschan
 148 that specifies the channel for the operating BSS should never be used
 149 except in
 150 .Dv IEEE80211_S_RUN
 151 or greater.
 152 .Sh STATE CHANGES
 153 State machine changes are typically handled internal to the
 154 .Nm net80211
 155 layer in response to
 156 .Xr ioctl 2
 157 requests, received frames, or external events such as a beacon miss.
 158 The
 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
 164 request a change to
 165 .Dv IEEE80211_S_SCAN
 166 the first will be permitted to run and the others will be
 167 .Em deferred
 168 until the scan operation completes at which time the selected channel
 169 will be adopted.
 170 Similarly
 171 .Nm net80211
 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
 176 .Dv IEEE80211_S_CAC
 177 and
 178 .Dv IEEE80211_S_CSA .
 179 No more than one vap can ever be actively changing state at a time.
 180 In fact
 181 .Nm net80211
 182 single-threads the state machine logic in a dedicated
 183 .Xr taskqueue 9
 184 thread that is also used to synchronize work such as scanning and
 185 beacon miss handling.
 186 .Pp
 187 After multi-vap scheduling/coordination is done the per-vap
 188 .Vt iv_newstate
 189 method is called to carry out the state change work.
 190 Drivers use this entry to setup private state and then dispatch
 191 the call to the
 192 .Nm net80211
 193 layer using the previously defined method pointer (in OOP-parlance they
 194 call the
 195 .Dq super method
 196 ).
 197 .Pp
 198 .Nm net80211
 199 handles two state changes specially.
 200 On transition to
 201 .Dv IEEE80211_S_RUN
 202 the
 203 .Dv IFF_DRV_OACTIVE
 204 bit on the vap's transmit queue is cleared so traffic can flow.
 205 On transition to
 206 .Dv IEEE80211_S_INIT
 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
 211 .Vt iv_newstate
 212 method to interpose their own code and handle setup work required
 213 by state changes.
 214 Otherwise drivers must call
 215 .Fn ieee80211_start_all
 216 in response to being marked up through an
 217 .Dv SIOCSIFFLAGS
 218 ioctl request and they should use
 219 .Fn ieee80211_suspend_all
 220 and
 221 .Fn ieee80211_resume_all
 222 to implement suspend/resume support.
 223 .Pp
 224 There is also an
 225 .Fn ieee80211_stop_all
 226 call to force all vaps to an
 227 .Dv IEEE80211_S_INIT
 228 state but this should not be needed by a driver; control is usually
 229 handled by
 230 .Nm net80211
 231 or, in the case of card eject or vap destroy,
 232 work 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
 240 The state machine concept was part of the original
 241 .Nm ieee80211
 242 code base that first appeared in
 243 .Nx 1.5 ,