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