/share/man/man9/ieee80211_proto.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 241 lines · 241 code · 0 blank · 0 comment · 0 complexity · 9ad930bb73fbbae2d26ca05960bbb5a0 MD5 · raw file

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