<?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>June 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>June 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>June 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>June 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>June 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 addition, removal or 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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 }; </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> </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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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>June 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. </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>June 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; u8 pin_status; 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>pin_status</term> <listitem><para> used internally for pinning a STA struct into memory </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>June 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, 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 }; </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</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> </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 either destroy it using <function>sta_info_destroy</function> (which is pretty useless) or insert it into the hash table using <function>sta_info_insert</function> which demotes the reference from ownership to a regular RCU-protected reference; if the function is called without protection by an RCU critical section the reference is instantly invalidated. 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> sta 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 we receive a probe response or a beacon from target IBSS network. 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> Because there are debugfs entries for each station, and adding those must be able to sleep, it is also possible to <quote>pin</quote> a station entry, that means it can be removed from the hash table but not be freed. See the comment in <function>__sta_info_unlink</function> for more information, this is an internal capability only. </para><para> In order to remove a STA info structure, the caller needs to first unlink it (<function>sta_info_unlink</function>) from the list and hash tables and then destroy it; <function>sta_info_destroy</function> will wait for an RCU grace period to elapse before actually freeing it. Due to the pinning and the possibility of multiple callers trying to remove the same STA info at the same time, <function>sta_info_unlink</function> can clear the STA info pointer it is passed to indicate that the STA info is owned by somebody else now. </para><para> If <function>sta_info_unlink</function> did not clear the pointer then the caller owns the STA info structure now and is responsible of destroying it with a call to <function>sta_info_destroy</function>. </para><para> In all other cases, 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>