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