- About cfg80211
- Regulatory support
- cfg80211 files and kernel docs
cfg80211 is the new Linux wireless configuration API. cfg80211 will replace Wireless-Extensions. You use nl80211 to configure a device. Note that we are not going to add any new features to Wireless Extensions, we'll only fix bugs for it. If you don't like what you see with Wireless-Extensions then help us advance cfg80211.
cfg80211 has regulatory compliance built into it, each registered device obeys cfg80211's regulatory interpretations and provides an API for drivers and for mac80211 to provide hints to it as to what rules should be enforced. A device registers with cfg80211 a list of supported bands and each band has a list of supported channels. During registration cfg80211 will ensure only the allowed channels for the currently set regulatory domain will be left enabled.
Wireless core initialization
Upon the initialization of the wireless core (cfg80211) a world regulatory domain (highly restrictive) will be set as the central regulatory domain. If CRDA is present the latest dynamic world regulatory domain is queried from CRDA; if it is not then a statically defined list is used.
When a wiphy is registered to cfg80211 (possibly via mac80211) the effective set of permitted channels/maximum power is calculated for that device based on the current regulatory domain. As initially that will be the world regulatory domain, devices start out being restricted to that.
Each driver can hint to cfg80211 which regulatory domain to set by providing an ISO-3166 alpha2 country code; this is intended to be used as a first start-up hint based on the device's EEPROM.
Conflicts can arise when you have multiple wireless devices present on a system which claim different regulatory domains. Arbitrarily complex algorithms could be invented to resolve such conflicts; for now the regulatory domain selected by the first wireless card is chosen. It would also be reasonable to let users resolve the conflict manually.
Once an alpha2 is suggested to the wireless core it will query CRDA for a regulatory domain for that alpha2. The wireless core will then iterate overall all registered wireless devices and update the device's list of enabled channels, max power, max bandwidth and max antenna gain for each of them.
After a regulatory domain has been set the reg_notfier() for each driver (if defined) will be called. Drivers have the option to register their callback (reg_notifier()) to review the current regulatory settings and update them based on further requirements.
Drivers which have regulatory restrictions enforced in the firmware and do not have ISO / IEC 3166 alpha2 country mappings to their currently set regulatory domain may choose to opt out of the first regulatory core review upon initialization, however subsequent updates (by the user or mac80211 through 802.11d) will be obeyed.
802.11 country information
APs can provide an ISO/IEC 3166-1 country code and a channel list (with associated max tx power setting.) In practice though one can not always trust APs country information element regulatory information due to considerations for outdated data, rogue/busted APs. Therefore, the wireless code determines the regulatory permissions based on the intersection of data from the APs country information element and what CRDA provides for the given country code.
The Linux kernel wireless subsystem always enables the dot11MultiDomainCapabilityEnabled flag. Therefore, it tries to follow country information received in AP beacons.
Manual setting of the regulatory domain
Manual setting for a regulatory domain only makes sense if you have no AP capable of broadcasting regulatory information or if your card has no EEPROM regulatory information. To help these type of devices we can allow setting of the regulatory domain to help the user comply to regulatory rules. This can happen, for example, when you travel with a wireless card. For devices with their own EEPROM regulatory information the callback routine (reg_notifier()) registered to cfg80211 for the driver can ensure the EEPROM data is respected even if a user changes the regulatory information manually.
As mentioned above, after the driver has registered to cfg80211 the world regulatory domain settings will have been set by default as no beacons with country information could have been received yet. Drivers should register all supported hardware channels to the wireless core.
Drivers with EEPROM regulatory information
Drivers that have country information in their EEPROM should provide an ISO/IEC 3166-1 alpha2 code to cfg80211 as a hint about the current regulatory domain. This should be done wiphy registration.
For the special case where the EEPROM regulatory information must be observed at all times, the driver will not register any other channels.
In the special case where the EEPROM regulatory information must be observed unless 802.11 country information is received, the driver may register a regulatory notifier and restrict any information that CRDA supplied to the EEPROM information depending on the cause of the regulatory change.
Drivers without EEPROM regulatory information
Drivers with no EEPROM regulatory information can simply rely on the world regulatory domain, wait for an 802.11 country information or the user setting the regulatory domain manually.
cfg80211 provides APIs for both drivers and mac80211 to supply regulatory hints to further enhance regulatory compliance.
After registration with cfg80211 a driver can provide a regulatory_hint() with an alpha2. This alpha2 can come from a map read from the device's EEPROM.
cfg80211 supports enhancing regulatory compliance by allowing drivers and mac80211 to inform it of when a country information element has been received and should be obeyed. The Country Information Element (cf. 802.11-2007 126.96.36.199) contains the information required to allow a station to identify the regulatory domain in which the AP is located and to configure its PHY for operation in that regulatory domain. The Country IE contains, amongst other things, the list of permissions (channels and transmit power on those channels) and an ISO/IEC 3166-1 country code. regulatory_hint_11d() can be used to pass to cfg80211 an IEEE 802.11 country information element. cfg80211 will parse the information element, build a regulatory domain from it and intersect with what CRDA tells us should apply for the given alpha2. This prevents rogue/busted APs from providing incorrect information.