|Kernel Developer's Manual
ieee80211com *ic, const
DESCRIPTION¶IEEE 802.11 device drivers are written to use the infrastructure provided by the
IEEE80211 software layer. This software provides a
support framework for drivers that includes ifnet cloning, state management,
and a user management API by which applications interact with 802.11 devices.
Most drivers depend on the
IEEE80211 layer for
protocol services but devices that off-load functionality may bypass the layer
to connect directly to the device (e.g. the ndis(4)
emulation support does this).
IEEE80211 device driver implements a
virtual radio API that is exported to users through network interfaces (aka
vaps) that are cloned from the underlying device. These interfaces have an
operating mode (station, adhoc, hostap, wds, monitor, etc.) that is fixed
for the lifetime of the interface. Devices that can support multiple
concurrent interfaces allow multiple vaps to be cloned. This enables
construction of interesting applications such as an AP vap and one or more
WDS vaps or multiple AP vaps, each with a different security model. The
IEEE80211 layer virtualizes most 802.11 state and
coordinates vap state changes including scheduling multiple vaps. State that
is not virtualized includes the current channel and WME/WMM parameters.
Protocol processing is typically handled entirely in the
IEEE80211 layer with drivers responsible purely for
moving data between the host and device. Similarly,
IEEE80211 handles most ioctl(2)
requests without entering the driver; instead drivers are notified of state
changes that require their involvement.
The virtual radio interface defined by the
IEEE80211 layer means that drivers must be
structured to follow specific rules. Drivers that support only a single
interface at any time must still follow these rules.
DATA STRUCTURES¶The virtual radio architecture splits state between a single per-device ieee80211com structure and one or more ieee80211vap structures. Drivers are expected to setup various shared state in these structures at device attach and during vap creation but otherwise should treat them as read-only. The ieee80211com structure is allocated by the
IEEE80211 layer as adjunct data to a device's
ifnet; it is accessed through the
if_l2com structure member. The
ieee80211vap structure is allocated by the driver in the
“vap create” method and should be extended with any
driver-private state. This technique of giving the driver control to allocate
data structures is used for other
structures and should be exploited to maintain driver-private state together
The other main data structures are the station, or node, table that tracks peers in the local BSS, and the channel table that defines the current set of available radio channels. Both tables are bound to the ieee80211com structure and shared by all vaps. Long-lasting references to a node are counted to guard against premature reclamation. In particular every packet sent/received holds a node reference (either explicitly for transmit or implicitly on receive).
The ieee80211com and
ieee80211vap structures also hold a collection of
method pointers that drivers fill-in and/or override to take control of
certain operations. These methods are the primary way drivers are bound to
IEEE80211 layer and are described below.
DRIVER ATTACH/DETACH¶Drivers attach to the
IEEE80211 layer with the
ieee80211_ifattach() function. The driver is expected
to allocate and setup any device-private data structures before passing
control. The ieee80211com structure must be
pre-initialized with state required to setup the
- Backpointer to the physical device's ifnet.
- Device/driver capabilities; see below for a complete description.
- Table of channels the device is capable of operating on. This is initially provided by the driver but may be changed through calls that change the regulatory state.
- Number of entries in
On return from
driver is expected to override default callback functions in the
ieee80211com structure to register it's private
routines. Methods marked with a “*” must be provided by the
- Create a vap instance of the specified type (operating mode). Any fixed BSSID and/or MAC address is provided. Drivers that support multi-bssid operation may honor the requested BSSID or assign their own.
- Destroy a vap instance created with
- Return the list of calibrated channels for the radio. The default method returns the current list of channels (space permitting).
- Process a request to change regulatory state. The routine may reject a request or constrain changes (e.g. reduce transmit power caps). The default method accepts all proposed changes.
- Send an 802.11 management frame. The default method fabricates the frame
IEEE80211state and passes it to the driver through the
- Transmit a raw 802.11 frame. The default method drops the frame and generates a message on the console.
- Update hardware state after an 802.11 IFS slot time change. There is no default method; the pointer may be NULL in which case it will not be used.
- Update hardware for a change in the multicast packet filter. The default method prints a console message.
- Update hardware for a change in the promiscuous mode setting. The default method prints a console message.
- Update driver/device state for association to a new AP (in station mode) or when a new station associates (e.g. in AP mode). There is no default method; the pointer may be NULL in which case it will not be used.
- Allocate and initialize a ieee80211_node structure.
This method cannot sleep. The default method allocates zero'd memory using
malloc(9). Drivers should override this method to
allocate extended storage for their own needs. Memory allocated by the
driver must be tagged with
M_80211_NODEto balance the memory allocation statistics.
- Reclaim storage of a node allocated by
ic_node_alloc. Drivers are expected to interpose their own method to cleanup private state but must call through this method to allow
IEEE80211to reclaim it's private state.
- Cleanup state in a ieee80211_node created by
ic_node_alloc. This operation is distinguished from
ic_node_freein that it may be called long before the node is actually reclaimed to cleanup adjunct state. This can happen, for example, when a node must not be reclaimed due to references held by packets in the transmit queue. Drivers typically interpose
- Age, and potentially reclaim, resources associated with a node. The default method ages frames on the power-save queue (in AP mode) and pending frames in the receive reorder queues (for stations using A-MPDU).
- Reclaim all optional resources associated with a node. This call is used to free up resources when they are in short supply.
- Return the Receive Signal Strength Indication (RSSI) in .5 dBm units for
the specified node. This interface returns a subset of the information
ic_node_getsignal. The default method calculates a filtered average over the last ten samples passed in to ieee80211_input(9) or ieee80211_input_all(9).
- Return the RSSI and noise floor (in .5 dBm units) for a station. The default method calculates RSSI as described above; the noise floor returned is the last value supplied to ieee80211_input(9) or ieee80211_input_all(9).
- Return MIMO radio state for a station in support of the
IEEE80211_IOC_STA_INFOioctl request. The default method returns nothing.
- Prepare driver/hardware state for scanning. This callback is done in a sleepable context.
- Restore driver/hardware state after scanning completes. This callback is done in a sleepable context.
- Set the current radio channel using ic_curchan. This callback is done in a sleepable context.
- Start scanning on a channel. This method is called immediately after each channel change and must initiate the work to scan a channel and schedule a timer to advance to the next channel in the scan list. This callback is done in a sleepable context. The default method handles active scan work (e.g. sending ProbeRequest frames), and schedules a call to ieee80211_scan_next(9) according to the maximum dwell time for the channel. Drivers that off-load scan work to firmware typically use this method to trigger per-channel scan activity.
- Handle reaching the minimum dwell time on a channel when scanning. This event is triggered when one or more stations have been found on a channel and the minimum dwell time has been reached. This callback is done in a sleepable context. The default method signals the scan machinery to advance to the next channel as soon as possible. Drivers can use this method to preempt further work (e.g. if scanning is handled by firmware) or ignore the request to force maximum dwell time on a channel.
- Process a received Action frame. The default method points to ieee80211_recv_action(9) which provides a mechanism for setting up handlers for each Action frame class.
- Transmit an Action frame. The default method points to ieee80211_send_action(9) which provides a mechanism for setting up handlers for each Action frame class.
- Check if transmit A-MPDU should be enabled for the specified station and AC. The default method checks a per-AC traffic rate against a per-vap threshold to decide if A-MPDU should be enabled. This method also rate-limits ADDBA requests so that requests are not made too frequently when a receiver has limited resources.
- Request A-MPDU transmit aggregation. The default method sets up local state and issues an ADDBA Request Action frame. Drivers may interpose this method if they need to setup private state for handling transmit A-MPDU.
- Process a received ADDBA Response Action frame and setup resources as needed for doing transmit A-MPDU.
- Shutdown an A-MPDU transmit stream for the specified station and AC. The default method reclaims local state after sending a DelBA Action frame.
- Process a response to a transmitted BAR control frame.
- Prepare to receive A-MPDU data from the specified station for the TID.
- Terminate receipt of A-MPDU data from the specified station for the TID.
IEEE80211 layer is attached to a
driver there are two more steps typically done to complete the work:
- Setup “radiotap support” for capturing raw 802.11 packets that pass through the device. This is done with a call to ieee80211_radiotap_attach(9).
- Do any final device setup like enabling interrupts.
State is torn down and reclaimed with a call to
ieee80211_ifdetach(). Note this call may result in
multiple callbacks into the driver so it should be done before any critical
driver state is reclaimed. On return from
ieee80211_ifdetach() all associated vaps and ifnet
structures are reclaimed or inaccessible to user applications so it is safe
to teardown driver state without worry about being re-entered. The driver is
responsible for calling if_free(9) on the ifnet it
allocated for the physical device.
DRIVER CAPABILITIES¶Driver/device capabilities are specified using several sets of flags in the ieee80211com structure. General capabilities are specified by ic_caps. Hardware cryptographic capabilities are specified by ic_cryptocaps. 802.11n capabilities, if any, are specified by ic_htcaps. The
IEEE80211 layer propagates a subset of these
capabilities to each vap through the equivalent fields:
iv_caps, iv_cryptocaps, and
iv_htcaps. The following general capabilities are
- Device is capable of operating in station (aka Infrastructure) mode.
- Device requires 802.3-encapsulated frames be passed for transmit. By
IEEE80211will encapsulate all outbound frames as 802.11 frames (without a PLCP header).
- Device supports Atheros Fast-Frames.
- Device supports Atheros Dynamic Turbo mode.
- Device is capable of operating in adhoc/IBSS mode.
- Device supports dynamic power-management (aka power save) in station mode.
- Device is capable of operating as an Access Point in Infrastructure mode.
- Device is capable of operating in Adhoc Demo mode. In this mode the device is used purely to send/receive raw 802.11 frames.
- Device supports software retry of transmitted frames.
- Device support dynamic transmit power changes on transmitted frames; also known as Transmit Power Control (TPC).
- Device supports short slot time operation (for 802.11g).
- Device supports short preamble operation (for 802.11g).
- Device is capable of operating in monitor mode.
- Device supports radar detection and/or DFS. DFS protocol support can be
IEEE80211but the device must be capable of detecting radar events.
- Device is capable of operating in MeshBSS (MBSS) mode (as defined by 802.11s Draft 3.0).
- Device supports WPA1 operation.
- Device supports WPA2/802.11i operation.
- Device supports frame bursting.
- Device supports WME/WMM operation (at the moment this is mostly support for sending and receiving QoS frames with EDCF).
- Device supports transmit/receive of 4-address frames.
- Device supports background scanning.
- Device supports transmit of fragmented 802.11 frames.
- Device is capable of operating in TDMA mode.
The follow general crypto capabilities are defined. In general
IEEE80211 will fall-back to software support when a
device is not capable of hardware acceleration of a cipher. This can be done
on a per-key basis.
IEEE80211 can also handle
Michael calculation combined with hardware
- Device supports hardware WEP cipher.
- Device supports hardware TKIP cipher.
- Device supports hardware AES-OCB cipher.
- Device supports hardware AES-CCM cipher.
- Device supports hardware Michael for use with TKIP.
- Devices supports hardware CKIP cipher.
The follow general 802.11n capabilities are defined. The first
capabilities are defined exactly as they appear in the 802.11n
specification. Capabilities beginning with IEEE80211_HTC_AMPDU are used
solely by the
- Device supports 20/40 channel width operation.
- Device supports dynamic SM power save operation.
- Device supports static SM power save operation.
- Device supports Greenfield preamble.
- Device supports Short Guard Interval on 20MHz channels.
- Device supports Short Guard Interval on 40MHz channels.
- Device supports Space Time Block Convolution (STBC) for transmit.
- Device supports 1 spatial stream for STBC receive.
- Device supports 1-2 spatial streams for STBC receive.
- Device supports 1-3 spatial streams for STBC receive.
- Device supports A-MSDU frames up to 7935 octets.
- Device supports A-MSDU frames up to 3839 octets.
- Device supports use of DSSS/CCK on 40MHz channels.
- Device supports PSMP.
- Device is intolerant of 40MHz wide channel use.
- Device supports L-SIG TXOP protection.
- Device supports A-MPDU aggregation. Note that any 802.11n compliant device must support A-MPDU receive so this implicitly means support for transmit of A-MPDU frames.
- Device supports A-MSDU aggregation. Note that any 802.11n compliant device must support A-MSDU receive so this implicitly means support for transmit of A-MSDU frames.
- Device supports High Throughput (HT) operation. This capability must be
set to enable 802.11n functionality in
- Device supports MIMO Power Save operation.
- Device supports Reduced Inter Frame Spacing (RIFS).
SEE ALSO¶ioctl(2), ndis(4), ieee80211_amrr(9), ieee80211_beacon(9), ieee80211_bmiss(9), ieee80211_crypto(9), ieee80211_ddb(9), ieee80211_input(9), ieee80211_node(9), ieee80211_output(9), ieee80211_proto(9), ieee80211_radiotap(9), ieee80211_regdomain(9), ieee80211_scan(9), ieee80211_vap(9), ifnet(9), malloc(9)
|April 28, 2010