- Regulatory rules processing
- Country definition
- Processing channels in cfg80211
Regulatory rules processing
This section is intended to help document cfg80211's algorithm for processing regulatory rules and applying them. You can read this if you are not so well versed with code or don't want to bother reading it.
Lets start out first by understanding how a country is defined. We start by declaring it with the key word "country" followed by the respective ISO 3166 alpha2 country code followed by a colon. So for example:
Each country can have a set of regulatory rules. Each regulatory rule has an attached frequency range and a respective power rule. An example of one regulatory rule follows:
(2402 - 2482 @ 40), (N/A, 20)
A country can have multiple regulatory rules.
Each frequency range provides a starting frequency and ending frequency in MHz followed by the maximum allowed bandwidth that a channel of communication can have in that frequency range. So for example, in the following regulatory rule:
(2402 - 2482 @ 40), (N/A, 20)
The frequency range is just:
(2402 - 2482 @ 40)
This is telling us that you can use a channel of communication of max bandwidth of up to 40 MHz in the frequency range 2402 MHz - 2482 MHz.
The power rule is the last section in a regulatory rule. For example in the regulatory rule:
(2402 - 2482 @ 40), (N/A, 20)
the power rule is:
This tells us the maximum allowed EIRP that can be used on a frequency range, and the maximum antenna gain if it is known. If the maximum antenna gain is not known N/A can be used to annotate this. The maximum EIRP is assumed to be in dBm, the maximum antenna gain is assumed to be in dBi.
Reading a regulatory rule
Now lets read a regulatory rule all together. The following regulatory rule:
(2402 - 2482 @ 40), (N/A, 20)
then tell us that we can use a channel of communication of up to 40 MHz in the frequency range 2402 MHz - 2482 MHz with a maximum EIRP output power of 20 dBm. No maximum antenna gain is known.
20 MHz channels
cfg80211 assumes all 802.11 cards want to use 20 MHz channels so channels get disabled if no 20 MHz channels are allowed in a given frequency range defined by the country the card is in.
40 MHz channels
40 MHz channels will only be allowed if 20 MHz channels are allowed as well. 40 MHz channels work by using a regular 20 MHz channel and then using an extra 20 MHz channel either on the left hand side of the first channel or the right hand side. We refer to this as either HT40- or HT40+, respectively.
cfg80211 checks if an HT40- or HT40+ channel fits on each center frequency for each power rule and will enable HT40- or HT40+ on each channel. This HT40 allow map is available currently only through debugfs. For example, here is an output:
root@tux:~# cat /sys/kernel/debug/ieee80211/phy0/ht40allow_map 2412 HT40 + 2417 HT40 + 2422 HT40 + 2427 HT40 + 2432 HT40 -+ 2437 HT40 -+ 2442 HT40 -+ 2447 HT40 - 2452 HT40 - 2457 HT40 - 2462 HT40 - 2467 Disabled 2472 Disabled 2484 Disabled 5180 HT40 + 5200 HT40 -+ 5220 HT40 -+ 5240 HT40 -+ 5260 HT40 -+ 5280 HT40 -+ 5300 HT40 -+ 5320 HT40 - 5500 HT40 + 5520 HT40 -+ 5540 HT40 -+ 5560 HT40 -+ 5580 HT40 - 5600 Disabled 5620 Disabled 5640 Disabled 5660 HT40 + 5680 HT40 -+ 5700 HT40 - 5745 HT40 + 5765 HT40 -+ 5785 HT40 -+ 5805 HT40 -+ 5825 HT40 -
This list is not exposed via nl80211 as cfg80211 will get a revisit as to how this is handled after the regulatory rules are restructured in the future.
Processing channels in cfg80211
When cfg80211 initializes it will have a list of wiphy devices. Each 802.11 card has a respective single wiphy device. Multiple interfaces can be attached to a wiphy device. The wiphy device has a list of channels which are shared. When a wiphy is registered to cfg80211 it has a list of supported 802.11 channels with a respective center frequency. The currently regulatory domain is read and each wiphy is processed to apply the regulatory domain to it. A wiphy device can have its own regulatory domain though. This allows us to enable two different cards which have two different regulatory domains to be present on a single system and for cfg80211 to respect it. When this happens there will be three regulatory domains, one for each wiphy and a core central regulatory domain which will consist of the intersection between the two wiphy's regulatory domains.
If a wiphy has no regulatory domain of its own cfg80211 will use its own core central regulatory domain to iterate over the card's 802.11 channels and apply rules, otherwise cfg80211 will use the card's own regulatory domain.
Suppose a wiphy is registered to cfg80211 and the driver that registers it claims that the wiphy has a regulatory domain of its own which indicates it is a card which is programmed to operate in Costa Rica. In this case cfg80211 would have queried CRDA for CR's regulatory domain and CRDA would reply with:
country CR: (2402 - 2482 @ 40), (N/A, 20) (5170 - 5250 @ 20), (3, 17) (5250 - 5330 @ 20), (3, 23), DFS (5735 - 5835 @ 20), (3, 30)
Now the wiphy that was registered to cfg80211 has these channels:
Frequencies: * 2412 MHz  * 2417 MHz  * 2422 MHz  * 2427 MHz  * 2432 MHz  * 2437 MHz  * 2442 MHz  * 2447 MHz  * 2452 MHz  * 2457 MHz  * 2462 MHz  * 2467 MHz  * 2472 MHz  * 2484 MHz  Frequencies: * 5180 MHz  * 5200 MHz  * 5220 MHz  * 5240 MHz  * 5260 MHz  * 5280 MHz  * 5300 MHz  * 5320 MHz  * 5500 MHz  * 5520 MHz  * 5540 MHz  * 5560 MHz  * 5580 MHz  * 5600 MHz  * 5620 MHz  * 5640 MHz  * 5660 MHz  * 5680 MHz  * 5700 MHz  * 5745 MHz  * 5765 MHz  * 5785 MHz  * 5805 MHz  * 5825 MHz 
What cfg80211 will do next is iterate over each channel's center frequency and see from the current regulatory domain on what regulatory rule a channel of 20 MHz bandwidth using the channel's center frequency fits in. If no match is found the channel is disabled. If a match is found cfg80211 will enable 20 MHz communication on the channel.
Post processing mechanisms
Once cfg80211 processes a regulatory domain on a wiphy device it goes through a series of post processing on the wiphy. Below we document the different types of post processing performed by cfg80211.
cfg80211 has a feature called beacon hinting to assist cfg80211 in allowing a card to life passive-scan and no-beaconing flags. Passive-scan flags are used on channels to ensure that an interface will not issue a probe request out. The no-beaconing flag (today its just called no-adhoc) exists to allow regulatory domain definitions to disallow a device from initiating communication using beacons, so for example AP/IBSS/Mesh interfaces would not be able to initiate communication on these channels unless the channel does not have this flag. If either of these flags are present on a channel a device is prohibited from initiating communication on cfg80211. The reason two flags exist instead of one is some regulatory definitions need to state that modes of operation like adhoc are strictly prohibited even though active scan is allowed.
Regulatory rule flags like passive-scan and no-beaconing were originally invented to help with World Roaming. If you do not know what country you are in you can still behave as an 802.11 STA interface but can wait to enable active scans until you see a beacon from an AP, if the channel being used is not a DFS channel and not channels 12-14 on the 2.4 GHz band. The same can be said for initiating communication, so both the passive-scan and no-beaconing flags can be lifted if an AP is found beaconing on a non-DFS channel and if the channel is also not channels 12-14 on the 2.4 GHz band. cfg80211 takes advantage of this bit of logic to life both of these flags if and only if the wiphy device is world roaming.
Driver override on rules
To allow more driver flexibility cfg80211 allows drivers to review the regulatory settings on the wiphy and override them. This enables more flexibility on regulatory design but also enables drivers to take advantage of offloading most of the regulatory work to cfg80211/CRDA. The way that drivers can override regulatory settings is by defining a wiphy regulatory reg_notifier(). The wiphy's reg_notifier() callback will be called after cfg80211 has completed processing its regulatory settings on the wiphy device.
Driver regulatory hints
Drivers can issue their own regulatory domain hints to cfg80211. If they do this the wiphy gets its own regulatory domain. This enables two different 802.11 devices even with the same 802.11 driver to have different regulatory domains. This also enables there to be a central 802.11 regulatory domain which will consists of an intersection between the two present regulatory domains if two cards are present with different regulatory domains.
Enabling users to enhance regulatory
Users can enhance regulatory settings by further restricting devices by picking a regulatory domain. This will enable users to help compliance further. Currently regulatory rules for certain countries ("US" and "JP") do not allow users to select their regulatory domain though so blindly trusting a user is not something that can be allowed if you are in certain regulatory domain. If a user picks a regulatory domain channels will be restricted further on a device if the device has its own regulatory domain already listed.
Cellular base station regulatory hints
Cell base station towers can inform mobile / laptop devices of their location with great accuracy. As of the 3.6 release Linux supports the ability for cell base station towers to supply a regulatory hint to the Linux kernel. This is done by providing an attribute to the Linux kernel that classifies the hint as coming from a cellular base station. Device drivers require testing / compliance prior to enabling this feature mostly due to possible synchronization issues with a device's firmware when the device implements some regulatory functionality in firmware. Device drivers which have completed validation for this feature can enable a Kconfig feature for system integrators for this feature on their driver by depending on the CONFIG_CFG80211_CERTIFICATION_ONUS option. When capable, a device driver would enable the wiphy->features NL80211_FEATURE_CELL_BASE_REG_HINTS feature, and upon registration to cfg80211 would inform it that there is at least one driver present that support cellular base station hints. cfg80211 will ignore cellular base station hints unless one device driver is present with one device (wiphy) that supports this feature. If all devices have been removed from the system that support this feature the cell base station hints would be ignored afterwards.
Userspace software solutions are expected to implement support for this feature through a dbus event and enabling such event to send a cell base station regulatory hint from wpa_supplicant to the kernel by using the NL80211_ATTR_USER_REG_HINT_TYPE attribute and classifying the hint as NL80211_USER_REG_HINT_CELL_BASE. System integrators which enable this feature must ensure cell base station hints is not a feature enabled for users to use manually, instead its designed for userspace software to implement a hint only when a cell modem has detected we are in a new country.