SYNOPSIS

DESCRIPTION

IEEE 802.11 device drivers are written to use the infrastructure provided
by the net80211 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 net80211 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).
A net80211 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 net80211 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 net80211 layer with drivers responsible purely
for moving data between the host and device. Similarly, net80211 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 net80211 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.

DATASTRUCTURES

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 net80211 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 net80211 data structures and should be
exploited to maintain driver-private state together with public net80211
state.
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 the net80211 layer and are described below.

DRIVERATTACH/DETACH

Drivers attach to the net80211 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
net80211 layer:
ic_ifp Backpointer to the physical device's ifnet.
ic_caps Device/driver capabilities; see below for a complete
description.
ic_channels 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.
ic_nchan Number of entries in ic_channels.
On return from ieee80211_ifattach() the 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
driver.
ic_vap_create*
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.
ic_vap_delete*
Destroy a vap instance created with ic_vap_create.
ic_getradiocaps
Return the list of calibrated channels for the radio. The
default method returns the current list of channels (space
permitting).
ic_setregdomain
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.
ic_send_mgmt
Send an 802.11 management frame. The default method
fabricates the frame using net80211 state and passes it to
the driver through the ic_raw_xmit method.
ic_raw_xmit Transmit a raw 802.11 frame. The default method drops the
frame and generates a message on the console.
ic_updateslot
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.
ic_update_mcast
Update hardware for a change in the multicast packet filter,
The default method prints a console message.
ic_update_promisc
Update hardware for a change in the promiscuous mode
setting. The default method prints a console message.
ic_newassoc 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.
ic_node_alloc
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_NODE to
balance the memory allocation statistics.
ic_node_free
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 net80211 to reclaim it's private state.
ic_node_cleanup
Cleanup state in a ieee80211_node created by ic_node_alloc.
This operation is distinguished from ic_node_free in 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
ic_node_cleanup instead of ic_node_free.
ic_node_age 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).
ic_node_drain
Reclaim all optional resources associated with a node. This
call is used to free up resources when they are in short
supply,
ic_node_getrssi
Return the Receive Signal Strength Indication (RSSI) in .5
dBm units for the specified node. This interface returns a
subset of the information returned by 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).
ic_node_getsignal
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).
ic_node_getmimoinfo
Return MIMO radio state for a station in support of the
IEEE80211_IOC_STA_INFO ioctl request. The default method
returns nothing.
ic_scan_start*
Prepare driver/hardware state for scanning. This callback
is done in a sleepable context.
ic_scan_end*
Restore driver/hardware state after scanning completes.
This callback is done in a sleepable context.
ic_set_channel*
Set the current radio channel using ic_curchan. This
callback is done in a sleepable context.
ic_scan_curchan
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.
ic_scan_mindwell
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.
ic_recv_action
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.
ic_send_action
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.
ic_ampdu_enable
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.
ic_addba_request
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.
ic_addb_response
Process a received ADDBA Response Action frame and setup
resources as needed for doing transmit A-MPDU,
ic_addb_stop
Shutdown an A-MPDU transmit stream for the specified station
and AC. The default method reclaims local state after
sending a DelBA Action frame.
ic_bar_response
Process a response to a transmitted BAR control frame.
ic_ampdu_rx_start
Prepare to receive A-MPDU data from the specified station
for the TID.
ic_ampdu_rx_stop
Terminate receipt of A-MPDU data from the specified station
for the TID.
Once the net80211 layer is attached to a driver there are two more steps
typically done to complete the work:
1. 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).
2. 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.