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