Linux Wireless Development

Developer Documentation

The MAC layer consists of two major functional entities:

• the MAC sublayer
The core functions of channel access, retransmissions, packet fragmentation and encryption are handled by the MAC sublayer.
• the MAC layer management entity (MLME)
The MLME handles higher MAC functions such as synchronization, power management, and connection management, which include association and authentication.
MLME is the management entity where the Physical layer (PHY) MAC state machines reside.
Examples of states a MLME may assist in reaching:
• Authenticate
• Deauthenticate
• Associate
• Disassociate
• Reassociate
• Beacon

SoftMAC is a term used to describe a type of Wireless NIC where the MLME is expected to be managed in software.
mac80211 is a driver API for SoftMAC Wireless NIC.

FullMAC is a term used to describe a type of wireless card where the MLME is managed in hardware.
You would not use mac80211 to write a FullMAC wireless driver.

Use TI's WiLink8 WiFi driver as an example to illustrate the architecture.

• WiLink8 FW
The FW runs on the device HW to provide the PHY and MAC functionality of the Wi-Fi.
The host communicates via SDIO to the WLAN device.
On the device side, the WLAN MAC is responsible for the 802.11 MAC functions, and conveys WLAN packets from/to the external host to/from the FW.
The MAC is responsible for the timing and the time critical decisions only.
The PHY performs the 802.11 PHY functions of encoding/decoding and modulation/ demodulation, and is responsible for the RF functions of up/down modulation to carrier frequency, filtering and amplification.
• WiLink8 Driver
is an abstraction layer to the device HW and FW.
Implements low level operations required to support the MAC driver.
• Wl18xx
Implement chip specific functions and services.
Supports the wlcore by implementing HW-specific functions.
• wlcore_sdio
Adaptation layer between the SDIO driver and the WiLink driver.
• wlcore
Implements the low level driver for WiLink devices, supporting mac80211 operations.
Contains the common functions for all supported WiLink chipsets.
• Linux wireless subsystem driver
implements layer-2 Wi-Fi protocol requirements (data and control path).
This is a generic component, not platform/device specific.
This layer consists of the following components.
• mac80211
The Linux kernel module implementing MAC-layer functions for Wi-Fi Soft-MAC solution.
• cfg80211
The Linux wireless configuration API. (This is the lowest layer that is common for both soft-MAC and hard-MAC).
• nl80211
Implements a net-link interface between user-space and kernel space components of the Linux Wireless solution.
• Hostap package
Contains open-source user-space package.
Provides the upper-management layers for all WLAN roles (STA, AP, P2P and Mesh).
Generates 2 daemons: wpa_supplicant (STA, P2P, Mesh), and hostapd (AP).
• Utilities
provide initialization and configuration services.
Implement debug and statistics capabilities

Driver APIs

Here are all the driver APIs we use to write drivers in Linux:

• Wireless-Extensions
- old wireless driver framework
• mac80211 - wireless driver API for SoftMAC devices
• cfg80211 - new driver configuration API
• nl80211 - new userspace ←→ kernelspace wireless driver communication transport
• Hardware Specifications - specifications for chipsets we support or will support soon
• Radiotap - For 802.11 frame injection/reception
• Support for Android - if you want to know how to add support for Android
• Howto modularize code - Examples of how we expect you to modularize code

nl80211

nl80211 is the new 802.11 netlink interface public header.
Together with cfg80211 it is intended to replace Wireless-Extensions.

• include/uapi/linux/nl80211.h

...    
 * @NL80211_ATTR_AKM_SUITES: Used with CONNECT, ASSOCIATE, and NEW_BEACON to
 *	indicate which key management algorithm(s) to use (an array of u32).
 *	This attribute is also sent in response to @NL80211_CMD_GET_WIPHY,
 *	indicating the supported AKM suites, intended for specific drivers which
 *	implement SME and have constraints on which AKMs are supported and also
 *	the cases where an AKM support is offloaded to the driver/firmware.
 *	If there is no such notification from the driver, user space should
 *	assume the driver supports all the AKM suites.
...


enum nl80211_attrs {
...
	NL80211_ATTR_AKM_SUITES,
...
};    
    

cfg80211

cfg80211 is the Linux 802.11 configuration API.
cfg80211 replaces Wireless-Extensions.

You write cfg80211 operation callbacks and fill in the wiphy struct to indicate to cfg80211 its device capabilities.
For more details refer to cfg80211.h and as an example driver you can read ath6kl .
The drivers and hardware can have their own regulatory solutions, this framework provide an API to allow drivers to export their own regulatory restrictions.

Our regulatory infrastructure consists of three major components:

• Kernel integration
• CRDA
• wireless-regdb

cfg80211 also provides full regulatory support, this is done through wireless-regdb and the usage of CRDA.

• cfg80211 used by new wireless drivers for regulatory compliance in the Linux kernel
• a thorough and flexible regulatory database in userspace
The database is shipped in binary form
• a Central Regulatory Domain Agent (CRDA), a userspace agent, which can be triggered to update the kernel wireless core's definition of the regulatory permissions for a specific country.
Keeping the database in userspace allows distributions to provide updates without kernel upgrades.

For some hardware, regulatory permissions are programmed into the EEPROM.

wireless-regdb

The regulatory database can be found : wireless-regdb.

CRDA

CRDA is the userspace agent which uploads regulatory domains into the kernel, it acts as a udev helper.
It relies on nl80211 for communication.
CRDA is intended to be run only through udev communication from the kernel. The user should never have to run it manually except if debugging udev issues.

Code

https://git.kernel.org/cgit/linux/kernel/git/mcgrof/crda.git/

CONFIG_CFG80211_INTERNAL_REGDB

If you do not want to install CRDA on a host, you can simply enable the CONFIG_CFG80211_INTERNAL_REGDB on your kernel.
This is an alternative to CRDA.
Once enabled, you need to place db.txt into net/wireless/db.txt. If using CONFIG_CFG80211_INTERNAL_REGDB without updating net/wireless/db.txt you'll end up with the static world regulatory domain "00.
It is also possible to configure the cfg80211 kernel module to use a specific regdomain by adding module options, for example,

options cfg80211 ieee80211_regdom=JP .

Changing regulatory domains

Regdomains use ISO 3166-1 alpha-2 country codes.
For example, the regdomain of the United States would be "US", China would be "CN", etc.

The current regdomain can be queried:

$ iw reg get
global
country 00: DFS-UNSET
	(2402 - 2472 @ 40), (N/A, 20), (N/A)
	(2457 - 2482 @ 20), (N/A, 20), (N/A), AUTO-BW, PASSIVE-SCAN
	(2474 - 2494 @ 20), (N/A, 20), (N/A), NO-OFDM, PASSIVE-SCAN
	(5170 - 5250 @ 80), (N/A, 20), (N/A), AUTO-BW, PASSIVE-SCAN
	(5250 - 5330 @ 80), (N/A, 20), (0 ms), DFS, AUTO-BW, PASSIVE-SCAN
	(5490 - 5730 @ 160), (N/A, 20), (0 ms), DFS, PASSIVE-SCAN
	(5735 - 5835 @ 80), (N/A, 20), (N/A), PASSIVE-SCAN
	(57240 - 63720 @ 2160), (N/A, 0), (N/A)  
  

Your device may be set to country "00:", which is the "world regulatory domain" and contains generic settings.

The following userspace applications can request the kernel to change regulatory domains:

• iw

iw reg set US
    

• wpa_supplicant
wpa_supplicant.conf:

COUNTRY=US
  	

• Using Network Manager to change regulatory domains
Network Manager uses wpa_supplicant.