NOTE: this page is for archival only, see the note at the end of the page.

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.

Country definition

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:

country CR:

Regulatory rules

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.

Frequency range

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.

Power rule

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:

        (N/A, 20)

This tells us the maximum allowed EIRP that can be used on a frequency range, and if an maximum antenna gain is known what it is. 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 powe rof 20 dBm. No known 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 of 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 of 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.

Example analysis

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:

                        * 2412 MHz [1]
                        * 2417 MHz [2]
                        * 2422 MHz [3]
                        * 2427 MHz [4]
                        * 2432 MHz [5]
                        * 2437 MHz [6]
                        * 2442 MHz [7]
                        * 2447 MHz [8]
                        * 2452 MHz [9]
                        * 2457 MHz [10]
                        * 2462 MHz [11]
                        * 2467 MHz [12]
                        * 2472 MHz [13]
                        * 2484 MHz [14]

                        * 5180 MHz [36]
                        * 5200 MHz [40]
                        * 5220 MHz [44]
                        * 5240 MHz [48]
                        * 5260 MHz [52]
                        * 5280 MHz [56]
                        * 5300 MHz [60]
                        * 5320 MHz [64]
                        * 5500 MHz [100]
                        * 5520 MHz [104]
                        * 5540 MHz [108]
                        * 5560 MHz [112]
                        * 5580 MHz [116]
                        * 5600 MHz [120]
                        * 5620 MHz [124]
                        * 5640 MHz [128]
                        * 5660 MHz [132]
                        * 5680 MHz [136]
                        * 5700 MHz [140]
                        * 5745 MHz [149]
                        * 5765 MHz [153]
                        * 5785 MHz [157]
                        * 5805 MHz [161]
                        * 5825 MHz [165]

What cfg80211 will do next is iterate over each channel's center of frequency and see from the current regulatory domain on what regulatory rule a channel of 20 MHz bandwidth using the channel's center of 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.

Beacon hints

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.

This is a static dump of the wiki, taken after locking it in January 2015. The new wiki is at
versions of this page: last, v22, v21, v20, v19, v18, v17, v16, v15, v14, v13, v12, v11, v10, v9, v8, v7, v6, v5, v4, v3, v2, v1