<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="mac80211-developers-guide">
<bookinfo>
<title>The mac80211 subsystem for kernel developers</title>
<authorgroup>
<author>
<firstname>Johannes</firstname>
<surname>Berg</surname>
<affiliation>
<address><email>johannes@sipsolutions.net</email></address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2007-2009</year>
<holder>Johannes Berg</holder>
</copyright>
<legalnotice>
<para>
This documentation is free software; you can redistribute
it and/or modify it under the terms of the GNU General Public
License version 2 as published by the Free Software Foundation.
</para>
<para>
This documentation is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public
License along with this documentation; if not, write to the Free
Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
MA 02111-1307 USA
</para>
<para>
For more details see the file COPYING in the source
distribution of Linux.
</para>
</legalnotice>
<abstract>
<para>
</para><para>
mac80211 is the Linux stack for 802.11 hardware that implements
only partial functionality in hard- or firmware. This document
defines the interface between mac80211 and low-level hardware
drivers.
</para>
<para>
</para><para>
If you're reading this document and not the header file itself, it will
be incomplete because not all documentation has been converted yet.
</para>
</abstract>
</bookinfo>
<toc></toc>
<!--
Generally, this document shall be ordered by increasing complexity.
It is important to note that readers should be able to read only
the first few sections to get a working driver and only advanced
usage should require reading the full document.
-->
<part>
<title>The basic mac80211 driver interface</title>
<partintro>
<para>
You should read and understand the information contained
within this part of the book while implementing a driver.
In some chapters, advanced usage is noted, that may be
skipped at first.
</para>
<para>
This part of the book only covers station and monitor mode
functionality, additional information required to implement
the other modes is covered in the second part of the book.
</para>
</partintro>
<chapter id="basics">
<title>Basic hardware handling</title>
<para>TBD</para>
<para>
This chapter shall contain information on getting a hw
struct allocated and registered with mac80211.
</para>
<para>
Since it is required to allocate rates/modes before registering
a hw struct, this chapter shall also contain information on setting
up the rate/mode structs.
</para>
<para>
Additionally, some discussion about the callbacks and
the general programming model should be in here, including
the definition of ieee80211_ops which will be referred to
a lot.
</para>
<para>
Finally, a discussion of hardware capabilities should be done
with references to other parts of the book.
</para>
<!-- intentionally multiple !F lines to get proper order -->
<refentry id="API-struct-ieee80211-hw">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_hw</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_hw</refname>
<refpurpose>
hardware information and state
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_hw {
struct ieee80211_conf conf;
struct wiphy * wiphy;
const char * rate_control_algorithm;
void * priv;
u32 flags;
unsigned int extra_tx_headroom;
int channel_change_time;
int vif_data_size;
int sta_data_size;
u16 queues;
u16 max_listen_interval;
s8 max_signal;
u8 max_rates;
u8 max_rate_tries;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>conf</term>
<listitem><para>
<structname>struct ieee80211_conf</structname>, device configuration, don't use.
</para></listitem>
</varlistentry>
<varlistentry> <term>wiphy</term>
<listitem><para>
This points to the <structname>struct wiphy</structname> allocated for this
802.11 PHY. You must fill in the <parameter>perm_addr</parameter> and <parameter>dev</parameter>
members of this structure using <function>SET_IEEE80211_DEV</function>
and <function>SET_IEEE80211_PERM_ADDR</function>. Additionally, all supported
bands (with channels, bitrates) are registered here.
</para></listitem>
</varlistentry>
<varlistentry> <term>rate_control_algorithm</term>
<listitem><para>
rate control algorithm for this hardware.
If unset (NULL), the default algorithm will be used. Must be
set before calling <function>ieee80211_register_hw</function>.
</para></listitem>
</varlistentry>
<varlistentry> <term>priv</term>
<listitem><para>
pointer to private area that was allocated for driver use
along with this structure.
</para></listitem>
</varlistentry>
<varlistentry> <term>flags</term>
<listitem><para>
hardware flags, see <structname>enum</structname> ieee80211_hw_flags.
</para></listitem>
</varlistentry>
<varlistentry> <term>extra_tx_headroom</term>
<listitem><para>
headroom to reserve in each transmit skb
for use by the driver (e.g. for transmit headers.)
</para></listitem>
</varlistentry>
<varlistentry> <term>channel_change_time</term>
<listitem><para>
time (in microseconds) it takes to change channels.
</para></listitem>
</varlistentry>
<varlistentry> <term>vif_data_size</term>
<listitem><para>
size (in bytes) of the drv_priv data area
within <structname>struct ieee80211_vif</structname>.
</para></listitem>
</varlistentry>
<varlistentry> <term>sta_data_size</term>
<listitem><para>
size (in bytes) of the drv_priv data area
within <structname>struct ieee80211_sta</structname>.
</para></listitem>
</varlistentry>
<varlistentry> <term>queues</term>
<listitem><para>
number of available hardware transmit queues for
data packets. WMM/QoS requires at least four, these
queues need to have configurable access parameters.
</para></listitem>
</varlistentry>
<varlistentry> <term>max_listen_interval</term>
<listitem><para>
max listen interval in units of beacon interval
that HW supports
</para></listitem>
</varlistentry>
<varlistentry> <term>max_signal</term>
<listitem><para>
Maximum value for signal (rssi) in RX information, used
only when <parameter>IEEE80211_HW_SIGNAL_UNSPEC</parameter> or <parameter>IEEE80211_HW_SIGNAL_DB</parameter>
</para></listitem>
</varlistentry>
<varlistentry> <term>max_rates</term>
<listitem><para>
maximum number of alternate rate retry stages
</para></listitem>
</varlistentry>
<varlistentry> <term>max_rate_tries</term>
<listitem><para>
maximum number of tries for each stage
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This structure contains the configuration and hardware
information for an 802.11 PHY.
</para>
</refsect1>
</refentry>
<refentry id="API-enum-ieee80211-hw-flags">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum ieee80211_hw_flags</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum ieee80211_hw_flags</refname>
<refpurpose>
hardware flags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum ieee80211_hw_flags {
IEEE80211_HW_RX_INCLUDES_FCS,
IEEE80211_HW_HOST_BROADCAST_PS_BUFFERING,
IEEE80211_HW_2GHZ_SHORT_SLOT_INCAPABLE,
IEEE80211_HW_2GHZ_SHORT_PREAMBLE_INCAPABLE,
IEEE80211_HW_SIGNAL_UNSPEC,
IEEE80211_HW_SIGNAL_DBM,
IEEE80211_HW_NOISE_DBM,
IEEE80211_HW_SPECTRUM_MGMT,
IEEE80211_HW_AMPDU_AGGREGATION,
IEEE80211_HW_SUPPORTS_PS,
IEEE80211_HW_PS_NULLFUNC_STACK,
IEEE80211_HW_SUPPORTS_DYNAMIC_PS,
IEEE80211_HW_MFP_CAPABLE,
IEEE80211_HW_BEACON_FILTER,
IEEE80211_HW_REPORTS_TX_ACK_STATUS
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>IEEE80211_HW_RX_INCLUDES_FCS</term>
<listitem><para>
Indicates that received frames passed to the stack include
the FCS at the end.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_HOST_BROADCAST_PS_BUFFERING</term>
<listitem><para>
Some wireless LAN chipsets buffer broadcast/multicast frames
for power saving stations in the hardware/firmware and others
rely on the host system for such buffering. This option is used
to configure the IEEE 802.11 upper layer to buffer broadcast and
multicast frames when there are power saving stations so that
the driver can fetch them with <function>ieee80211_get_buffered_bc</function>.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_2GHZ_SHORT_SLOT_INCAPABLE</term>
<listitem><para>
Hardware is not capable of short slot operation on the 2.4 GHz band.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_2GHZ_SHORT_PREAMBLE_INCAPABLE</term>
<listitem><para>
Hardware is not capable of receiving frames with short preamble on
the 2.4 GHz band.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_SIGNAL_UNSPEC</term>
<listitem><para>
Hardware can provide signal values but we don't know its units. We
expect values between 0 and <parameter>max_signal</parameter>.
If possible please provide dB or dBm instead.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_SIGNAL_DBM</term>
<listitem><para>
Hardware gives signal values in dBm, decibel difference from
one milliwatt. This is the preferred method since it is standardized
between different devices. <parameter>max_signal</parameter> does not need to be set.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_NOISE_DBM</term>
<listitem><para>
Hardware can provide noise (radio interference) values in units dBm,
decibel difference from one milliwatt.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_SPECTRUM_MGMT</term>
<listitem><para>
Hardware supports spectrum management defined in 802.11h
Measurement, Channel Switch, Quieting, TPC
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_AMPDU_AGGREGATION</term>
<listitem><para>
Hardware supports 11n A-MPDU aggregation.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_SUPPORTS_PS</term>
<listitem><para>
Hardware has power save support (i.e. can go to sleep).
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_PS_NULLFUNC_STACK</term>
<listitem><para>
Hardware requires nullfunc frame handling in stack, implies
stack support for dynamic PS.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_SUPPORTS_DYNAMIC_PS</term>
<listitem><para>
Hardware has support for dynamic PS.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_MFP_CAPABLE</term>
<listitem><para>
Hardware supports management frame protection (MFP, IEEE 802.11w).
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_BEACON_FILTER</term>
<listitem><para>
Hardware supports dropping of irrelevant beacon frames to
avoid waking up cpu.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_HW_REPORTS_TX_ACK_STATUS</term>
<listitem><para>
Hardware can provide ack status reports of Tx frames to
the stack.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
These flags are used to indicate hardware capabilities to
the stack. Generally, flags here should have their meaning
done in a way that the simplest hardware doesn't need setting
any particular flags. There are some exceptions to this rule,
however, so you are advised to review these flags carefully.
</para>
</refsect1>
</refentry>
<refentry id="API-SET-IEEE80211-DEV">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>SET_IEEE80211_DEV</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>SET_IEEE80211_DEV</refname>
<refpurpose>
set device for 802.11 hardware
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>SET_IEEE80211_DEV </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct device * <parameter>dev</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the <structname>struct ieee80211_hw</structname> to set the device for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>dev</parameter></term>
<listitem>
<para>
the <structname>struct device</structname> of this 802.11 device
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-SET-IEEE80211-PERM-ADDR">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>SET_IEEE80211_PERM_ADDR</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>SET_IEEE80211_PERM_ADDR</refname>
<refpurpose>
set the permanent MAC address for 802.11 hardware
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>SET_IEEE80211_PERM_ADDR </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>u8 * <parameter>addr</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the <structname>struct ieee80211_hw</structname> to set the MAC address for
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>addr</parameter></term>
<listitem>
<para>
the address to set
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-struct-ieee80211-ops">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_ops</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_ops</refname>
<refpurpose>
callbacks from mac80211 to the driver
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_ops {
int (* tx) (struct ieee80211_hw *hw, struct sk_buff *skb);
int (* start) (struct ieee80211_hw *hw);
void (* stop) (struct ieee80211_hw *hw);
int (* add_interface) (struct ieee80211_hw *hw,struct ieee80211_if_init_conf *conf);
void (* remove_interface) (struct ieee80211_hw *hw,struct ieee80211_if_init_conf *conf);
int (* config) (struct ieee80211_hw *hw, u32 changed);
void (* bss_info_changed) (struct ieee80211_hw *hw,struct ieee80211_vif *vif,struct ieee80211_bss_conf *info,u32 changed);
u64 (* prepare_multicast) (struct ieee80211_hw *hw,int mc_count, struct dev_addr_list *mc_list);
void (* configure_filter) (struct ieee80211_hw *hw,unsigned int changed_flags,unsigned int *total_flags,u64 multicast);
int (* set_tim) (struct ieee80211_hw *hw, struct ieee80211_sta *sta,bool set);
int (* set_key) (struct ieee80211_hw *hw, enum set_key_cmd cmd,struct ieee80211_vif *vif, struct ieee80211_sta *sta,struct ieee80211_key_conf *key);
void (* update_tkip_key) (struct ieee80211_hw *hw,struct ieee80211_key_conf *conf, const u8 *address,u32 iv32, u16 *phase1key);
int (* hw_scan) (struct ieee80211_hw *hw,struct cfg80211_scan_request *req);
void (* sw_scan_start) (struct ieee80211_hw *hw);
void (* sw_scan_complete) (struct ieee80211_hw *hw);
int (* get_stats) (struct ieee80211_hw *hw,struct ieee80211_low_level_stats *stats);
void (* get_tkip_seq) (struct ieee80211_hw *hw, u8 hw_key_idx,u32 *iv32, u16 *iv16);
int (* set_rts_threshold) (struct ieee80211_hw *hw, u32 value);
void (* sta_notify) (struct ieee80211_hw *hw, struct ieee80211_vif *vif,enum sta_notify_cmd, struct ieee80211_sta *sta);
int (* conf_tx) (struct ieee80211_hw *hw, u16 queue,const struct ieee80211_tx_queue_params *params);
int (* get_tx_stats) (struct ieee80211_hw *hw,struct ieee80211_tx_queue_stats *stats);
u64 (* get_tsf) (struct ieee80211_hw *hw);
void (* set_tsf) (struct ieee80211_hw *hw, u64 tsf);
void (* reset_tsf) (struct ieee80211_hw *hw);
int (* tx_last_beacon) (struct ieee80211_hw *hw);
int (* ampdu_action) (struct ieee80211_hw *hw,enum ieee80211_ampdu_mlme_action action,struct ieee80211_sta *sta, u16 tid, u16 *ssn);
void (* rfkill_poll) (struct ieee80211_hw *hw);
#ifdef CONFIG_NL80211_TESTMODE
int (* testmode_cmd) (struct ieee80211_hw *hw, void *data, int len);
#endif
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>tx</term>
<listitem><para>
Handler that 802.11 module calls for each transmitted frame.
skb contains the buffer starting from the IEEE 802.11 header.
The low-level driver should send the frame out based on
configuration in the TX control data. This handler should,
preferably, never fail and stop queues appropriately, more
importantly, however, it must never fail for A-MPDU-queues.
This function should return NETDEV_TX_OK except in very
limited cases.
Must be implemented and atomic.
</para></listitem>
</varlistentry>
<varlistentry> <term>start</term>
<listitem><para>
Called before the first netdevice attached to the hardware
is enabled. This should turn on the hardware and must turn on
frame reception (for possibly enabled monitor interfaces.)
Returns negative error codes, these may be seen in userspace,
or zero.
When the device is started it should not have a MAC address
to avoid acknowledging frames before a non-monitor device
is added.
Must be implemented.
</para></listitem>
</varlistentry>
<varlistentry> <term>stop</term>
<listitem><para>
Called after last netdevice attached to the hardware
is disabled. This should turn off the hardware (at least
it must turn off frame reception.)
May be called right after add_interface if that rejects
an interface. If you added any work onto the mac80211 workqueue
you should ensure to cancel it on this callback.
Must be implemented.
</para></listitem>
</varlistentry>
<varlistentry> <term>add_interface</term>
<listitem><para>
Called when a netdevice attached to the hardware is
enabled. Because it is not called for monitor mode devices, <parameter>start</parameter>
and <parameter>stop</parameter> must be implemented.
The driver should perform any initialization it needs before
the device can be enabled. The initial configuration for the
interface is given in the conf parameter.
The callback may refuse to add an interface by returning a
negative error code (which will be seen in userspace.)
Must be implemented.
</para></listitem>
</varlistentry>
<varlistentry> <term>remove_interface</term>
<listitem><para>
Notifies a driver that an interface is going down.
The <parameter>stop</parameter> callback is called after this if it is the last interface
and no monitor interfaces are present.
When all interfaces are removed, the MAC address in the hardware
must be cleared so the device no longer acknowledges packets,
the mac_addr member of the conf structure is, however, set to the
MAC address of the device going away.
Hence, this callback must be implemented.
</para></listitem>
</varlistentry>
<varlistentry> <term>config</term>
<listitem><para>
Handler for configuration requests. IEEE 802.11 code calls this
function to change hardware configuration, e.g., channel.
This function should never fail but returns a negative error code
if it does.
</para></listitem>
</varlistentry>
<varlistentry> <term>bss_info_changed</term>
<listitem><para>
Handler for configuration requests related to BSS
parameters that may vary during BSS's lifespan, and may affect low
level driver (e.g. assoc/disassoc status, erp parameters).
This function should not be used if no BSS has been set, unless
for association indication. The <parameter>changed</parameter> parameter indicates which
of the bss parameters has changed when a call is made.
</para></listitem>
</varlistentry>
<varlistentry> <term>prepare_multicast</term>
<listitem><para>
Prepare for multicast filter configuration.
This callback is optional, and its return value is passed
to <function>configure_filter</function>. This callback must be atomic.
</para></listitem>
</varlistentry>
<varlistentry> <term>configure_filter</term>
<listitem><para>
Configure the device's RX filter.
See the section <quote>Frame filtering</quote> for more information.
This callback must be implemented.
</para></listitem>
</varlistentry>
<varlistentry> <term>set_tim</term>
<listitem><para>
Set TIM bit. mac80211 calls this function when a TIM bit
must be set or cleared for a given STA. Must be atomic.
</para></listitem>
</varlistentry>
<varlistentry> <term>set_key</term>
<listitem><para>
See the section <quote>Hardware crypto acceleration</quote>
This callback can sleep, and is only called between add_interface
and remove_interface calls, i.e. while the given virtual interface
is enabled.
Returns a negative error code if the key can't be added.
</para></listitem>
</varlistentry>
<varlistentry> <term>update_tkip_key</term>
<listitem><para>
See the section <quote>Hardware crypto acceleration</quote>
This callback will be called in the context of Rx. Called for drivers
which set IEEE80211_KEY_FLAG_TKIP_REQ_RX_P1_KEY.
</para></listitem>
</varlistentry>
<varlistentry> <term>hw_scan</term>
<listitem><para>
Ask the hardware to service the scan request, no need to start
the scan state machine in stack. The scan must honour the channel
configuration done by the regulatory agent in the wiphy's
registered bands. The hardware (or the driver) needs to make sure
that power save is disabled.
The <parameter>req</parameter> ie/ie_len members are rewritten by mac80211 to contain the
entire IEs after the SSID, so that drivers need not look at these
at all but just send them after the SSID -- mac80211 includes the
(extended) supported rates and HT information (where applicable).
When the scan finishes, <function>ieee80211_scan_completed</function> must be called;
note that it also must be called when the scan cannot finish due to
any error unless this callback returned a negative error code.
</para></listitem>
</varlistentry>
<varlistentry> <term>sw_scan_start</term>
<listitem><para>
Notifier function that is called just before a software scan
is started. Can be NULL, if the driver doesn't need this notification.
</para></listitem>
</varlistentry>
<varlistentry> <term>sw_scan_complete</term>
<listitem><para>
Notifier function that is called just after a software scan
finished. Can be NULL, if the driver doesn't need this notification.
</para></listitem>
</varlistentry>
<varlistentry> <term>get_stats</term>
<listitem><para>
Return low-level statistics.
Returns zero if statistics are available.
</para></listitem>
</varlistentry>
<varlistentry> <term>get_tkip_seq</term>
<listitem><para>
If your device implements TKIP encryption in hardware this
callback should be provided to read the TKIP transmit IVs (both IV32
and IV16) for the given key from hardware.
</para></listitem>
</varlistentry>
<varlistentry> <term>set_rts_threshold</term>
<listitem><para>
Configuration of RTS threshold (if device needs it)
</para></listitem>
</varlistentry>
<varlistentry> <term>sta_notify</term>
<listitem><para>
Notifies low level driver about power state transition of an
associated station, AP, IBSS/WDS/mesh peer etc. Must be atomic.
</para></listitem>
</varlistentry>
<varlistentry> <term>conf_tx</term>
<listitem><para>
Configure TX queue parameters (EDCF (aifs, cw_min, cw_max),
bursting) for a hardware TX queue.
Returns a negative error code on failure.
</para></listitem>
</varlistentry>
<varlistentry> <term>get_tx_stats</term>
<listitem><para>
Get statistics of the current TX queue status. This is used
to get number of currently queued packets (queue length), maximum queue
size (limit), and total number of packets sent using each TX queue
(count). The 'stats' pointer points to an array that has hw->queues
items.
</para></listitem>
</varlistentry>
<varlistentry> <term>get_tsf</term>
<listitem><para>
Get the current TSF timer value from firmware/hardware. Currently,
this is only used for IBSS mode BSSID merging and debugging. Is not a
required function.
</para></listitem>
</varlistentry>
<varlistentry> <term>set_tsf</term>
<listitem><para>
Set the TSF timer to the specified value in the firmware/hardware.
Currently, this is only used for IBSS mode debugging. Is not a
required function.
</para></listitem>
</varlistentry>
<varlistentry> <term>reset_tsf</term>
<listitem><para>
Reset the TSF timer and allow firmware/hardware to synchronize
with other STAs in the IBSS. This is only used in IBSS mode. This
function is optional if the firmware/hardware takes full care of
TSF synchronization.
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_last_beacon</term>
<listitem><para>
Determine whether the last IBSS beacon was sent by us.
This is needed only for IBSS mode and the result of this function is
used to determine whether to reply to Probe Requests.
Returns non-zero if this device sent the last beacon.
</para></listitem>
</varlistentry>
<varlistentry> <term>ampdu_action</term>
<listitem><para>
Perform a certain A-MPDU action
The RA/TID combination determines the destination and TID we want
the ampdu action to be performed for. The action is defined through
ieee80211_ampdu_mlme_action. Starting sequence number (<parameter>ssn</parameter>)
is the first frame we expect to perform the action on. Notice
that TX/RX_STOP can pass NULL for this parameter.
Returns a negative error code on failure.
</para></listitem>
</varlistentry>
<varlistentry> <term>rfkill_poll</term>
<listitem><para>
Poll rfkill hardware state. If you need this, you also
need to set wiphy->rfkill_poll to <constant>true</constant> before registration,
and need to call <function>wiphy_rfkill_set_hw_state</function> in the callback.
</para></listitem>
</varlistentry>
<varlistentry> <term>testmode_cmd</term>
<listitem><para>
Implement a cfg80211 test mode command.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This structure contains various callbacks that the driver may
handle or, in some cases, must handle, for example to configure
the hardware to a new channel or to transmit a frame.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-alloc-hw">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_alloc_hw</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_alloc_hw</refname>
<refpurpose>
Allocate a new hardware device
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct ieee80211_hw * <function>ieee80211_alloc_hw </function></funcdef>
<paramdef>size_t <parameter>priv_data_len</parameter></paramdef>
<paramdef>const struct ieee80211_ops * <parameter>ops</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>priv_data_len</parameter></term>
<listitem>
<para>
length of private data
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>ops</parameter></term>
<listitem>
<para>
callbacks for this device
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This must be called once for each hardware device. The returned pointer
must be used to refer to this device when calling other functions.
mac80211 allocates a private data area for the driver pointed to by
<parameter>priv</parameter> in <structname>struct ieee80211_hw</structname>, the size of this area is given as
<parameter>priv_data_len</parameter>.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-register-hw">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_register_hw</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_register_hw</refname>
<refpurpose>
Register hardware device
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>int <function>ieee80211_register_hw </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the device to register as returned by <function>ieee80211_alloc_hw</function>
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
You must call this function before any other functions in
mac80211. Note that before a hardware can be registered, you
need to fill the contained wiphy's information.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-get-tx-led-name">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_get_tx_led_name</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_get_tx_led_name</refname>
<refpurpose>
get name of TX LED
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>char * <function>ieee80211_get_tx_led_name </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware to get the LED trigger name for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
mac80211 creates a transmit LED trigger for each wireless hardware
that can be used to drive LEDs if your driver registers a LED device.
This function returns the name (or <constant>NULL</constant> if not configured for LEDs)
of the trigger so you can automatically link the LED device.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-get-rx-led-name">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_get_rx_led_name</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_get_rx_led_name</refname>
<refpurpose>
get name of RX LED
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>char * <function>ieee80211_get_rx_led_name </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware to get the LED trigger name for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
mac80211 creates a receive LED trigger for each wireless hardware
that can be used to drive LEDs if your driver registers a LED device.
This function returns the name (or <constant>NULL</constant> if not configured for LEDs)
of the trigger so you can automatically link the LED device.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-get-assoc-led-name">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_get_assoc_led_name</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_get_assoc_led_name</refname>
<refpurpose>
get name of association LED
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>char * <function>ieee80211_get_assoc_led_name </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware to get the LED trigger name for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
mac80211 creates a association LED trigger for each wireless hardware
that can be used to drive LEDs if your driver registers a LED device.
This function returns the name (or <constant>NULL</constant> if not configured for LEDs)
of the trigger so you can automatically link the LED device.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-get-radio-led-name">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_get_radio_led_name</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_get_radio_led_name</refname>
<refpurpose>
get name of radio LED
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>char * <function>ieee80211_get_radio_led_name </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware to get the LED trigger name for
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
mac80211 creates a radio change LED trigger for each wireless hardware
that can be used to drive LEDs if your driver registers a LED device.
This function returns the name (or <constant>NULL</constant> if not configured for LEDs)
of the trigger so you can automatically link the LED device.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-unregister-hw">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_unregister_hw</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_unregister_hw</refname>
<refpurpose>
Unregister a hardware device
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_unregister_hw </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware to unregister
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This function instructs mac80211 to free allocated resources
and unregister netdevices from the networking subsystem.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-free-hw">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_free_hw</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_free_hw</refname>
<refpurpose>
free hardware descriptor
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_free_hw </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware to free
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This function frees everything that was allocated, including the
private data for the driver. You must call <function>ieee80211_unregister_hw</function>
before calling this function.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="phy-handling">
<title>PHY configuration</title>
<para>TBD</para>
<para>
This chapter should describe PHY handling including
start/stop callbacks and the various structures used.
</para>
<refentry id="API-struct-ieee80211-conf">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_conf</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_conf</refname>
<refpurpose>
configuration of the device
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_conf {
u32 flags;
int power_level;
int dynamic_ps_timeout;
int max_sleep_period;
u16 listen_interval;
u8 long_frame_max_tx_count;
u8 short_frame_max_tx_count;
struct ieee80211_channel * channel;
enum nl80211_channel_type channel_type;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>flags</term>
<listitem><para>
configuration flags defined above
</para></listitem>
</varlistentry>
<varlistentry> <term>power_level</term>
<listitem><para>
requested transmit power (in dBm)
</para></listitem>
</varlistentry>
<varlistentry> <term>dynamic_ps_timeout</term>
<listitem><para>
The dynamic powersave timeout (in ms), see the
powersave documentation below. This variable is valid only when
the CONF_PS flag is set.
</para></listitem>
</varlistentry>
<varlistentry> <term>max_sleep_period</term>
<listitem><para>
the maximum number of beacon intervals to sleep for
before checking the beacon for a TIM bit (managed mode only); this
value will be only achievable between DTIM frames, the hardware
needs to check for the multicast traffic bit in DTIM beacons.
This variable is valid only when the CONF_PS flag is set.
</para></listitem>
</varlistentry>
<varlistentry> <term>listen_interval</term>
<listitem><para>
listen interval in units of beacon interval
</para></listitem>
</varlistentry>
<varlistentry> <term>long_frame_max_tx_count</term>
<listitem><para>
Maximum number of transmissions for a <quote>long</quote> frame
(a frame not RTS protected), called <quote>dot11LongRetryLimit</quote> in 802.11,
but actually means the number of transmissions not the number of retries
</para></listitem>
</varlistentry>
<varlistentry> <term>short_frame_max_tx_count</term>
<listitem><para>
Maximum number of transmissions for a <quote>short</quote>
frame, called <quote>dot11ShortRetryLimit</quote> in 802.11, but actually means the
number of transmissions not the number of retries
</para></listitem>
</varlistentry>
<varlistentry> <term>channel</term>
<listitem><para>
the channel to tune to
</para></listitem>
</varlistentry>
<varlistentry> <term>channel_type</term>
<listitem><para>
the channel (HT) type
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This struct indicates how the driver shall configure the hardware.
</para>
</refsect1>
</refentry>
<refentry id="API-enum-ieee80211-conf-flags">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum ieee80211_conf_flags</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum ieee80211_conf_flags</refname>
<refpurpose>
configuration flags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum ieee80211_conf_flags {
IEEE80211_CONF_RADIOTAP,
IEEE80211_CONF_PS,
IEEE80211_CONF_IDLE,
IEEE80211_CONF_QOS
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>IEEE80211_CONF_RADIOTAP</term>
<listitem><para>
add radiotap header at receive time (if supported)
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_CONF_PS</term>
<listitem><para>
Enable 802.11 power save mode (managed mode only)
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_CONF_IDLE</term>
<listitem><para>
The device is running, but idle; if the flag is set
the driver should be prepared to handle configuration requests but
may turn the device off as much as possible. Typically, this flag will
be set when an interface is set UP but not associated or scanning, but
it can also be unset in that case when monitor interfaces are active.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_CONF_QOS</term>
<listitem><para>
Enable 802.11e QoS also know as WMM (Wireless
Multimedia). On some drivers (iwlwifi is one of know) we have
to enable/disable QoS explicitly.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Flags to define PHY configuration options
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="iface-handling">
<title>Virtual interfaces</title>
<para>TBD</para>
<para>
This chapter should describe virtual interface basics
that are relevant to the driver (VLANs, MGMT etc are not.)
It should explain the use of the add_iface/remove_iface
callbacks as well as the interface configuration callbacks.
</para>
<para>Things related to AP mode should be discussed there.</para>
<para>
Things related to supporting multiple interfaces should be
in the appropriate chapter, a BIG FAT note should be here about
this though and the recommendation to allow only a single
interface in STA mode at first!
</para>
<refentry id="API-struct-ieee80211-if-init-conf">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_if_init_conf</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_if_init_conf</refname>
<refpurpose>
initial configuration of an interface
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_if_init_conf {
enum nl80211_iftype type;
struct ieee80211_vif * vif;
void * mac_addr;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>type</term>
<listitem><para>
one of <structname>enum</structname> nl80211_iftype constants. Determines the type of
added/removed interface.
</para></listitem>
</varlistentry>
<varlistentry> <term>vif</term>
<listitem><para>
pointer to a driver-use per-interface structure. The pointer
itself is also used for various functions including
<function>ieee80211_beacon_get</function> and <function>ieee80211_get_buffered_bc</function>.
</para></listitem>
</varlistentry>
<varlistentry> <term>mac_addr</term>
<listitem><para>
pointer to MAC address of the interface. This pointer is valid
until the interface is removed (i.e. it cannot be used after
<function>remove_interface</function> callback was called for this interface).
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
This structure is used in <function>add_interface</function> and <function>remove_interface</function>
callbacks of <structname>struct ieee80211_hw</structname>.
</para><para>
When you allow multiple interfaces to be added to your PHY, take care
that the hardware can actually handle multiple MAC addresses. However,
also take care that when there's no interface left with mac_addr != <constant>NULL</constant>
you remove the MAC address from the device to avoid acknowledging packets
in pure monitor mode.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="rx-tx">
<title>Receive and transmit processing</title>
<sect1>
<title>what should be here</title>
<para>TBD</para>
<para>
This should describe the receive and transmit
paths in mac80211/the drivers as well as
transmit status handling.
</para>
</sect1>
<sect1>
<title>Frame format</title>
<para>
</para><para>
As a general rule, when frames are passed between mac80211 and the driver,
they start with the IEEE 802.11 header and include the same octets that are
sent over the air except for the FCS which should be calculated by the
hardware.
</para><para>
There are, however, various exceptions to this rule for advanced features:
</para><para>
The first exception is for hardware encryption and decryption offload
where the IV/ICV may or may not be generated in hardware.
</para><para>
Secondly, when the hardware handles fragmentation, the frame handed to
the driver from mac80211 is the MSDU, not the MPDU.
</para><para>
Finally, for received frames, the driver is able to indicate that it has
filled a radiotap header and put that in front of the frame; if it does
not do so then mac80211 may add this under certain circumstances.
</para>
</sect1>
<sect1>
<title>Packet alignment</title>
<para>
</para><para>
Drivers always need to pass packets that are aligned to two-byte boundaries
to the stack.
</para><para>
Additionally, should, if possible, align the payload data in a way that
guarantees that the contained IP header is aligned to a four-byte
boundary. In the case of regular frames, this simply means aligning the
payload to a four-byte boundary (because either the IP header is directly
contained, or IV/RFC1042 headers that have a length divisible by four are
in front of it).
</para><para>
With A-MSDU frames, however, the payload data address must yield two modulo
four because there are 14-byte 802.3 headers within the A-MSDU frames that
push the IP header further back to a multiple of four again. Thankfully, the
specs were sane enough this time around to require padding each A-MSDU
subframe to a length that is a multiple of four.
</para><para>
Padding like Atheros hardware adds which is inbetween the 802.11 header and
the payload is not supported, the driver is required to move the 802.11
header to be directly in front of the payload in that case.
</para>
</sect1>
<sect1>
<title>Calling into mac80211 from interrupts</title>
<para>
</para><para>
Only <function>ieee80211_tx_status_irqsafe</function> and <function>ieee80211_rx_irqsafe</function> can be
called in hardware interrupt context. The low-level driver must not call any
other functions in hardware interrupt context. If there is a need for such
call, the low-level driver should first ACK the interrupt and perform the
IEEE 802.11 code call after this, e.g. from a scheduled workqueue or even
tasklet function.
</para><para>
NOTE: If the driver opts to use the <function>_irqsafe</function> functions, it may not also
use the non-IRQ-safe functions!
</para>
</sect1>
<sect1>
<title>functions/definitions</title>
<refentry id="API-struct-ieee80211-rx-status">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_rx_status</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_rx_status</refname>
<refpurpose>
receive status
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_rx_status {
u64 mactime;
enum ieee80211_band band;
int freq;
int signal;
int noise;
int qual;
int antenna;
int rate_idx;
int flag;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>mactime</term>
<listitem><para>
value in microseconds of the 64-bit Time Synchronization Function
(TSF) timer when the first data symbol (MPDU) arrived at the hardware.
</para></listitem>
</varlistentry>
<varlistentry> <term>band</term>
<listitem><para>
the active band when this frame was received
</para></listitem>
</varlistentry>
<varlistentry> <term>freq</term>
<listitem><para>
frequency the radio was tuned to when receiving this frame, in MHz
</para></listitem>
</varlistentry>
<varlistentry> <term>signal</term>
<listitem><para>
signal strength when receiving this frame, either in dBm, in dB or
unspecified depending on the hardware capabilities flags
<parameter>IEEE80211_HW_SIGNAL_</parameter>*
</para></listitem>
</varlistentry>
<varlistentry> <term>noise</term>
<listitem><para>
noise when receiving this frame, in dBm.
</para></listitem>
</varlistentry>
<varlistentry> <term>qual</term>
<listitem><para>
overall signal quality indication, in percent (0-100).
</para></listitem>
</varlistentry>
<varlistentry> <term>antenna</term>
<listitem><para>
antenna used
</para></listitem>
</varlistentry>
<varlistentry> <term>rate_idx</term>
<listitem><para>
index of data rate into band's supported rates or MCS index if
HT rates are use (RX_FLAG_HT)
</para></listitem>
</varlistentry>
<varlistentry> <term>flag</term>
<listitem><para>
<constant>RX_FLAG_</constant>*
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
The low-level driver should provide this information (the subset
supported by hardware) to the 802.11 code with each received
frame, in the skb's control buffer (cb).
</para>
</refsect1>
</refentry>
<refentry id="API-enum-mac80211-rx-flags">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum mac80211_rx_flags</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum mac80211_rx_flags</refname>
<refpurpose>
receive flags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum mac80211_rx_flags {
RX_FLAG_MMIC_ERROR,
RX_FLAG_DECRYPTED,
RX_FLAG_RADIOTAP,
RX_FLAG_MMIC_STRIPPED,
RX_FLAG_IV_STRIPPED,
RX_FLAG_FAILED_FCS_CRC,
RX_FLAG_FAILED_PLCP_CRC,
RX_FLAG_TSFT,
RX_FLAG_SHORTPRE,
RX_FLAG_HT,
RX_FLAG_40MHZ,
RX_FLAG_SHORT_GI
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>RX_FLAG_MMIC_ERROR</term>
<listitem><para>
Michael MIC error was reported on this frame.
Use together with <constant>RX_FLAG_MMIC_STRIPPED</constant>.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_DECRYPTED</term>
<listitem><para>
This frame was decrypted in hardware.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_RADIOTAP</term>
<listitem><para>
This frame starts with a radiotap header.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_MMIC_STRIPPED</term>
<listitem><para>
the Michael MIC is stripped off this frame,
verification has been done by the hardware.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_IV_STRIPPED</term>
<listitem><para>
The IV/ICV are stripped from this frame.
If this flag is set, the stack cannot do any replay detection
hence the driver or hardware will have to do that.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_FAILED_FCS_CRC</term>
<listitem><para>
Set this flag if the FCS check failed on
the frame.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_FAILED_PLCP_CRC</term>
<listitem><para>
Set this flag if the PCLP check failed on
the frame.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_TSFT</term>
<listitem><para>
The timestamp passed in the RX status (<parameter>mactime</parameter> field)
is valid. This is useful in monitor mode and necessary for beacon frames
to enable IBSS merging.
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_SHORTPRE</term>
<listitem><para>
Short preamble was used for this frame
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_HT</term>
<listitem><para>
HT MCS was used and rate_idx is MCS index
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_40MHZ</term>
<listitem><para>
HT40 (40 MHz) was used
</para></listitem>
</varlistentry>
<varlistentry> <term>RX_FLAG_SHORT_GI</term>
<listitem><para>
Short guard interval was used
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
These flags are used with the <parameter>flag</parameter> member of <structname>struct ieee80211_rx_status</structname>.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-ieee80211-tx-info">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_tx_info</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_tx_info</refname>
<refpurpose>
skb transmit information
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_tx_info {
u32 flags;
u8 band;
u8 antenna_sel_tx;
u8 pad[2];
union {unnamed_union};
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>flags</term>
<listitem><para>
transmit info flags, defined above
</para></listitem>
</varlistentry>
<varlistentry> <term>band</term>
<listitem><para>
the band to transmit on (use for checking for races)
</para></listitem>
</varlistentry>
<varlistentry> <term>antenna_sel_tx</term>
<listitem><para>
antenna to use, 0 for automatic diversity
</para></listitem>
</varlistentry>
<varlistentry> <term>pad[2]</term>
<listitem><para>
padding, ignore
</para></listitem>
</varlistentry>
<varlistentry> <term>{unnamed_union}</term>
<listitem><para>
anonymous
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This structure is placed in skb->cb for three uses:
(1) mac80211 TX control - mac80211 tells the driver what to do
(2) driver internal use (if applicable)
(3) TX status information - driver tells mac80211 what happened
</para><para>
The TX control's sta pointer is only valid during the ->tx call,
it may be NULL.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-rx">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_rx</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_rx</refname>
<refpurpose>
receive frame
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_rx </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware this frame came in on
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>skb</parameter></term>
<listitem>
<para>
the buffer to receive, owned by mac80211 after this call
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Use this function to hand received frames to mac80211. The receive
buffer in <parameter>skb</parameter> must start with an IEEE 802.11 header or a radiotap
header if <constant>RX_FLAG_RADIOTAP</constant> is set in the <parameter>status</parameter> flags.
</para><para>
This function may not be called in IRQ context. Calls to this function
for a single hardware must be synchronized against each other. Calls
to this function and <function>ieee80211_rx_irqsafe</function> may not be mixed for a
single hardware.
</para><para>
Note that right now, this function must be called with softirqs disabled.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-rx-irqsafe">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_rx_irqsafe</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_rx_irqsafe</refname>
<refpurpose>
receive frame
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_rx_irqsafe </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware this frame came in on
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>skb</parameter></term>
<listitem>
<para>
the buffer to receive, owned by mac80211 after this call
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Like <function>ieee80211_rx</function> but can be called in IRQ context
(internally defers to a tasklet.)
</para><para>
Calls to this function and <function>ieee80211_rx</function> may not be mixed for a
single hardware.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-tx-status">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_tx_status</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_tx_status</refname>
<refpurpose>
transmit status callback
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_tx_status </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware the frame was transmitted by
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>skb</parameter></term>
<listitem>
<para>
the frame that was transmitted, owned by mac80211 after this call
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Call this function for all transmitted frames after they have been
transmitted. It is permissible to not call this function for
multicast frames but this can affect statistics.
</para><para>
This function may not be called in IRQ context. Calls to this function
for a single hardware must be synchronized against each other. Calls
to this function and <function>ieee80211_tx_status_irqsafe</function> may not be mixed
for a single hardware.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-tx-status-irqsafe">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_tx_status_irqsafe</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_tx_status_irqsafe</refname>
<refpurpose>
IRQ-safe transmit status callback
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_tx_status_irqsafe </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct sk_buff * <parameter>skb</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware the frame was transmitted by
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>skb</parameter></term>
<listitem>
<para>
the frame that was transmitted, owned by mac80211 after this call
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Like <function>ieee80211_tx_status</function> but can be called in IRQ context
(internally defers to a tasklet.)
</para><para>
Calls to this function and <function>ieee80211_tx_status</function> may not be mixed for a
single hardware.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-rts-get">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_rts_get</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_rts_get</refname>
<refpurpose>
RTS frame generation function
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_rts_get </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
<paramdef>const void * <parameter>frame</parameter></paramdef>
<paramdef>size_t <parameter>frame_len</parameter></paramdef>
<paramdef>const struct ieee80211_tx_info * <parameter>frame_txctl</parameter></paramdef>
<paramdef>struct ieee80211_rts * <parameter>rts</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame</parameter></term>
<listitem>
<para>
pointer to the frame that is going to be protected by the RTS.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_len</parameter></term>
<listitem>
<para>
the frame length (in octets).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_txctl</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_tx_info</structname> of the frame.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>rts</parameter></term>
<listitem>
<para>
The buffer where to store the RTS frame.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If the RTS frames are generated by the host system (i.e., not in
hardware/firmware), the low-level driver uses this function to receive
the next RTS frame from the 802.11 code. The low-level is responsible
for calling this function before and RTS frame is needed.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-rts-duration">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_rts_duration</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_rts_duration</refname>
<refpurpose>
Get the duration field for an RTS frame
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__le16 <function>ieee80211_rts_duration </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
<paramdef>size_t <parameter>frame_len</parameter></paramdef>
<paramdef>const struct ieee80211_tx_info * <parameter>frame_txctl</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_len</parameter></term>
<listitem>
<para>
the length of the frame that is going to be protected by the RTS.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_txctl</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_tx_info</structname> of the frame.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If the RTS is generated in firmware, but the host system must provide
the duration field, the low-level driver uses this function to receive
the duration field value in little-endian byteorder.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-ctstoself-get">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_ctstoself_get</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_ctstoself_get</refname>
<refpurpose>
CTS-to-self frame generation function
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_ctstoself_get </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
<paramdef>const void * <parameter>frame</parameter></paramdef>
<paramdef>size_t <parameter>frame_len</parameter></paramdef>
<paramdef>const struct ieee80211_tx_info * <parameter>frame_txctl</parameter></paramdef>
<paramdef>struct ieee80211_cts * <parameter>cts</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame</parameter></term>
<listitem>
<para>
pointer to the frame that is going to be protected by the CTS-to-self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_len</parameter></term>
<listitem>
<para>
the frame length (in octets).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_txctl</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_tx_info</structname> of the frame.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>cts</parameter></term>
<listitem>
<para>
The buffer where to store the CTS-to-self frame.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If the CTS-to-self frames are generated by the host system (i.e., not in
hardware/firmware), the low-level driver uses this function to receive
the next CTS-to-self frame from the 802.11 code. The low-level is responsible
for calling this function before and CTS-to-self frame is needed.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-ctstoself-duration">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_ctstoself_duration</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_ctstoself_duration</refname>
<refpurpose>
Get the duration field for a CTS-to-self frame
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__le16 <function>ieee80211_ctstoself_duration </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
<paramdef>size_t <parameter>frame_len</parameter></paramdef>
<paramdef>const struct ieee80211_tx_info * <parameter>frame_txctl</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_len</parameter></term>
<listitem>
<para>
the length of the frame that is going to be protected by the CTS-to-self.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_txctl</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_tx_info</structname> of the frame.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If the CTS-to-self is generated in firmware, but the host system must provide
the duration field, the low-level driver uses this function to receive
the duration field value in little-endian byteorder.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-generic-frame-duration">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_generic_frame_duration</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_generic_frame_duration</refname>
<refpurpose>
Calculate the duration field for a frame
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>__le16 <function>ieee80211_generic_frame_duration </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
<paramdef>size_t <parameter>frame_len</parameter></paramdef>
<paramdef>struct ieee80211_rate * <parameter>rate</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>frame_len</parameter></term>
<listitem>
<para>
the length of the frame.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>rate</parameter></term>
<listitem>
<para>
the rate at which the frame is going to be transmitted.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Calculate the duration field of some generic frame, given its
length and transmission rate (in 100kbps).
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-wake-queue">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_wake_queue</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_wake_queue</refname>
<refpurpose>
wake specific queue
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_wake_queue </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>int <parameter>queue</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer as obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>queue</parameter></term>
<listitem>
<para>
queue number (counted from zero).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Drivers should use this function instead of netif_wake_queue.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-stop-queue">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_stop_queue</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_stop_queue</refname>
<refpurpose>
stop specific queue
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_stop_queue </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>int <parameter>queue</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer as obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>queue</parameter></term>
<listitem>
<para>
queue number (counted from zero).
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Drivers should use this function instead of netif_stop_queue.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-wake-queues">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_wake_queues</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_wake_queues</refname>
<refpurpose>
wake all queues
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_wake_queues </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer as obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Drivers should use this function instead of netif_wake_queue.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-stop-queues">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_stop_queues</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_stop_queues</refname>
<refpurpose>
stop all queues
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_stop_queues </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer as obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Drivers should use this function instead of netif_stop_queue.
</para>
</refsect1>
</refentry>
</sect1>
</chapter>
<chapter id="filters">
<title>Frame filtering</title>
<para>
</para><para>
mac80211 requires to see many management frames for proper
operation, and users may want to see many more frames when
in monitor mode. However, for best CPU usage and power consumption,
having as few frames as possible percolate through the stack is
desirable. Hence, the hardware should filter as much as possible.
</para><para>
To achieve this, mac80211 uses filter flags (see below) to tell
the driver's <function>configure_filter</function> function which frames should be
passed to mac80211 and which should be filtered out.
</para><para>
Before <function>configure_filter</function> is invoked, the <function>prepare_multicast</function>
callback is invoked with the parameters <parameter>mc_count</parameter> and <parameter>mc_list</parameter>
for the combined multicast address list of all virtual interfaces.
It's use is optional, and it returns a u64 that is passed to
<function>configure_filter</function>. Additionally, <function>configure_filter</function> has the
arguments <parameter>changed_flags</parameter> telling which flags were changed and
<parameter>total_flags</parameter> with the new flag states.
</para><para>
If your device has no multicast address filters your driver will
need to check both the <constant>FIF_ALLMULTI</constant> flag and the <parameter>mc_count</parameter>
parameter to see whether multicast frames should be accepted
or dropped.
</para><para>
All unsupported flags in <parameter>total_flags</parameter> must be cleared.
Hardware does not support a flag if it is incapable of _passing_
the frame to the stack. Otherwise the driver must ignore
the flag, but not clear it.
You must _only_ clear the flag (announce no support for the
flag to mac80211) if you are not able to pass the packet type
to the stack (so the hardware always filters it).
So for example, you should clear <parameter>FIF_CONTROL</parameter>, if your hardware
always filters control frames. If your hardware always passes
control frames to the kernel and is incapable of filtering them,
you do _not_ clear the <parameter>FIF_CONTROL</parameter> flag.
This rule applies to all other FIF flags as well.
</para>
<refentry id="API-enum-ieee80211-filter-flags">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum ieee80211_filter_flags</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum ieee80211_filter_flags</refname>
<refpurpose>
hardware filter flags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum ieee80211_filter_flags {
FIF_PROMISC_IN_BSS,
FIF_ALLMULTI,
FIF_FCSFAIL,
FIF_PLCPFAIL,
FIF_BCN_PRBRESP_PROMISC,
FIF_CONTROL,
FIF_OTHER_BSS,
FIF_PSPOLL
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>FIF_PROMISC_IN_BSS</term>
<listitem><para>
promiscuous mode within your BSS,
think of the BSS as your network segment and then this corresponds
to the regular ethernet device promiscuous mode.
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_ALLMULTI</term>
<listitem><para>
pass all multicast frames, this is used if requested
by the user or if the hardware is not capable of filtering by
multicast address.
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_FCSFAIL</term>
<listitem><para>
pass frames with failed FCS (but you need to set the
<constant>RX_FLAG_FAILED_FCS_CRC</constant> for them)
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_PLCPFAIL</term>
<listitem><para>
pass frames with failed PLCP CRC (but you need to set
the <constant>RX_FLAG_FAILED_PLCP_CRC</constant> for them
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_BCN_PRBRESP_PROMISC</term>
<listitem><para>
This flag is set during scanning to indicate
to the hardware that it should not filter beacons or probe responses
by BSSID. Filtering them can greatly reduce the amount of processing
mac80211 needs to do and the amount of CPU wakeups, so you should
honour this flag if possible.
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_CONTROL</term>
<listitem><para>
pass control frames (except for PS Poll), if PROMISC_IN_BSS
is not set then only those addressed to this station.
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_OTHER_BSS</term>
<listitem><para>
pass frames destined to other BSSes
</para></listitem>
</varlistentry>
<varlistentry> <term>FIF_PSPOLL</term>
<listitem><para>
pass PS Poll frames, if PROMISC_IN_BSS is not set then only
those addressed to this station.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Frame filtering</title>
<para>
</para><para>
These flags determine what the filter in hardware should be
programmed to let through and what should not be passed to the
stack. It is always safe to pass more frames than requested,
but this has negative impact on power consumption.
</para>
</refsect1>
</refentry>
</chapter>
</part>
<part id="advanced">
<title>Advanced driver interface</title>
<partintro>
<para>
Information contained within this part of the book is
of interest only for advanced interaction of mac80211
with drivers to exploit more hardware capabilities and
improve performance.
</para>
</partintro>
<chapter id="hardware-crypto-offload">
<title>Hardware crypto acceleration</title>
<para>
</para><para>
mac80211 is capable of taking advantage of many hardware
acceleration designs for encryption and decryption operations.
</para><para>
The <function>set_key</function> callback in the <structname>struct ieee80211_ops</structname> for a given
device is called to enable hardware acceleration of encryption and
decryption. The callback takes a <parameter>sta</parameter> parameter that will be NULL
for default keys or keys used for transmission only, or point to
the station information for the peer for individual keys.
Multiple transmission keys with the same key index may be used when
VLANs are configured for an access point.
</para><para>
When transmitting, the TX control data will use the <parameter>hw_key_idx</parameter>
selected by the driver by modifying the <structname>struct ieee80211_key_conf</structname>
pointed to by the <parameter>key</parameter> parameter to the <function>set_key</function> function.
</para><para>
The <function>set_key</function> call for the <constant>SET_KEY</constant> command should return 0 if
the key is now in use, -<constant>EOPNOTSUPP</constant> or -<constant>ENOSPC</constant> if it couldn't be
added; if you return 0 then hw_key_idx must be assigned to the
hardware key index, you are free to use the full u8 range.
</para><para>
When the cmd is <constant>DISABLE_KEY</constant> then it must succeed.
</para><para>
Note that it is permissible to not decrypt a frame even if a key
for it has been uploaded to hardware, the stack will not make any
decision based on whether a key has been uploaded or not but rather
based on the receive flags.
</para><para>
The <structname>struct ieee80211_key_conf</structname> structure pointed to by the <parameter>key</parameter>
parameter is guaranteed to be valid until another call to <function>set_key</function>
removes it, but it can only be used as a cookie to differentiate
keys.
</para><para>
In TKIP some HW need to be provided a phase 1 key, for RX decryption
acceleration (i.e. iwlwifi). Those drivers should provide update_tkip_key
handler.
The <function>update_tkip_key</function> call updates the driver with the new phase 1 key.
This happens everytime the iv16 wraps around (every 65536 packets). The
<function>set_key</function> call will happen only once for each key (unless the AP did
rekeying), it will not include a valid phase 1 key. The valid phase 1 key is
provided by update_tkip_key only. The trigger that makes mac80211 call this
handler is software decryption with wrap around of iv16.
</para>
<!-- intentionally multiple !F lines to get proper order -->
<refentry id="API-enum-set-key-cmd">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum set_key_cmd</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum set_key_cmd</refname>
<refpurpose>
key command
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum set_key_cmd {
SET_KEY,
DISABLE_KEY
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>SET_KEY</term>
<listitem><para>
a key is set
</para></listitem>
</varlistentry>
<varlistentry> <term>DISABLE_KEY</term>
<listitem><para>
a key must be disabled
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
Used with the <function>set_key</function> callback in <structname>struct ieee80211_ops</structname>, this
indicates whether a key is being removed or added.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-ieee80211-key-conf">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_key_conf</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_key_conf</refname>
<refpurpose>
key information
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_key_conf {
enum ieee80211_key_alg alg;
u8 icv_len;
u8 iv_len;
u8 hw_key_idx;
u8 flags;
s8 keyidx;
u8 keylen;
u8 key[0];
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>alg</term>
<listitem><para>
The key algorithm.
</para></listitem>
</varlistentry>
<varlistentry> <term>icv_len</term>
<listitem><para>
The ICV length for this key type
</para></listitem>
</varlistentry>
<varlistentry> <term>iv_len</term>
<listitem><para>
The IV length for this key type
</para></listitem>
</varlistentry>
<varlistentry> <term>hw_key_idx</term>
<listitem><para>
To be set by the driver, this is the key index the driver
wants to be given when a frame is transmitted and needs to be
encrypted in hardware.
</para></listitem>
</varlistentry>
<varlistentry> <term>flags</term>
<listitem><para>
key flags, see <structname>enum</structname> ieee80211_key_flags.
</para></listitem>
</varlistentry>
<varlistentry> <term>keyidx</term>
<listitem><para>
the key index (0-3)
</para></listitem>
</varlistentry>
<varlistentry> <term>keylen</term>
<listitem><para>
key material length
</para></listitem>
</varlistentry>
<varlistentry> <term>key[0]</term>
<listitem><para>
key material. For ALG_TKIP the key is encoded as a 256-bit (32 byte)
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This key information is given by mac80211 to the driver by
the <function>set_key</function> callback in <structname>struct ieee80211_ops</structname>.
</para>
</refsect1>
<refsect1>
<title>data block</title>
<para>
- Temporal Encryption Key (128 bits)
- Temporal Authenticator Tx MIC Key (64 bits)
- Temporal Authenticator Rx MIC Key (64 bits)
</para>
</refsect1>
</refentry>
<refentry id="API-enum-ieee80211-key-alg">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum ieee80211_key_alg</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum ieee80211_key_alg</refname>
<refpurpose>
key algorithm
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum ieee80211_key_alg {
ALG_WEP,
ALG_TKIP,
ALG_CCMP,
ALG_AES_CMAC
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>ALG_WEP</term>
<listitem><para>
WEP40 or WEP104
</para></listitem>
</varlistentry>
<varlistentry> <term>ALG_TKIP</term>
<listitem><para>
TKIP
</para></listitem>
</varlistentry>
<varlistentry> <term>ALG_CCMP</term>
<listitem><para>
CCMP (AES)
</para></listitem>
</varlistentry>
<varlistentry> <term>ALG_AES_CMAC</term>
<listitem><para>
AES-128-CMAC
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
<refentry id="API-enum-ieee80211-key-flags">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum ieee80211_key_flags</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum ieee80211_key_flags</refname>
<refpurpose>
key flags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum ieee80211_key_flags {
IEEE80211_KEY_FLAG_WMM_STA,
IEEE80211_KEY_FLAG_GENERATE_IV,
IEEE80211_KEY_FLAG_GENERATE_MMIC,
IEEE80211_KEY_FLAG_PAIRWISE,
IEEE80211_KEY_FLAG_SW_MGMT
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>IEEE80211_KEY_FLAG_WMM_STA</term>
<listitem><para>
Set by mac80211, this flag indicates
that the STA this key will be used with could be using QoS.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_KEY_FLAG_GENERATE_IV</term>
<listitem><para>
This flag should be set by the
driver to indicate that it requires IV generation for this
particular key.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_KEY_FLAG_GENERATE_MMIC</term>
<listitem><para>
This flag should be set by
the driver for a TKIP key if it requires Michael MIC
generation in software.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_KEY_FLAG_PAIRWISE</term>
<listitem><para>
Set by mac80211, this flag indicates
that the key is pairwise rather then a shared key.
</para></listitem>
</varlistentry>
<varlistentry> <term>IEEE80211_KEY_FLAG_SW_MGMT</term>
<listitem><para>
This flag should be set by the driver for a
CCMP key if it requires CCMP encryption of management frames (MFP) to
be done in software.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
These flags are used for communication about keys between the driver
and mac80211, with the <parameter>flags</parameter> parameter of <structname>struct ieee80211_key_conf</structname>.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="powersave">
<title>Powersave support</title>
<para>
</para><para>
mac80211 has support for various powersave implementations.
</para><para>
First, it can support hardware that handles all powersaving by
itself, such hardware should simply set the <constant>IEEE80211_HW_SUPPORTS_PS</constant>
hardware flag. In that case, it will be told about the desired
powersave mode depending on the association status, and the driver
must take care of sending nullfunc frames when necessary, i.e. when
entering and leaving powersave mode. The driver is required to look at
the AID in beacons and signal to the AP that it woke up when it finds
traffic directed to it. This mode supports dynamic PS by simply
enabling/disabling PS.
</para><para>
Additionally, such hardware may set the <constant>IEEE80211_HW_SUPPORTS_DYNAMIC_PS</constant>
flag to indicate that it can support dynamic PS mode itself (see below).
</para><para>
Other hardware designs cannot send nullfunc frames by themselves and also
need software support for parsing the TIM bitmap. This is also supported
by mac80211 by combining the <constant>IEEE80211_HW_SUPPORTS_PS</constant> and
<constant>IEEE80211_HW_PS_NULLFUNC_STACK</constant> flags. The hardware is of course still
required to pass up beacons. The hardware is still required to handle
waking up for multicast traffic; if it cannot the driver must handle that
as best as it can, mac80211 is too slow.
</para><para>
Dynamic powersave mode is an extension to normal powersave mode in which
the hardware stays awake for a user-specified period of time after sending
a frame so that reply frames need not be buffered and therefore delayed
to the next wakeup. This can either be supported by hardware, in which case
the driver needs to look at the <parameter>dynamic_ps_timeout</parameter> hardware configuration
value, or by the stack if all nullfunc handling is in the stack.
</para>
</chapter>
<chapter id="beacon-filter">
<title>Beacon filter support</title>
<para>
</para><para>
Some hardware have beacon filter support to reduce host cpu wakeups
which will reduce system power consumption. It usuallly works so that
the firmware creates a checksum of the beacon but omits all constantly
changing elements (TSF, TIM etc). Whenever the checksum changes the
beacon is forwarded to the host, otherwise it will be just dropped. That
way the host will only receive beacons where some relevant information
(for example ERP protection or WMM settings) have changed.
</para><para>
Beacon filter support is advertised with the <constant>IEEE80211_HW_BEACON_FILTER</constant>
hardware capability. The driver needs to enable beacon filter support
whenever power save is enabled, that is <constant>IEEE80211_CONF_PS</constant> is set. When
power save is enabled, the stack will not check for beacon loss and the
driver needs to notify about loss of beacons with <function>ieee80211_beacon_loss</function>.
</para><para>
The time (or number of beacons missed) until the firmware notifies the
driver of a beacon loss event (which in turn causes the driver to call
<function>ieee80211_beacon_loss</function>) should be configurable and will be controlled
by mac80211 and the roaming algorithm in the future.
</para><para>
Since there may be constantly changing information elements that nothing
in the software stack cares about, we will, in the future, have mac80211
tell the driver which information elements are interesting in the sense
that we want to see changes in them. This will include
- a list of information element IDs
- a list of OUIs for the vendor information element
</para><para>
Ideally, the hardware would filter out any beacons without changes in the
requested elements, but if it cannot support that it may, at the expense
of some efficiency, filter out only a subset. For example, if the device
doesn't support checking for OUIs it should pass up all changes in all
vendor information elements.
</para><para>
Note that change, for the sake of simplification, also includes information
elements appearing or disappearing from the beacon.
</para><para>
Some hardware supports an <quote>ignore list</quote> instead, just make sure nothing
that was requested is on the ignore list, and include commonly changing
information element IDs in the ignore list, for example 11 (BSS load) and
the various vendor-assigned IEs with unknown contents (128, 129, 133-136,
149, 150, 155, 156, 173, 176, 178, 179, 219); for forward compatibility
it could also include some currently unused IDs.
</para><para>
</para><para>
In addition to these capabilities, hardware should support notifying the
host of changes in the beacon RSSI. This is relevant to implement roaming
when no traffic is flowing (when traffic is flowing we see the RSSI of
the received data packets). This can consist in notifying the host when
the RSSI changes significantly or when it drops below or rises above
configurable thresholds. In the future these thresholds will also be
configured by mac80211 (which gets them from userspace) to implement
them as the roaming algorithm requires.
</para><para>
If the hardware cannot implement this, the driver should ask it to
periodically pass beacon frames to the host so that software can do the
signal strength threshold checking.
</para>
<refentry id="API-ieee80211-beacon-loss">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_beacon_loss</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_beacon_loss</refname>
<refpurpose>
inform hardware does not receive beacons
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_beacon_loss </function></funcdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
When beacon filtering is enabled with IEEE80211_HW_BEACON_FILTERING and
IEEE80211_CONF_PS is set, the driver needs to inform whenever the
hardware is not receiving beacons with this function.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="qos">
<title>Multiple queues and QoS support</title>
<para>TBD</para>
<refentry id="API-struct-ieee80211-tx-queue-params">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_tx_queue_params</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_tx_queue_params</refname>
<refpurpose>
transmit queue configuration
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_tx_queue_params {
u16 txop;
u16 cw_min;
u16 cw_max;
u8 aifs;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>txop</term>
<listitem><para>
maximum burst time in units of 32 usecs, 0 meaning disabled
</para></listitem>
</varlistentry>
<varlistentry> <term>cw_min</term>
<listitem><para>
minimum contention window [a value of the form
2^n-1 in the range 1..32767]
</para></listitem>
</varlistentry>
<varlistentry> <term>cw_max</term>
<listitem><para>
maximum contention window [like <parameter>cw_min</parameter>]
</para></listitem>
</varlistentry>
<varlistentry> <term>aifs</term>
<listitem><para>
arbitration interframe space [0..255]
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
The information provided in this structure is required for QoS
transmit queue configuration. Cf. IEEE 802.11 7.3.2.29.
</para>
</refsect1>
</refentry>
<refentry id="API-struct-ieee80211-tx-queue-stats">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct ieee80211_tx_queue_stats</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct ieee80211_tx_queue_stats</refname>
<refpurpose>
transmit queue statistics
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct ieee80211_tx_queue_stats {
unsigned int len;
unsigned int limit;
unsigned int count;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>len</term>
<listitem><para>
number of packets in queue
</para></listitem>
</varlistentry>
<varlistentry> <term>limit</term>
<listitem><para>
queue length limit
</para></listitem>
</varlistentry>
<varlistentry> <term>count</term>
<listitem><para>
number of frames sent
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
</refentry>
</chapter>
<chapter id="AP">
<title>Access point mode support</title>
<para>TBD</para>
<para>Some parts of the if_conf should be discussed here instead</para>
<para>
Insert notes about VLAN interfaces with hw crypto here or
in the hw crypto chapter.
</para>
<refentry id="API-ieee80211-get-buffered-bc">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_get_buffered_bc</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_get_buffered_bc</refname>
<refpurpose>
accessing buffered broadcast and multicast frames
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct sk_buff * <function>ieee80211_get_buffered_bc </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer as obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
Function for accessing buffered broadcast and multicast frames. If
hardware/firmware does not implement buffering of broadcast/multicast
frames when power saving is used, 802.11 code buffers them in the host
memory. The low-level driver uses this function to fetch next buffered
frame. In most cases, this is used when generating beacon frame. This
function returns a pointer to the next buffered skb or NULL if no more
buffered frames are available.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
buffered frames are returned only after DTIM beacon frame was
generated with <function>ieee80211_beacon_get</function> and the low-level driver must thus
call <function>ieee80211_beacon_get</function> first. <function>ieee80211_get_buffered_bc</function> returns
NULL if the previous generated beacon was not DTIM, so the low-level driver
does not need to check for DTIM beacons separately and should be able to
use common code for all beacons.
</para>
</refsect1>
</refentry>
<refentry id="API-ieee80211-beacon-get">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_beacon_get</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_beacon_get</refname>
<refpurpose>
beacon generation function
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>struct sk_buff * <function>ieee80211_beacon_get </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>struct ieee80211_vif * <parameter>vif</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
pointer obtained from <function>ieee80211_alloc_hw</function>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>vif</parameter></term>
<listitem>
<para>
<structname>struct ieee80211_vif</structname> pointer from <structname>struct ieee80211_if_init_conf</structname>.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
If the beacon frames are generated by the host system (i.e., not in
hardware/firmware), the low-level driver uses this function to receive
the next beacon frame from the 802.11 code. The low-level is responsible
for calling this function before beacon data is needed (e.g., based on
hardware interrupt). Returned skb is used only once and low-level driver
is responsible for freeing it.
</para>
</refsect1>
</refentry>
</chapter>
<chapter id="multi-iface">
<title>Supporting multiple virtual interfaces</title>
<para>TBD</para>
<para>
Note: WDS with identical MAC address should almost always be OK
</para>
<para>
Insert notes about having multiple virtual interfaces with
different MAC addresses here, note which configurations are
supported by mac80211, add notes about supporting hw crypto
with it.
</para>
</chapter>
<chapter id="hardware-scan-offload">
<title>Hardware scan offload</title>
<para>TBD</para>
<refentry id="API-ieee80211-scan-completed">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>ieee80211_scan_completed</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ieee80211_scan_completed</refname>
<refpurpose>
completed hardware scan
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<funcsynopsis><funcprototype>
<funcdef>void <function>ieee80211_scan_completed </function></funcdef>
<paramdef>struct ieee80211_hw * <parameter>hw</parameter></paramdef>
<paramdef>bool <parameter>aborted</parameter></paramdef>
</funcprototype></funcsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Arguments</title>
<variablelist>
<varlistentry>
<term><parameter>hw</parameter></term>
<listitem>
<para>
the hardware that finished the scan
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><parameter>aborted</parameter></term>
<listitem>
<para>
set to true if scan was aborted
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
When hardware scan offload is used (i.e. the <function>hw_scan</function> callback is
assigned) this function needs to be called by the driver to notify
mac80211 that the scan finished. This function can be called from
any context, including hardirq context.
</para>
</refsect1>
</refentry>
</chapter>
</part>
<part id="rate-control">
<title>Rate control interface</title>
<partintro>
<para>TBD</para>
<para>
This part of the book describes the rate control algorithm
interface and how it relates to mac80211 and drivers.
</para>
</partintro>
<chapter id="dummy">
<title>dummy chapter</title>
<para>TBD</para>
</chapter>
</part>
<part id="internal">
<title>Internals</title>
<partintro>
<para>TBD</para>
<para>
This part of the book describes mac80211 internals.
</para>
</partintro>
<chapter id="key-handling">
<title>Key handling</title>
<sect1>
<title>Key handling basics</title>
<para>
</para><para>
Key handling in mac80211 is done based on per-interface (sub_if_data)
keys and per-station keys. Since each station belongs to an interface,
each station key also belongs to that interface.
</para><para>
Hardware acceleration is done on a best-effort basis, for each key
that is eligible the hardware is asked to enable that key but if
it cannot do that they key is simply kept for software encryption.
There is currently no way of knowing this except by looking into
debugfs.
</para><para>
All key operations are protected internally so you can call them at
any time.
</para><para>
Within mac80211, key references are, just as STA structure references,
protected by RCU. Note, however, that some things are unprotected,
namely the key->sta dereferences within the hardware acceleration
functions. This means that <function>sta_info_destroy</function> must flush the key todo
list.
</para><para>
All the direct key list manipulation functions must not sleep because
they can operate on STA info structs that are protected by RCU.
</para>
</sect1>
<sect1>
<title>MORE TBD</title>
<para>TBD</para>
</sect1>
</chapter>
<chapter id="rx-processing">
<title>Receive processing</title>
<para>TBD</para>
</chapter>
<chapter id="tx-processing">
<title>Transmit processing</title>
<para>TBD</para>
</chapter>
<chapter id="sta-info">
<title>Station info handling</title>
<sect1>
<title>Programming information</title>
<refentry id="API-struct-sta-info">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>struct sta_info</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>struct sta_info</refname>
<refpurpose>
STA information
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
struct sta_info {
struct list_head list;
struct sta_info * hnext;
struct ieee80211_local * local;
struct ieee80211_sub_if_data * sdata;
struct ieee80211_key * key;
struct rate_control_ref * rate_ctrl;
void * rate_ctrl_priv;
spinlock_t lock;
spinlock_t flaglock;
u16 listen_interval;
bool dead;
bool uploaded;
u32 flags;
struct sk_buff_head ps_tx_buf;
struct sk_buff_head tx_filtered;
unsigned long rx_packets;
unsigned long rx_bytes;
unsigned long wep_weak_iv_count;
unsigned long last_rx;
unsigned long num_duplicates;
unsigned long rx_fragments;
unsigned long rx_dropped;
int last_signal;
int last_qual;
int last_noise;
__le16 last_seq_ctrl[NUM_RX_DATA_QUEUES];
unsigned long tx_filtered_count;
unsigned long tx_retry_failed;
unsigned long tx_retry_count;
unsigned int fail_avg;
unsigned long tx_packets;
unsigned long tx_bytes;
unsigned long tx_fragments;
struct ieee80211_tx_rate last_tx_rate;
u16 tid_seq[IEEE80211_QOS_CTL_TID_MASK + 1];
struct sta_ampdu_mlme ampdu_mlme;
u8 timer_to_tid[STA_TID_NUM];
#ifdef CONFIG_MAC80211_MESH
__le16 llid;
__le16 plid;
__le16 reason;
u8 plink_retries;
bool ignore_plink_timer;
bool plink_timer_was_running;
enum plink_state plink_state;
u32 plink_timeout;
struct timer_list plink_timer;
#endif
#ifdef CONFIG_MAC80211_DEBUGFS
struct sta_info_debugfsdentries debugfs;
#endif
struct ieee80211_sta sta;
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Members</title>
<variablelist>
<varlistentry> <term>list</term>
<listitem><para>
global linked list entry
</para></listitem>
</varlistentry>
<varlistentry> <term>hnext</term>
<listitem><para>
hash table linked list pointer
</para></listitem>
</varlistentry>
<varlistentry> <term>local</term>
<listitem><para>
pointer to the global information
</para></listitem>
</varlistentry>
<varlistentry> <term>sdata</term>
<listitem><para>
virtual interface this station belongs to
</para></listitem>
</varlistentry>
<varlistentry> <term>key</term>
<listitem><para>
peer key negotiated with this station, if any
</para></listitem>
</varlistentry>
<varlistentry> <term>rate_ctrl</term>
<listitem><para>
rate control algorithm reference
</para></listitem>
</varlistentry>
<varlistentry> <term>rate_ctrl_priv</term>
<listitem><para>
rate control private per-STA pointer
</para></listitem>
</varlistentry>
<varlistentry> <term>lock</term>
<listitem><para>
used for locking all fields that require locking, see comments
in the header file.
</para></listitem>
</varlistentry>
<varlistentry> <term>flaglock</term>
<listitem><para>
spinlock for flags accesses
</para></listitem>
</varlistentry>
<varlistentry> <term>listen_interval</term>
<listitem><para>
listen interval of this station, when we're acting as AP
</para></listitem>
</varlistentry>
<varlistentry> <term>dead</term>
<listitem><para>
set to true when sta is unlinked
</para></listitem>
</varlistentry>
<varlistentry> <term>uploaded</term>
<listitem><para>
set to true when sta is uploaded to the driver
<parameter>drv_unblock_wk</parameter> used for driver PS unblocking
</para></listitem>
</varlistentry>
<varlistentry> <term>flags</term>
<listitem><para>
STA flags, see <structname>enum</structname> ieee80211_sta_info_flags
</para></listitem>
</varlistentry>
<varlistentry> <term>ps_tx_buf</term>
<listitem><para>
buffer of frames to transmit to this station
when it leaves power saving state
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_filtered</term>
<listitem><para>
buffer of frames we already tried to transmit
but were filtered by hardware due to STA having entered
power saving state
</para></listitem>
</varlistentry>
<varlistentry> <term>rx_packets</term>
<listitem><para>
Number of MSDUs received from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>rx_bytes</term>
<listitem><para>
Number of bytes received from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>wep_weak_iv_count</term>
<listitem><para>
number of weak WEP IVs received from this station
</para></listitem>
</varlistentry>
<varlistentry> <term>last_rx</term>
<listitem><para>
time (in jiffies) when last frame was received from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>num_duplicates</term>
<listitem><para>
number of duplicate frames received from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>rx_fragments</term>
<listitem><para>
number of received MPDUs
</para></listitem>
</varlistentry>
<varlistentry> <term>rx_dropped</term>
<listitem><para>
number of dropped MPDUs from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>last_signal</term>
<listitem><para>
signal of last received frame from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>last_qual</term>
<listitem><para>
qual of last received frame from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>last_noise</term>
<listitem><para>
noise of last received frame from this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>last_seq_ctrl[NUM_RX_DATA_QUEUES]</term>
<listitem><para>
last received seq/frag number from this STA (per RX queue)
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_filtered_count</term>
<listitem><para>
number of frames the hardware filtered for this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_retry_failed</term>
<listitem><para>
number of frames that failed retry
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_retry_count</term>
<listitem><para>
total number of retries for frames to this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>fail_avg</term>
<listitem><para>
moving percentage of failed MSDUs
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_packets</term>
<listitem><para>
number of RX/TX MSDUs
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_bytes</term>
<listitem><para>
number of bytes transmitted to this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>tx_fragments</term>
<listitem><para>
number of transmitted MPDUs
</para></listitem>
</varlistentry>
<varlistentry> <term>last_tx_rate</term>
<listitem><para>
rate used for last transmit, to report to userspace as
<quote>the</quote> transmit rate
</para></listitem>
</varlistentry>
<varlistentry> <term>tid_seq[IEEE80211_QOS_CTL_TID_MASK + 1]</term>
<listitem><para>
per-TID sequence numbers for sending to this STA
</para></listitem>
</varlistentry>
<varlistentry> <term>ampdu_mlme</term>
<listitem><para>
A-MPDU state machine state
</para></listitem>
</varlistentry>
<varlistentry> <term>timer_to_tid[STA_TID_NUM]</term>
<listitem><para>
identity mapping to ID timers
</para></listitem>
</varlistentry>
<varlistentry> <term>llid</term>
<listitem><para>
Local link ID
</para></listitem>
</varlistentry>
<varlistentry> <term>plid</term>
<listitem><para>
Peer link ID
</para></listitem>
</varlistentry>
<varlistentry> <term>reason</term>
<listitem><para>
Cancel reason on PLINK_HOLDING state
</para></listitem>
</varlistentry>
<varlistentry> <term>plink_retries</term>
<listitem><para>
Retries in establishment
</para></listitem>
</varlistentry>
<varlistentry> <term>ignore_plink_timer</term>
<listitem><para>
ignore the peer-link timer (used internally)
</para></listitem>
</varlistentry>
<varlistentry> <term>plink_timer_was_running</term>
<listitem><para>
used by suspend/resume to restore timers
</para></listitem>
</varlistentry>
<varlistentry> <term>plink_state</term>
<listitem><para>
peer link state
</para></listitem>
</varlistentry>
<varlistentry> <term>plink_timeout</term>
<listitem><para>
timeout of peer link
</para></listitem>
</varlistentry>
<varlistentry> <term>plink_timer</term>
<listitem><para>
peer link watch timer
</para></listitem>
</varlistentry>
<varlistentry> <term>debugfs</term>
<listitem><para>
debug filesystem info
</para></listitem>
</varlistentry>
<varlistentry> <term>sta</term>
<listitem><para>
station information we share with the driver
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
This structure collects information about a station that
mac80211 is communicating with.
</para>
</refsect1>
</refentry>
<refentry id="API-enum-ieee80211-sta-info-flags">
<refentryinfo>
<title>LINUX</title>
<productname>Kernel Hackers Manual</productname>
<date>October 2011</date>
</refentryinfo>
<refmeta>
<refentrytitle><phrase>enum ieee80211_sta_info_flags</phrase></refentrytitle>
<manvolnum>9</manvolnum>
<refmiscinfo class="version">2.6.32</refmiscinfo>
</refmeta>
<refnamediv>
<refname>enum ieee80211_sta_info_flags</refname>
<refpurpose>
Stations flags
</refpurpose>
</refnamediv>
<refsynopsisdiv>
<title>Synopsis</title>
<programlisting>
enum ieee80211_sta_info_flags {
WLAN_STA_AUTH,
WLAN_STA_ASSOC,
WLAN_STA_PS_STA,
WLAN_STA_AUTHORIZED,
WLAN_STA_SHORT_PREAMBLE,
WLAN_STA_ASSOC_AP,
WLAN_STA_WME,
WLAN_STA_WDS,
WLAN_STA_CLEAR_PS_FILT,
WLAN_STA_MFP,
WLAN_STA_SUSPEND,
WLAN_STA_PS_DRIVER,
WLAN_STA_PSPOLL
}; </programlisting>
</refsynopsisdiv>
<refsect1>
<title>Constants</title>
<variablelist>
<varlistentry> <term>WLAN_STA_AUTH</term>
<listitem><para>
Station is authenticated.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_ASSOC</term>
<listitem><para>
Station is associated.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_PS_STA</term>
<listitem><para>
Station is in power-save mode
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_AUTHORIZED</term>
<listitem><para>
Station is authorized to send/receive traffic.
This bit is always checked so needs to be enabled for all stations
when virtual port control is not in use.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_SHORT_PREAMBLE</term>
<listitem><para>
Station is capable of receiving short-preamble
frames.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_ASSOC_AP</term>
<listitem><para>
We're associated to that station, it is an AP.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_WME</term>
<listitem><para>
Station is a QoS-STA.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_WDS</term>
<listitem><para>
Station is one of our WDS peers.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_CLEAR_PS_FILT</term>
<listitem><para>
Clear PS filter in hardware (using the
IEEE80211_TX_CTL_CLEAR_PS_FILT control flag) when the next
frame to this station is transmitted.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_MFP</term>
<listitem><para>
Management frame protection is used with this STA.
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_SUSPEND</term>
<listitem><para>
Set/cleared during a suspend/resume cycle.
Used to deny ADDBA requests (both TX and RX).
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_PS_DRIVER</term>
<listitem><para>
driver requires keeping this station in
power-save mode logically to flush frames that might still
be in the queues
</para></listitem>
</varlistentry>
<varlistentry> <term>WLAN_STA_PSPOLL</term>
<listitem><para>
Station sent PS-poll while driver was keeping
station in power-save mode, reply when the driver unblocks.
</para></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Description</title>
<para>
</para><para>
These flags are used with <structname>struct sta_info</structname>'s <parameter>flags</parameter> member.
</para>
</refsect1>
</refentry>
</sect1>
<sect1>
<title>STA information lifetime rules</title>
<para>
</para><para>
STA info structures (<structname>struct sta_info</structname>) are managed in a hash table
for faster lookup and a list for iteration. They are managed using
RCU, i.e. access to the list and hash table is protected by RCU.
</para><para>
Upon allocating a STA info structure with <function>sta_info_alloc</function>, the caller
owns that structure. It must then insert it into the hash table using
either <function>sta_info_insert</function> or <function>sta_info_insert_rcu</function>; only in the latter
case (which acquires an rcu read section but must not be called from
within one) will the pointer still be valid after the call. Note that
the caller may not do much with the STA info before inserting it, in
particular, it may not start any mesh peer link management or add
encryption keys.
</para><para>
When the insertion fails (<function>sta_info_insert</function>) returns non-zero), the
structure will have been freed by <function>sta_info_insert</function>!
</para><para>
Station entries are added by mac80211 when you establish a link with a
peer. This means different things for the different type of interfaces
we support. For a regular station this mean we add the AP sta when we
receive an assocation response from the AP. For IBSS this occurs when
get to know about a peer on the same IBSS. For WDS we add the sta for
the peer imediately upon device open. When using AP mode we add stations
for each respective station upon request from userspace through nl80211.
</para><para>
In order to remove a STA info structure, various sta_info_destroy_*()
calls are available.
</para><para>
There is no concept of ownership on a STA entry, each structure is
owned by the global hash table/list until it is removed. All users of
the structure need to be RCU protected so that the structure won't be
freed before they are done using it.
</para>
</sect1>
</chapter>
<chapter id="synchronisation">
<title>Synchronisation</title>
<para>TBD</para>
<para>Locking, lots of RCU</para>
</chapter>
</part>
</book>
