69cb5ffba72cc63929bfb4432f61ec6d90aced18
[dragonfly.git] / share / man / man9 / ieee80211.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: head/share/man/man9/ieee80211.9 233648 2012-03-29 05:02:12Z eadler $
27 .\"
28 .Dd May 26, 2016
29 .Dt IEEE80211 9
30 .Os
31 .Sh NAME
32 .Nm ieee80211
33 .Nd 802.11 network layer
34 .Sh SYNOPSIS
35 .In net/if.h
36 .In net/if_media.h
37 .In netproto/802_11/ieee80211_var.h
38 .Ft void
39 .Fn ieee80211_ifattach "struct ieee80211com *ic"
40 .Ft void
41 .Fn ieee80211_ifdetach "struct ieee80211com *ic"
42 .Sh DESCRIPTION
43 IEEE 802.11 device drivers are written to use the infrastructure provided
44 by the
45 .Nm
46 software layer.
47 This software provides a support framework for drivers that includes
48 ifnet cloning, state management, and a user management API by which
49 applications interact with 802.11 devices.
50 Most drivers depend on the
51 .Nm
52 layer for protocol services but devices that off-load functionality
53 may bypass the layer to connect directly to the device
54 (e.g. the
55 .Xr ndis 4
56 emulation support does this).
57 .Pp
58 A
59 .Nm
60 device driver implements a virtual radio API that is exported to
61 users through network interfaces (aka vaps) that are cloned from the
62 underlying device.
63 These interfaces have an operating mode
64 (station, adhoc, hostap, wds, monitor, etc.)
65 that is fixed for the lifetime of the interface.
66 Devices that can support multiple concurrent interfaces allow
67 multiple vaps to be cloned.
68 This enables construction of interesting applications such as
69 an AP vap and one or more WDS vaps
70 or multiple AP vaps, each with a different security model.
71 The
72 .Nm
73 layer virtualizes most 802.11 state
74 and coordinates vap state changes including scheduling multiple vaps.
75 State that is not virtualized includes the current channel and
76 WME/WMM parameters.
77 Protocol processing is typically handled entirely in the
78 .Nm
79 layer with drivers responsible purely for moving data between the host
80 and device.
81 Similarly,
82 .Nm
83 handles most
84 .Xr ioctl 2
85 requests without entering the driver;
86 instead drivers are notified of state changes that
87 require their involvement.
88 .Pp
89 The virtual radio interface defined by the
90 .Nm
91 layer means that drivers must be structured to follow specific rules.
92 Drivers that support only a single interface at any time must still
93 follow these rules.
94 .Sh DATA STRUCTURES
95 The virtual radio architecture splits state between a single per-device
96 .Vt ieee80211com
97 structure and one or more
98 .Vt ieee80211vap
99 structures.
100 Drivers are expected to setup various shared state in these structures
101 at device attach and during vap creation but otherwise should treat them
102 as read-only.
103 The
104 .Vt ieee80211com
105 structure is allocated by the
106 .Nm
107 layer as adjunct data to a device's
108 .Vt ifnet ;
109 it is accessed through the
110 .Vt if_l2com
111 structure member.
112 The
113 .Vt ieee80211vap
114 structure is allocated by the driver in the
115 .Dq vap create
116 method
117 and should be extended with any driver-private state.
118 This technique of giving the driver control to allocate data structures
119 is used for other
120 .Nm
121 data structures and should be exploited to maintain driver-private state
122 together with public
123 .Nm
124 state.
125 .Pp
126 The other main data structures are the station, or node, table
127 that tracks peers in the local BSS, and the channel table that defines
128 the current set of available radio channels.
129 Both tables are bound to the
130 .Vt ieee80211com
131 structure and shared by all vaps.
132 Long-lasting references to a node are counted to guard against
133 premature reclamation.
134 In particular every packet sent/received holds a node reference
135 (either explicitly for transmit or implicitly on receive).
136 .Pp
137 The
138 .Vt ieee80211com
139 and
140 .Vt ieee80211vap
141 structures also hold a collection of method pointers that drivers
142 fill-in and/or override to take control of certain operations.
143 These methods are the primary way drivers are bound to the
144 .Nm
145 layer and are described below.
146 .Sh DRIVER ATTACH/DETACH
147 Drivers attach to the
148 .Nm
149 layer with the
150 .Fn ieee80211_ifattach
151 function.
152 The driver is expected to allocate and setup any device-private
153 data structures before passing control.
154 The
155 .Vt ieee80211com
156 structure must be pre-initialized with state required to setup the
157 .Nm
158 layer:
159 .Bl -tag -width ic_channels
160 .It Dv ic_ifp
161 Backpointer to the physical device's ifnet.
162 .It Dv ic_caps
163 Device/driver capabilities; see below for a complete description.
164 .It Dv ic_channels
165 Table of channels the device is capable of operating on.
166 This is initially provided by the driver but may be changed
167 through calls that change the regulatory state.
168 .It Dv ic_nchan
169 Number of entries in
170 .Dv ic_channels .
171 .El
172 .Pp
173 On return from
174 .Fn ieee80211_ifattach
175 the driver is expected to override default callback functions in the
176 .Vt ieee80211com
177 structure to register it's private routines.
178 Methods marked with a
179 .Dq *
180 must be provided by the driver.
181 .Bl -tag -width ic_channels
182 .It Dv ic_vap_create*
183 Create a vap instance of the specified type (operating mode).
184 Any fixed BSSID and/or MAC address is provided.
185 Drivers that support multi-bssid operation may honor the requested BSSID
186 or assign their own.
187 .It Dv ic_vap_delete*
188 Destroy a vap instance created with
189 .Dv ic_vap_create .
190 .It Dv ic_getradiocaps
191 Return the list of calibrated channels for the radio.
192 The default method returns the current list of channels
193 (space permitting).
194 .It Dv ic_setregdomain
195 Process a request to change regulatory state.
196 The routine may reject a request or constrain changes (e.g. reduce
197 transmit power caps).
198 The default method accepts all proposed changes.
199 .It Dv ic_send_mgmt
200 Send an 802.11 management frame.
201 The default method fabricates the frame using
202 .Nm
203 state and passes it to the driver through the
204 .Dv ic_raw_xmit
205 method.
206 .It Dv ic_raw_xmit
207 Transmit a raw 802.11 frame.
208 The default method drops the frame and generates a message on the console.
209 .It Dv ic_updateslot
210 Update hardware state after an 802.11 IFS slot time change.
211 There is no default method; the pointer may be NULL in which case
212 it will not be used.
213 .It Dv ic_update_mcast
214 Update hardware for a change in the multicast packet filter.
215 The default method prints a console message.
216 .It Dv ic_update_promisc
217 Update hardware for a change in the promiscuous mode setting.
218 The default method prints a console message.
219 .It Dv ic_newassoc
220 Update driver/device state for association to a new AP (in station mode)
221 or when a new station associates (e.g. in AP mode).
222 There is no default method; the pointer may be NULL in which case
223 it will not be used.
224 .It Dv ic_node_alloc
225 Allocate and initialize a
226 .Vt ieee80211_node
227 structure.
228 This method cannot sleep.
229 The default method allocates zero'd memory using
230 .Xr kmalloc 9 .
231 Drivers should override this method to allocate extended storage
232 for their own needs.
233 Memory allocated by the driver must be tagged with
234 .Dv M_80211_NODE
235 to balance the memory allocation statistics.
236 .It Dv ic_node_free
237 Reclaim storage of a node allocated by
238 .Dv ic_node_alloc .
239 Drivers are expected to
240 .Em interpose
241 their own method to cleanup private state but must call through
242 this method to allow
243 .Nm
244 to reclaim it's private state.
245 .It Dv ic_node_cleanup
246 Cleanup state in a
247 .Vt ieee80211_node
248 created by
249 .Dv ic_node_alloc .
250 This operation is distinguished from
251 .Dv ic_node_free
252 in that it may be called long before the node is actually reclaimed
253 to cleanup adjunct state.
254 This can happen, for example, when a node must not be reclaimed
255 due to references held by packets in the transmit queue.
256 Drivers typically interpose
257 .Dv ic_node_cleanup
258 instead of
259 .Dv ic_node_free .
260 .It Dv ic_node_age
261 Age, and potentially reclaim, resources associated with a node.
262 The default method ages frames on the power-save queue (in AP mode)
263 and pending frames in the receive reorder queues (for stations using A-MPDU).
264 .It Dv ic_node_drain
265 Reclaim all optional resources associated with a node.
266 This call is used to free up resources when they are in short supply.
267 .It Dv ic_node_getrssi
268 Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for
269 the specified node.
270 This interface returns a subset of the information
271 returned by
272 .Dv ic_node_getsignal .
273 The default method calculates a filtered average over the last ten
274 samples passed in to
275 .Xr ieee80211_input 9
276 or
277 .Xr ieee80211_input_all 9 .
278 .It Dv ic_node_getsignal
279 Return the RSSI and noise floor (in .5 dBm units) for a station.
280 The default method calculates RSSI as described above;
281 the noise floor returned is the last value supplied to
282 .Xr ieee80211_input 9
283 or
284 .Xr ieee80211_input_all 9 .
285 .It Dv ic_node_getmimoinfo
286 Return MIMO radio state for a station in support of the
287 .Dv IEEE80211_IOC_STA_INFO
288 ioctl request.
289 The default method returns nothing.
290 .It Dv ic_scan_start*
291 Prepare driver/hardware state for scanning.
292 This callback is done in a sleepable context.
293 .It Dv ic_scan_end*
294 Restore driver/hardware state after scanning completes.
295 This callback is done in a sleepable context.
296 .It Dv ic_set_channel*
297 Set the current radio channel using
298 .Vt ic_curchan .
299 This callback is done in a sleepable context.
300 .It Dv ic_scan_curchan
301 Start scanning on a channel.
302 This method is called immediately after each channel change
303 and must initiate the work to scan a channel and schedule a timer
304 to advance to the next channel in the scan list.
305 This callback is done in a sleepable context.
306 The default method handles active scan work (e.g. sending ProbeRequest
307 frames), and schedules a call to
308 .Xr ieee80211_scan_next 9
309 according to the maximum dwell time for the channel.
310 Drivers that off-load scan work to firmware typically use this method
311 to trigger per-channel scan activity.
312 .It Dv ic_scan_mindwell
313 Handle reaching the minimum dwell time on a channel when scanning.
314 This event is triggered when one or more stations have been found on
315 a channel and the minimum dwell time has been reached.
316 This callback is done in a sleepable context.
317 The default method signals the scan machinery to advance
318 to the next channel as soon as possible.
319 Drivers can use this method to preempt further work (e.g. if scanning
320 is handled by firmware) or ignore the request to force maximum dwell time
321 on a channel.
322 .It Dv ic_recv_action
323 Process a received Action frame.
324 The default method points to
325 .Fn ieee80211_recv_action
326 which provides a mechanism for setting up handlers for each Action frame class.
327 .It Dv ic_send_action
328 Transmit an Action frame.
329 The default method points to
330 .Fn ieee80211_send_action
331 which provides a mechanism for setting up handlers for each Action frame class.
332 .It Dv ic_ampdu_enable
333 Check if transmit A-MPDU should be enabled for the specified station and AC.
334 The default method checks a per-AC traffic rate against a per-vap
335 threshold to decide if A-MPDU should be enabled.
336 This method also rate-limits ADDBA requests so that requests are not
337 made too frequently when a receiver has limited resources.
338 .It Dv ic_addba_request
339 Request A-MPDU transmit aggregation.
340 The default method sets up local state and issues an
341 ADDBA Request Action frame.
342 Drivers may interpose this method if they need to setup private state
343 for handling transmit A-MPDU.
344 .It Dv ic_addb_response
345 Process a received ADDBA Response Action frame and setup resources as
346 needed for doing transmit A-MPDU.
347 .It Dv ic_addb_stop
348 Shutdown an A-MPDU transmit stream for the specified station and AC.
349 The default method reclaims local state after sending a DelBA Action frame.
350 .It Dv ic_bar_response
351 Process a response to a transmitted BAR control frame.
352 .It Dv ic_ampdu_rx_start
353 Prepare to receive A-MPDU data from the specified station for the TID.
354 .It Dv ic_ampdu_rx_stop
355 Terminate receipt of A-MPDU data from the specified station for the TID.
356 .El
357 .Pp
358 Once the
359 .Nm
360 layer is attached to a driver there are two more steps typically done
361 to complete the work:
362 .Bl -enum
363 .It
364 Setup
365 .Dq radiotap support
366 for capturing raw 802.11 packets that pass through the device.
367 This is done with a call to
368 .Xr ieee80211_radiotap_attach 9 .
369 .It
370 Do any final device setup like enabling interrupts.
371 .El
372 .Pp
373 State is torn down and reclaimed with a call to
374 .Fn ieee80211_ifdetach .
375 Note this call may result in multiple callbacks into the driver
376 so it should be done before any critical driver state is reclaimed.
377 On return from
378 .Fn ieee80211_ifdetach
379 all associated vaps and ifnet structures are reclaimed or inaccessible
380 to user applications so it is safe to teardown driver state without
381 worry about being re-entered.
382 The driver is responsible for calling
383 .Fn if_free
384 on the ifnet it allocated for the physical device.
385 .Sh DRIVER CAPABILITIES
386 Driver/device capabilities are specified using several sets of flags
387 in the
388 .Vt ieee80211com
389 structure.
390 General capabilities are specified by
391 .Vt ic_caps .
392 Hardware cryptographic capabilities are specified by
393 .Vt ic_cryptocaps .
394 802.11n capabilities, if any, are specified by
395 .Vt ic_htcaps .
396 The
397 .Nm
398 layer propagates a subset of these capabilities to each vap through
399 the equivalent fields:
400 .Vt iv_caps ,
401 .Vt iv_cryptocaps ,
402 and
403 .Vt iv_htcaps .
404 The following general capabilities are defined:
405 .Bl -tag -width IEEE80211_C_8023ENCAP
406 .It Dv IEEE80211_C_STA
407 Device is capable of operating in station (aka Infrastructure) mode.
408 .It Dv IEEE80211_C_8023ENCAP
409 Device requires 802.3-encapsulated frames be passed for transmit.
410 By default
411 .Nm
412 will encapsulate all outbound frames as 802.11 frames (without a PLCP header).
413 .It Dv IEEE80211_C_FF
414 Device supports Atheros Fast-Frames.
415 .It Dv IEEE80211_C_TURBOP
416 Device supports Atheros Dynamic Turbo mode.
417 .It Dv IEEE80211_C_IBSS
418 Device is capable of operating in adhoc/IBSS mode.
419 .It Dv IEEE80211_C_PMGT
420 Device supports dynamic power-management (aka power save) in station mode.
421 .It Dv IEEE80211_C_HOSTAP
422 Device is capable of operating as an Access Point in Infrastructure mode.
423 .It Dv IEEE80211_C_AHDEMO
424 Device is capable of operating in Adhoc Demo mode.
425 In this mode the device is used purely to send/receive raw 802.11 frames.
426 .It Dv IEEE80211_C_SWRETRY
427 Device supports software retry of transmitted frames.
428 .It Dv IEEE80211_C_TXPMGT
429 Device support dynamic transmit power changes on transmitted frames;
430 also known as Transmit Power Control (TPC).
431 .It Dv IEEE80211_C_SHSLOT
432 Device supports short slot time operation (for 802.11g).
433 .It Dv IEEE80211_C_SHPREAMBLE
434 Device supports short preamble operation (for 802.11g).
435 .It Dv IEEE80211_C_MONITOR
436 Device is capable of operating in monitor mode.
437 .It Dv IEEE80211_C_DFS
438 Device supports radar detection and/or DFS.
439 DFS protocol support can be handled by
440 .Nm
441 but the device must be capable of detecting radar events.
442 .It Dv IEEE80211_C_MBSS
443 Device is capable of operating in MeshBSS (MBSS) mode
444 (as defined by 802.11s Draft 3.0).
445 .It Dv IEEE80211_C_WPA1
446 Device supports WPA1 operation.
447 .It Dv IEEE80211_C_WPA2
448 Device supports WPA2/802.11i operation.
449 .It Dv IEEE80211_C_BURST
450 Device supports frame bursting.
451 .It Dv IEEE80211_C_WME
452 Device supports WME/WMM operation
453 (at the moment this is mostly support for sending and receiving
454 QoS frames with EDCF).
455 .It Dv IEEE80211_C_WDS
456 Device supports transmit/receive of 4-address frames.
457 .It Dv IEEE80211_C_BGSCAN
458 Device supports background scanning.
459 .It Dv IEEE80211_C_TXFRAG
460 Device supports transmit of fragmented 802.11 frames.
461 .It Dv IEEE80211_C_TDMA
462 Device is capable of operating in TDMA mode.
463 .El
464 .Pp
465 The follow general crypto capabilities are defined.
466 In general
467 .Nm
468 will fall-back to software support when a device is not capable
469 of hardware acceleration of a cipher.
470 This can be done on a per-key basis.
471 .Nm
472 can also handle software
473 .Dv Michael
474 calculation combined with hardware
475 .Dv AES
476 acceleration.
477 .Bl -tag -width IEEE80211_C_8023ENCAP
478 .It Dv IEEE80211_CRYPTO_WEP
479 Device supports hardware WEP cipher.
480 .It Dv IEEE80211_CRYPTO_TKIP
481 Device supports hardware TKIP cipher.
482 .It Dv IEEE80211_CRYPTO_AES_OCB
483 Device supports hardware AES-OCB cipher.
484 .It Dv IEEE80211_CRYPTO_AES_CCM
485 Device supports hardware AES-CCM cipher.
486 .It Dv IEEE80211_CRYPTO_TKIPMIC
487 Device supports hardware Michael for use with TKIP.
488 .It Dv IEEE80211_CRYPTO_CKIP
489 Devices supports hardware CKIP cipher.
490 .El
491 .Pp
492 The follow general 802.11n capabilities are defined.
493 The first capabilities are defined exactly as they appear in the
494 802.11n specification.
495 Capabilities beginning with IEEE80211_HTC_AMPDU are used solely by the
496 .Nm
497 layer.
498 .Bl -tag -width IEEE80211_C_8023ENCAP
499 .It Dv IEEE80211_HTCAP_CHWIDTH40
500 Device supports 20/40 channel width operation.
501 .It Dv IEEE80211_HTCAP_SMPS_DYNAMIC
502 Device supports dynamic SM power save operation.
503 .It Dv IEEE80211_HTCAP_SMPS_ENA
504 Device supports static SM power save operation.
505 .It Dv IEEE80211_HTCAP_GREENFIELD
506 Device supports Greenfield preamble.
507 .It Dv IEEE80211_HTCAP_SHORTGI20
508 Device supports Short Guard Interval on 20MHz channels.
509 .It Dv IEEE80211_HTCAP_SHORTGI40
510 Device supports Short Guard Interval on 40MHz channels.
511 .It Dv IEEE80211_HTCAP_TXSTBC
512 Device supports Space Time Block Convolution (STBC) for transmit.
513 .It Dv IEEE80211_HTCAP_RXSTBC_1STREAM
514 Device supports 1 spatial stream for STBC receive.
515 .It Dv IEEE80211_HTCAP_RXSTBC_2STREAM
516 Device supports 1-2 spatial streams for STBC receive.
517 .It Dv IEEE80211_HTCAP_RXSTBC_3STREAM
518 Device supports 1-3 spatial streams for STBC receive.
519 .It Dv IEEE80211_HTCAP_MAXAMSDU_7935
520 Device supports A-MSDU frames up to 7935 octets.
521 .It Dv IEEE80211_HTCAP_MAXAMSDU_3839
522 Device supports A-MSDU frames up to 3839 octets.
523 .It Dv IEEE80211_HTCAP_DSSSCCK40
524 Device supports use of DSSS/CCK on 40MHz channels.
525 .It Dv IEEE80211_HTCAP_PSMP
526 Device supports PSMP.
527 .It Dv IEEE80211_HTCAP_40INTOLERANT
528 Device is intolerant of 40MHz wide channel use.
529 .It Dv IEEE80211_HTCAP_LSIGTXOPPROT
530 Device supports L-SIG TXOP protection.
531 .It Dv IEEE80211_HTC_AMPDU
532 Device supports A-MPDU aggregation.
533 Note that any 802.11n compliant device must support A-MPDU receive
534 so this implicitly means support for
535 .Em transmit
536 of A-MPDU frames.
537 .It Dv IEEE80211_HTC_AMSDU
538 Device supports A-MSDU aggregation.
539 Note that any 802.11n compliant device must support A-MSDU receive
540 so this implicitly means support for
541 .Em transmit
542 of A-MSDU frames.
543 .It Dv IEEE80211_HTC_HT
544 Device supports High Throughput (HT) operation.
545 This capability must be set to enable 802.11n functionality
546 in
547 .Nm .
548 .It Dv IEEE80211_HTC_SMPS
549 Device supports MIMO Power Save operation.
550 .It Dv IEEE80211_HTC_RIFS
551 Device supports Reduced Inter Frame Spacing (RIFS).
552 .El
553 .Sh SEE ALSO
554 .Xr ioctl 2 ,
555 .Xr ndis 4 ,
556 .\".Xr ieee80211_amrr 9 ,
557 .Xr ieee80211_beacon 9 ,
558 .Xr ieee80211_bmiss 9 ,
559 .Xr ieee80211_crypto 9 ,
560 .Xr ieee80211_ddb 9 ,
561 .Xr ieee80211_input 9 ,
562 .Xr ieee80211_node 9 ,
563 .Xr ieee80211_output 9 ,
564 .Xr ieee80211_proto 9 ,
565 .Xr ieee80211_radiotap 9 ,
566 .Xr ieee80211_regdomain 9 ,
567 .Xr ieee80211_scan 9 ,
568 .Xr ieee80211_vap 9 ,
569 .Xr ifnet 9 ,
570 .Xr kmalloc 9