ieee80211 package
Information on this package is covered here.
|
Package
|
Description
|
License
|
|
ieee80211
|
Devicescape 802.11 stack for DataPath driver.
|
Devicescape Software, Inc.
|
(For information on modifying/extending this package, see the "DataPath Driver" topic in the Developer Guide.)
Summary
The Devicescape DataPath driver is the software that controls the radio hardware on the target device on which the runtime system is deployed. The DataPath driver provides a well-defined interface between the higher-level Access Point or wireless client functions and the low-level radio drivers.
Usage
Start/Stop Options
Use the following commands to control the DataPath driver (ieee80211) on the target device.
|
Action
|
Command
|
|
Start
|
/etc/init.d/ieee80211 start
|
|
Stop
|
/etc/init.d/ieee80211 stop
|
|
Restart
|
/etc/init.d/ieee80211 restart
|
There are no parameters defined for this script.
Runtime Configuration
The Devicescape 80211.o module uses hostapd for Access Point configuration. (See hostapd package).
External APIs
The Devicescape DataPath driver 80211.o module provides an external interface for user programs. Examples of programs that use the external API of the 80211.o module are:
Debugging (80211.o module procfs tree)
The 80211.o module provides a procfs tree for easy access to configuration and statistics information of data collected within kernel module.
The root of 80211.o procfs tree is /proc/net/ieee80211. Each radio interface has its own subtree in this directory. The name of the subtree root directory is the same as the main netdevice of that interface (wlan#); for example, /proc/net/ieee80211/wlan0.
For example, the following files show radio specific information for the wlan0 interface for an Access Point in /proc/net/ieee80211/wlan0:
configcountersdebugifacemulticastratessta
|
Note
|
- This procfs interface is designed primarily for debugging use and, therefore, does not include information that is collected in user space hostapd process. In future releases, some functionality may be moved from 80211.o into hostapd and the related information will at that point be removed from the
procfs tree.
- In the following sections, the various data values are shown the way they will appear in the file, with example values (for example, "
channel=11").
|
Radio Interface Specific Files (/proc/net/ieee80211/wlan#/*)
config
tx_power_reduction=0.0 dBm
fragmentation_threshold=2346
counters
TransmittedFragmentCount=2000
MulticastTransmittedFrameCount=303
ReceivedFragmentCount=1298
MulticastReceivedFrameCount=1227
TransmittedFrameCount=888
Virtual Interface Specific Files (/proc/net/ieee80211/wlan#/iface/*)
Each virtual interface; for example, wlan# for the default data interface and each virtual interface configured in multi_ssid blocks of hostapd.conf, has its own file that contain generic information about the interface. This includes interface type (norm/wds/vlan) and default (broadcast) encryption algorithm and keys (if in use).
Following are some typical entries in an example file:
drop_unencrypted=0
<Optional_Encryption_Key_Entries>
Here are the details on most options and values in the above example file:
|
Example
|
Description
|
|
channel_use=0
|
Estimated channel (air time) use of this interface in 1/1000. (For example, 10 = 1 percent.)
|
|
drop_unencrypted=0
|
Drop all unencrypted TX and RX frames from this interface.
|
|
key[<idx]>[*] len=<len> sw_encrypt=<val> idx=<val>
hwidx =<val> tx_rx_count=<val> alg=<str> ... [alg specific data]
|
Optional encryption key entries (default/broadcast keys)
|
Station Information (/proc/net/ieee80211/wlan#/sta/*)
Each associated station has its own file (with the hardware/MAC address as the file name) that includes state information and statistics. Stations that are not associated are not in the 80211.o station table and, consequently, they do not have procfs entry. These stations may have an entry in the hostapd tables and, if so, that information is available through the hostapd interface. (See hostapd package.)
xx:xx:xx:xx:xx:xx (for example, FE:DC:BA:09:87:65)
Following is the contents of an example STA file (named <SomeMACAddress>) in /proc/net/ieee80211/wlan#/sta/. Parameters and values found in this file are described below.
flags=0xa3 [AUTH][ASSOC][AUTHORIZED][SHORT PREAMBLE]
key[0]* len=32 sw_encrypt=0 idx=0 hwidx=1 tx_rx_count=2 alg=TKIP
iv(tx)=00000000 0001 iv(rx 0)=00000000 0001
key=d60eff2f44369a8147e90ce9d8dda0a6fd4a8c6fe16fa2394c9fe4363db37970
wme_rx_queue=4 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
wme_tx_queue=0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
last_seq_ctrl=680 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0
rate: num_tx / rssi_thresh / MPDU not ACKed (%)
Here are the details on most options and values in the above example file:
|
Example
|
Description
|
|
flags=0x3 [AUTH][ASSOC][AUTHORIZED]
[SHORT PREAMBLE]
|
Station flags:
- AUTH=authenticated
- ASSOC=associated
- AUTHORIZED=IEEE 802.1X authorized
- PS=in power saving mode
- TIM=buffered frame pending for STA in PS mode
|
|
dev=wlan0
|
Data device to which this station is bound
|
|
rx_packets=3
|
Number of received packets (MSDU)
|
|
tx_packets=3
|
Number of transmitted packets (MSDU)
|
|
rx_bytes=439
|
Number of received bytes
|
|
tx_bytes=459
|
Number of transmitted packets
|
|
rx_duplicates=1
|
Number of received MPDUs that were dropped because they were duplicates.
|
|
rx_fragments=3
|
Number of received fragments (MPDU
|
|
rx_dropped=1
|
Number of received MPDUs that were dropped for any reason (for example, duplicates and failed decryption).
|
|
tx_fragments=3
|
Number of transmitted fragments (MPDU)
|
|
txrate=55
|
Current transmission rate (for AP-to-STA transmissions) in 100 kbps. For example, 55 = 5.5 Mbps.
|
|
tx_avg_rate_avg=37
|
Transmission rate average value
|
|
num_ps_buf_frames=0
|
Number of buffered frames for this station (power saving mode)
|
|
tx_retry_failed=0
|
Number of times transmission failed due to excessive retries
|
|
tx_retry_count=1
|
Total number of retries used for TX packets
|
|
last_rssi=51
|
Received Signal Strength Indication (RSSI) of the last received frame
|
|
last_ack_rssi=40 35 35
|
RSSI of the last received frame
|
|
last_ack_rssi=61
|
RSSI of the acknowledgement ACK to the last sent Unicast frame
|
|
inactive_msec=6560
|
Number of milliseconds from the last received frame
|
|
channel_use=0
|
Estimated channel (air time) use of this STA in 1/1000. (For example, 10 = 1 percent.)
|
IEEE 802.11 QoS and Linux QoS
The IEEE 802.11 implementation from Devicescape supports quality of service (QoS) by allowing multiple hardware transmit queues to be used. Each transmit queue can have a different configuration of EDCA and bursting parameters. See the example hostapd configuration file (hostapd/hostapd.conf) for more information about transmit queue configuration (tx_queue_data* items in that file).
IEEE 802.11 QoS is tightly integrated into standard Linux QoS mechanisms to enable advanced packet classification and traffic shaping. Together, these allow versatile options for QoS configuration of an IEEE 802.11 access point, and full Wi-Fi Wireless Multimedia Extensions (WMM) compliance.
The following topics are covered here:
Documentation for Linux QoS
Detailed background information about Linux networking and QoS is available in "Linux Advanced Routing & Traffic Control HOWTO", available at http://lartc.org/howto/.
In particular the reader is expected to be familiar with the use of qdiscs in general. An understanding of all the specific queuing algorithms (CBQ, RED, and so on) is not required - but familiarity with the operation of the prio and fifo qdiscs, and filters is a prerequisite. In particular the Devicescape 802.11 QoS is based on a classful queuing discipline. These are described in section 9.5(Classful Queuing Disciplines) of the LARTC guide. Sections 9.5 through 9.5.3.2, and 9.6 through 9.6.2 inclusive are required reading. The reader should have a good understanding of the use and configuration of both classful qdiscs and filters before proceeding with this document.
In addition if the reader will be implementing an AP which can prioritize based on 802.1q priority tags then an understanding of the Linux ebtables mechanism is required. Understanding the full use of ebtables for brouter construction, and mixed L2/L3 nat functionality is not required, however an understanding of the basic packet flow through the ebtables chains and the bridge is required. Documentation on this can be found in the Devicescape guide "Linux Layer 2 Frame Handling" and also at http://ebtables.sourceforge.net/.
Kernel / Module requirements
Example configuration uses Linux QoS implementation, which needs to be enabled in the kernel configuration. At least following options are needed for this example:
- CONFIG_NET_SCHED
- CONFIG_NET_QOS
- CONFIG_NET_CLS
- CONFIG_NET_CLS_FW
- CONFIG_NET_CLS_U32
If the 802.1q priority tags are to be supported then the kernel requires ebtables functionality (ebtables is a filtering tool for a bridging firewall). In the Linux 2.4 kernel series this is available as a patch to be applied to the kernel sources. This patch may be downloaded from the ebtables sourceforge Website, and is only available for certain kernel versions. In this example we are using kernel 2.4.21. Linux 2.6 series kernels have ebtables built in.
|
Note
|
Devicescape Wireless Infrastructure Platform supplies the Linux kernel pre-patched with ebtables support. See ebtables package listed in Quick View of Packages.
|
In addition to ebtables support the Devicescape module "strip1q" is required to be loaded to provide 802.1q priority tag based prioritization.
ebtables is not required simply to prioritize based on normal VLA.
User Space Requirements
The Linux "tc" utility is used to set up, control and monitor the kernel qdiscs. A patched version of this command is included with this distribution. The tc utility has been extended to be able to configure the Devicescape 802.11 qdisc.
The Linux "ebtables" utility is used to set up, control and monitor the kernel ebtables functionality. A patched version of this command is included with this distribution. The ebtables utility has been extended to be able to configure the Devicescape strip1q ebtables target.
Architecture
In the Devicescape architecture each physical 802.11 radio has multiple Linux virtual interface devices. The radio will have a single master device. This is typically named wlan0.11. This device requires 802.11 format frames, and hence cannot be directly used by the built in Linux protocol stacks. Each separate broadcast domain (SSID, BSSID or wireless VLAN) is assigned a Linux interface, which accepts Ethernet type frames. For example a simple access point with 1 SSID would have an interface wlan0. This is the interface the built in Linux protocol stacks use to transmit frames. Internally the Devicescape wireless subsystem takes these Ethernet frames, converts them into 802.11 frames, and then calls back to the Linux kernel to transmit the frames on the 802.11 format master interface. These multiple Ethernet format interfaces do not perform any queuing (they are 'virtual' interfaces), and are not involved in any QoS operations. There is only one single queue per radio and this is on the master interface.
See the Devicescape Guide "Linux Layer 2 Frame Handling" for more detail.
The 802.11 qdisc
The 802.11 qdisc is implemented by the 80211.o module and so is common to all radios. The 802.11 qdisc operates in a very similar way to the prio qdisc; it only subdivides traffic based on how you configured your filters. The biggest difference from the prio qdisc is that the 802.11 qdisc supports directly feeding multiple hardware output queues.
In order to access any Devicescape QoS features the 802.11 qdisc must be installed as the root qdisc on the master interface. This is done automatically for you when the master interface is created. It is not possible to remove or change this special qdisc.
The 802.11 qdisc directly represents the multiple hardware queues that are available on the radio. It is a classful queuing discipline, and automatically creates a class for each hardware queue. By default each class has a simple fifo queue attached to it; although these are hidden and you do not see them. The classes have these handles:
|
Class ID
|
Description
|
|
:1
|
AC_VO - Voice
|
|
:2
|
AC_VI - Video
|
|
:3
|
AC_BE - Best Effort
|
|
:4
|
AC_BK - Background
|
|
:5
|
Atheros XR data. This is deprecated and may be removed in the future.
|
|
:6
|
SVP - Spectralink Voice Protocol
|
Filters
When frames are sent from the kernel to the 802.11 qdisc (enqueued) they are first classified by whatever filters you installed. The filters select an 802.1p priority to be used for this frame. By installing filters here you can classify certain traffic and ensure a certain 802.1d priority tag be used. If no filter are present, or none match the frame, then a default set of internal filters are used. The internal filters match firstly on magic skb->priority fields. Values of 256->263 map directly to 802.1d tags of 0-7. Next if the frame is IP protocol, then a DSCP value will be checked. DSCP values are mapped to 802.1d priorities as specified in the Wi-Fi WMM test plan. If the frame is IP/SVP protocol then the 802.1d priority of 7 is used, and the frame is sent to the special SVP hardware queue. Finally if no other match is made the frame is assigned a 802.1d priority of "0" or Best Effort.
The class (or hardware queue) the frame is sent to is selected according to the mapping specified in the 802.11e specification.
|
802.1d Priority
|
Class Used
|
|
0
|
:3
|
|
1
|
:4
|
|
2
|
:4
|
|
3
|
:3
|
|
4
|
:2
|
|
5
|
:2
|
|
6
|
:1
|
|
7
|
:1
|
|
IP SVP Frames
|
:6
|
For frames that are sent as an 802.11e or Wi-Fi WMM QOS DATA frame this 802.1d priority will appear in the priority field of the 'qos control' header.
When the hardware has space available in any one of its hardware queues, the 802.11 qdisc dequeues a frame from the matching class. There is a 1-1 mapping between the hardware queues and the classes of the 802.11 qdisc. In this way the classes of the 802.11 qdisc represent queues that feed each of the separate hardware queues.
By default when the 802.11 qdisc is installed, it installs a simple fifo qdisc on each subclass. This fifo qdisc is hidden and will not show up in the output of:
$ tc class show dev wlan0.11
The user can add whatever qdisc, or qdisc hierarchy is required to any of the classes - automatically replacing the default fifo qdisc. For example it may be desirable to prioritize certain traffic within the best effort class. To do this you would add a prio qdisc.
$ tc qdisc add dev wlan0.11 parent 8001:3 prio
IP Filtering Setup
In this example we will send all TCP traffic on port 25 (email) as background.
To do this you must install filters on the 802.11 qdisc that match on the required frame headers, and return appropriate 802.1d priorities. An example script does this:
$ tc filter add dev wlan0.11 parent 8001: protocol ip prio 1 u32 match ip sport 25 0xffff classid :1
$ tc filter add dev wlan0.11 parent 8001: protocol ip prio 1 u32 match ip dport 25 0xffff classid :1
Lets break this example down a little.
"tc filter add dev wlan0.11 parent 8001:..."
This specifies to add a filter to the qdisc on the wlan0.11 device with handle 8001: (the default handle for the 802.11 qdisc is 8001:).
This filter will only match IP traffic. (It's possible to specify 'all' or any ethernet protocol from /etc/protocols)
This filter will be in the first group of filters examined on this qdisc.
"...u32 match ip sport..."
This filter is a match on the IP source port byte. See the LARTC guide for more details on the u32 match.
This matches the source port value of 25. The match is made here by ANDing the whole source port word with 0xffff and comparing with 25.
This specifies that frames matching this rule should be returned to the qdisc with a classid of :1. The 802.11 qdisc will interpret this classid by assigning the frame an 802.1d priority of 1. The qdisc will then use the static 802.1d mapping to determine which hardware queue to use to queue this frame on, and send the frame on the background queue (AC_BK).
802.1q VLAN Tag Setup
In order to prioritize VLAN tagged traffic according to the 802.1d priority specified in the VLAN tags the Linux VLAN code should be set to map the VLAN priorities to skb->priorities of 256-263. After the VLAN decapsulation when the frames finally reach the 802.11 qdisc they will be mapped to the right priority by the default filtering code in the 802.11 qdisc. This example code does this:
$ vconfig set_ingress_map vlan1 256 0
$ vconfig set_ingress_map vlan1 257 1
$ vconfig set_ingress_map vlan1 258 2
$ vconfig set_ingress_map vlan1 259 3
$ vconfig set_ingress_map vlan1 260 4
$ vconfig set_ingress_map vlan1 261 5
$ vconfig set_ingress_map vlan1 262 6
$ vconfig set_ingress_map vlan1 263 7
802.1q Priority Tag Setup
Out of the box Linux 2.4 and 2.6 support 802.1q tags for vlan-id. They do not support 802.1q priority tags - i.e. tags where that vlan-id is set to 0, and the tag is used just to add priority information to the frame. Devicescape adds 802.1q priority tag support through the ebtables strip1q extension. Ebtables is a mechanism which allows packets to be inspected and processed during various stages of forwarding through a Linux Bridge. All packets received on a linux bridge pass through the 'broute chain' before any other processing. To use the strip1q module you add it to the broute chain or nat chain on a Linux bridge that will be forwarding 802.1q priority tagged frames. This command does this:
$ ebtables -t broute -A BROUTING -p 802_1Q --vlan-id 0 -j strip1q
|
Note
|
You must use the provided version of the ebtables user space command. This version has been extended to support the strip1q target.
|
This command registers the Devicescape strip1q module to be called for all frames received on the bridge which have an Ethernet protocol of 802_1Q (as all 802.1q tagged frames do), and where the vlan-id is equal to 0. When the strip1q module receives one of these frames it removes the 802.1q tag from the frame, while recording the priority from the tag in the skb->priority field. The now untagged frame is forwarded by the bridge appropriately. The value in the skb->priority field can be used later on when the frame reaches the 802.11 qdisc to select which wireless hardware queue to use to transmit the frame.
By default the strip1q modules maps 802.1q priority values (0-7) to skb->priority values of 256->263.
Wi-Fi WMM in hostapd.conf
The hostapd.conf file controls three important parts of the WMM implementation.
- The
wme_data parameters control the EDCA parameters that are advertised by the access point in beacons, probe responses and association responses and then used by WMM clients when transmitting data to the access point. See Default QoS Parameters for Clients (STA-to-AP Traffic) in the hostapd package topic in this Guide.
|
Note
|
The wme_data parameters do not control queueing in the access point - they only specify what queueing parameters will be used by WMM clients.
|
For more information on the hostapd package and hostapd.conf file, see the hostapd package topic in the Package Reference Guide.
Terminology
- Wi-Fi's Wireless Multimedia Extensions (WMM). A QoS standard released by Wi-Fi including the EDCA features from the forthcoming 802.11e standard, but not supporting the HCF, and with simplified negotiation. WMM is based on 802.11e draft 7.
- qdisc is the Linux name for a queuing discipline.
Building the Package
Follow standard instructions for building kernel modules in the Devicescape Developer Guide topic on "Building the Packages", see subtopic: "Building a Kernel Module from a Source RPM".
This package requires building a userspace and kernel module from one source RPM, so it must have .tshint file also, like all kernel modules.
Creating a Custom Low-Level Driver
This section describes the interface between the DataPath driver and the low-level radio driver package for developers who want to use a board not currently supported by the Devicescape Wireless Infrastructure Platform and implement their own low-level driver.
Design and Methodology
The Devicescape DataPath driver is the software that controls the radio hardware on the target device on which the runtime system is deployed. The DataPath driver provides a well-defined interface between the higher-level access point functions and the low-level radio drivers.
The DataPath driver is implemented as the kernel module, 80211.o.
To obtain the correct definitions, you must include the ieee80211.h header file in your code.
|
Notes
|
Only ieee80211_tx_status_irqsafe() and ieee80211_rx_irqsave() can be called in hardware interrupt context.The low-level driver must not call any of the DataPath driver interface functions in the context of a hardware interrupt. If there is a need for such call, the low-level driver should first ACK the interrupt and perform the DataPath driver call after this from a scheduled task (for example, in the context of a software interrupt).
The format used when passing frames between the low-level radio drivers and the DataPath driver is the same as used in the wireless media, that is, buffers start with an IEEE 802.11header and include the same octets that are sent over air.
Hardware that uses IEEE 802.3 headers and performs 802.3 to 802.11 conversion in firmware is currently unsupported in the DataPath driver.
Receive frame formats that are not the same as the real frame sent on the wireless media (for example, due to padding) are currently unsupported in the DataPath driver.
|
Data Structures
Transmit Control Fields
The transmit control struct ieee80211_tx_control data structure is passed to low-level driver with each transmitted frame. The low-level driver is responsible for configuring the hardware to use these values to the extent that they are supported by the hardware.
Transmit Status
The transmit status struct ieee80211_tx_status must be provided by the low-level driver to the DataPath driver for each transmitted frame.
Receive Status
The low-level driver must fill in the receive status struct ieee80211_rx_status data structure and pass this information to the DataPath driver with each received frame.
Configuration Block
The struct ieee80211_hw configuration block is used by the low-level driver to tell the DataPath driver about supported hardware features and to pass function pointers for its callback functions.
Some WLAN chipsets generate Beacons in the hardware/firmware. Others rely on host generated beacons. The host_gen_beacon option is used to configure the DataPath driver to generate beacons. The low-level driver can call ieee80211_beacon_gen() to fetch next beacon frame.
Some devices handle decryption internally and do not indicate whether the frame was encrypted (unencrypted frames will be dropped by the hardware, unless specifically allowed through).
Some WLAN chipsets buffer broadcast/multicast frames for power saving stations in the hardware or firmware. Others rely on the host system for such buffering. The host_broadcast_ps_buffering option is used to configure the DataPath driver to buffer broadcast/multicast frames when there are power saving stations so that low-level driver can fetch them with ieee80211_get_buffered_bc().
Handlers
Transmit (tx)
The DataPath driver calls the tx handler for each transmitted frame. skb contains the buffer starting from the 802.11 header. The low-level driver should transmit the frame based on configuration in the Transmit Control Fields.
int (*tx)(struct net_device *dev, struct sk_buff *skb,
struct ieee80211_tx_control *control);
Hardware Reset (reset)
The DataPath driver calls the reset handler to perform a hardware reset.
int (*reset)(struct net_device *dev);
Enable (open)
The DataPath driver calls the open handler when any network device attached to the hardware is set to UP status for the first time. This can be used to enable interrupts and Beacon generation.
int (*open)(struct net_device *dev);
Disable (stop)
The DataPath driver calls the stop handler when any network device attached to the hardware is set to DOWN status for the first time. This can be used to disable interrupts and Beacon generation.
int (*stop)(struct net_device *dev);
Change the Hardware Configuration (config)
The DataPath driver calls the config handler to change the hardware configuration, for example, channel changes.
int (*config)(struct net_device *dev, struct ieee80211_conf *conf);
Set the Traffic Information Map (set_tim)
If the hardware/firmware takes care of Beacon generation, the DataPath driver calls the set_tim handler to tell the low-level driver to set (or clear) the TIM bit for the given Association ID (AID).
If the host system is used to generate Beacons, this handler is not used. The low-level driver should set it to NULL.
int (*set_tim)(struct net_device *dev, int aid, int set);
Set Encryption Keys (set_key)
The DataPath driver calls the set_key handler to set encryption keys. For the default keys, addr is set to ff:ff:ff:ff:ff:ff. It is set to the station hardware address for individual keys. aid of the station is given to help the low-level driver select which hardware key index to use for this key. The Transmit Control Fields contains the hardware key index selected by the low-level driver.
int (*set_key)(struct net_device *dev, set_key_cmd cmd, u8 *addr,
struct ieee80211_key *key, int aid);
Set Transmit Key Index for WEP/TKIP (set_key_idx)
The DataPath driver calls the set_key_idx handler to set the transmit key index for default/broadcast keys. This is needed in cases where the WLAN card is doing full WEP/TKIP encapsulation (wep_include_iv is not set). In other cases, this function pointer can be set to NULL since the DataPath driver takes care of selecting the key index for each transmitted frame.
int (*set_key_idx)(struct net_device *dev, int idx);
Enable/Disable IEEE 8021x (set_ieee8021x)
The DataPath calls the set_ieee8021x handler to enable/disable IEEE 802.1X. This item requests the WLAN card to pass unencrypted EAPOL-Key frames even when encryption is configured. If the WLAN card does not require such a configuration, this function pointer can be set to NULL.
int (*set_ieee8021x)(struct net_device *dev, int use_ieee8021x);
Set Port Authorization State (set_port_auth)
If the WLAN hardware or low-level driver implements Physical Address Extension (PAE), the set_port_auth function can be used to set port authorization state (IEEE 802.1X PAE) to be authorized (authorized=1) or unauthorized (authorized=0). The DataPath Driver will filter frames based on authorization state anyway, so this function pointer can be set to NULL if the low-level driver does not require event notification about port state changes.
int (*set_port_auth)(struct net_device *dev, u8 *addr, int authorized);
Request Passive Scanning (passive_scan)
The DataPath driver calls the passive_scan handler to request the hardware to do a passive scan on a new channel. The hardware is expect to leave the current channel, including transmitting any CTS packets, etc.
int (*passive_scan)(struct net_device *dev, int state,
struct ieee80211_scan_conf *conf);
Return Low-level Statistics (get_stats)
The DataPath driver calls the get_stats handler to request low-level statistics from the device:
int (*get_stats)(struct net_device *dev,
struct ieee80211_low_level_stats *stats);
Enable/Disable Test Modes (test_mode)
The test_mode handler is used to enable/disable test modes (mode = IEEE80211_TEST_)
int (*test_mode)(struct net_device *dev, int mode);
Configure Test Parameters (test_param)
The test_param handler is used to configure test parameters.
int (*test_param)(struct net_device *dev, int param, int value);
Change MAC Address (set_mac_address)
The set_mac_address handler is used to change the MAC address. addr is pointer to struct sockaddr.
int (*set_mac_address)(struct net_device *dev, void *addr);
Set Privacy (set_privacy_invoked)
For devices that generate their own Beacons and probe response or association responses, the set_privacy_invoked handler updates the state of the privacy_invoked. It returns 0 for success or an error number.
int (*set_privacy_invoked)(struct net_device *dev,
Get Value from Sequence Counter (get_sequence_counter)
For devices that have internal sequence counters, allow the DataPath driver to access the current value of a counter:
int (*get_sequence_counter)(struct net_device *dev,
u8* addr, u8 keyidx, u8 txrx,
Configure RTS Threshold (set_rts_threshold)
The set_rts_threshold handler configures the RTS Threshold (if device needs it).
int (*set_rts_threshold)(struct net_device *dev, u32 value);
Configure Fragmentation Threshold (set_frag_threshold)
set_frag_threshold configures the fragmentation threshold (if device needs it).
int (*set_frag_threshold)(struct net_device *dev, u32 value);
Configure the Retry Limits (set_frag_threshold)
set_retry_limit configures the retry limits (if device needs it).
int (*set_retry_limit)(struct net_device *dev, u32 short_retry,
Request Number of Stations (sta_table_notification)
The sta_table_notification handler gets the number of client Stations (STAs) in the station (STA) table notification. This can be disabled. (NULL = disabled)
void (*sta_table_notification)(struct net_device *dev, int num_sta);
Configure QOS
Configure Queue Parameters (EDCF and Bursting) (conf_tx)
conf_tx configures transmit (TX) queue parameters (EDCF (aifs, cw_min, cw_max), bursting) for a hardware TX queue.
int (*conf_tx)(struct net_device *dev, int queue,
struct ieee80211_tx_queue_params *params);
Get Statistics of Current TX Queue Status (get_tx_stats)
get_tx_stats is used to get number of currently queued packets (queue length), maximum queue size (limit), and total number of packets sent using each transmit (TX) queue (count). This information is used for WMM to find out which TX queues have room for more packets and by hostapd to provide statistics about the current queueing state to external programs.
int (*get_tx_stats)(struct net_device *dev,
struct ieee80211_tx_queue_stats *stats);
Number of Available Hardware Queues (queues)
queues indicates the number of available hardware TX queues for data packets. WMM requires at least four queues.
Get TSF Timer Value (get_tsf)
get_tsf gets the current timing synchronization function (TSF) timer value from firmware/hardware. Currently, this is used only for IBSS mode debugging and, as such, is not a required function.
u64 (*get_tsf)(struct net_device *dev);
Reset the TSF Timer (reset_tsf)
reset_tsf resets 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 responsibility for TSF synchronization.
void (*reset_tsf)(struct net_device *dev);
Configure Beacon Data for IBSS (beacon_update)
beacon_update sets up Beacon data for IBSS Beacons. Unlike the Access Point (Master), IBSS uses a fixed beacon frame which is configured using this function. This handler is required only for IBSS mode.
int (*beacon_update)(struct net_device *dev, struct sk_buff *skb,
struct ieee80211_tx_control *control);
Determine if Last Beacon Sent by this IBSS (tx_last_beacon)
tx_last_beacon determines 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.
int (*tx_last_beacon)(struct net_device *dev);
DataPath Driver Function Calls
Register Hardware Device
The ieee80211_register_hw function registers a hardware device to the DataPath driver and kernel. The low-level driver must call this function before using any other DataPath driver function. It is called once for each hardware device. The returned pointer must be used to refer to the device when calling other functions. The DataPath driver allocates a private data area for the low-level driver. The size of this area is given as priv_data_len. The ieee80211_dev_hw_data function is used to get a pointer to the private data area.
struct net_device *ieee80211_register_hw(struct ieee80211_hw *hw, size_t
priv_data_len);
|
Note
|
In this version of the interface, the returned pointer is struct net_device *. This may change in the future. The low-level driver must not refer to the device data directly to remain compatible with the future versions.
|
Initialization Completed
The low-level driver should call the ieee80211_hw_initialized function to inform the DataPath driver that it has completed hardware initialization. This function is allowed to update the hardware configuration (for example, the list of supported operation modes and rates).
void ieee80211_hw_initialized(struct net_device *dev, struct ieee80211_hw
*hw);
Remove Hardware Device
The ieee80211_unregister_hw function instructs the DataPath driver to free the allocated resources and remove the net_device from the kernel. A non-zero return value indicates that removing the net_device was not allowed, and the low-level driver must continue to accept calls to its registered handler functions.
int ieee80211_unregister_hw(struct net_device *dev);
Receive Frame Callback
The low-level driver uses the ieee80211_rx function to send the frames it has received to the DataPath driver. The receive buffer (skb) must start with an 802.11 header.
void ieee80211_rx(struct net_device *dev, struct sk_buff *skb, struct
ieee80211_rx_status *status);
Transmit Status Callback
The low-level driver should call the ieee80211_tx_status function to report the status for any transmitted frames that had req_tx_status set in their Transmit Control Fields.
void ieee80211_tx_status(struct net_device *dev, struct sk_buff *skb,
struct ieee80211_tx_status *status);
Beacon Generation
If beacon frames are generated by the host system rather than in hardware/firmware, the low-level driver uses the ieee80211_beacon_gen function to receive the next beacon frame from the DataPath driver. The low-level driver is responsible for calling this function before beacon data is needed (for example, based on a hardware interrupt).
struct sk_buff *ieee80211_beacon_gen(struct net_device *dev, struct
ieee80211_tx_control *control);
Accessing Buffered Broadcast and Multicast Frames
If the hardware/firmware does not implement buffering of broadcast/multicast frames when power saving is used, the DataPath driver buffers them in host memory. The low-level driver uses this function to fetch next buffered frame. In most cases, this is used when generating a beacon frame. The function returns a pointer to the next buffered skb or NULL if no more buffered frames are available.
struct sk_buff *ieee80211_get_buffered_bc(struct net_device *dev, struct
ieee80211_tx_control *control);
|
Note
|
Buffered frames are returned only after a DTIM beacon frame was generated with ieee80211_beacon_gen(). Thus, the low-level driver must call ieee80211_beacon_gen() first. If the previous generated beacon was not DTIM, ieee80211_get_buffered_bc() returns NULL. Therefore, the low-level driver does not need to check for DTIM beacons separately and should be able to use common code for all beacons.
|
Net Interface Operation
802.11 may use more than one kernel net_device for each hardware device. The low-level driver does not "see" these interfaces, so it should use the ieee80211_netif_oper function to perform netif operations on all interfaces.
NETIF_ATTACH, NETIF_DETACH, NETIF_START, NETIF_STOP, NETIF_WAKE,
NETIF_IS_STOPPED, NETIF_UPDATE_TX_START
int ieee80211_netif_oper(struct net_device *dev, Netif_Oper op);
Accessing Private Data
Return a pointer to the low-level driver's private data area for a given device.
void *ieee80211_dev_hw_data(struct net_device *dev);
Network Statistics Data
Return a pointer to the network statistics data area for a given device.
void *ieee80211_dev_stats(struct net_device *dev);
Licensing
Devicescape Software, Inc.
Related Packages
Suggested
hostapd package
ieee80211-tools package
Required
None
