^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Linux wireless regulatory documentation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) =======================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) This document gives a brief review over how the Linux wireless
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) regulatory infrastructure works.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) More up to date information can be obtained at the project's web page:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) https://wireless.wiki.kernel.org/en/developers/Regulatory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) Keeping regulatory domains in userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Due to the dynamic nature of regulatory domains we keep them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) in userspace and provide a framework for userspace to upload
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) to the kernel one regulatory domain to be used as the central
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) core regulatory domain all wireless devices should adhere to.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) How to get regulatory domains to the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) -------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) When the regulatory domain is first set up, the kernel will request a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) database file (regulatory.db) containing all the regulatory rules. It
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) will then use that database when it needs to look up the rules for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) given country.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) How to get regulatory domains to the kernel (old CRDA solution)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) ---------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) Userspace gets a regulatory domain in the kernel by having
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) a userspace agent build it and send it via nl80211. Only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) expected regulatory domains will be respected by the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) A currently available userspace agent which can accomplish this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) is CRDA - central regulatory domain agent. Its documented here:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) https://wireless.wiki.kernel.org/en/developers/Regulatory/CRDA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Essentially the kernel will send a udev event when it knows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) it needs a new regulatory domain. A udev rule can be put in place
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) to trigger crda to send the respective regulatory domain for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) specific ISO/IEC 3166 alpha2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Below is an example udev rule which can be used:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) # Example file, should be put in /etc/udev/rules.d/regulatory.rules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) The alpha2 is passed as an environment variable under the variable COUNTRY.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) Who asks for regulatory domains?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) * Users
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Users can use iw:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) https://wireless.wiki.kernel.org/en/users/Documentation/iw
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) An example::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) # set regulatory domain to "Costa Rica"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) iw reg set CR
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) This will request the kernel to set the regulatory domain to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) the specificied alpha2. The kernel in turn will then ask userspace
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) to provide a regulatory domain for the alpha2 specified by the user
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) by sending a uevent.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) * Wireless subsystems for Country Information elements
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) The kernel will send a uevent to inform userspace a new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) regulatory domain is required. More on this to be added
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) as its integration is added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) * Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) If drivers determine they need a specific regulatory domain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) set they can inform the wireless core using regulatory_hint().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) They have two options -- they either provide an alpha2 so that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) crda can provide back a regulatory domain for that country or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) they can build their own regulatory domain based on internal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) custom knowledge so the wireless core can respect it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) *Most* drivers will rely on the first mechanism of providing a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) regulatory hint with an alpha2. For these drivers there is an additional
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) check that can be used to ensure compliance based on custom EEPROM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) regulatory data. This additional check can be used by drivers by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) registering on its struct wiphy a reg_notifier() callback. This notifier
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) is called when the core's regulatory domain has been changed. The driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) can use this to review the changes made and also review who made them
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) (driver, user, country IE) and determine what to allow based on its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) internal EEPROM data. Devices drivers wishing to be capable of world
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) roaming should use this callback. More on world roaming will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) added to this document when its support is enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) Device drivers who provide their own built regulatory domain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) do not need a callback as the channels registered by them are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) the only ones that will be allowed and therefore *additional*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) channels cannot be enabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) Example code - drivers hinting an alpha2:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) ------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) This example comes from the zd1211rw device driver. You can start
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) by having a mapping of your device's EEPROM country/regulatory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) domain value to a specific alpha2 as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) static struct zd_reg_alpha2_map reg_alpha2_map[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) { ZD_REGDOMAIN_FCC, "US" },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) { ZD_REGDOMAIN_IC, "CA" },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) { ZD_REGDOMAIN_ETSI, "DE" }, /* Generic ETSI, use most restrictive */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) { ZD_REGDOMAIN_JAPAN, "JP" },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) { ZD_REGDOMAIN_JAPAN_ADD, "JP" },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) { ZD_REGDOMAIN_SPAIN, "ES" },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) { ZD_REGDOMAIN_FRANCE, "FR" },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) Then you can define a routine to map your read EEPROM value to an alpha2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) static int zd_reg2alpha2(u8 regdomain, char *alpha2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) unsigned int i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) struct zd_reg_alpha2_map *reg_map;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) for (i = 0; i < ARRAY_SIZE(reg_alpha2_map); i++) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) reg_map = ®_alpha2_map[i];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) if (regdomain == reg_map->reg) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) alpha2[0] = reg_map->alpha2[0];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) alpha2[1] = reg_map->alpha2[1];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) return 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) Lastly, you can then hint to the core of your discovered alpha2, if a match
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) was found. You need to do this after you have registered your wiphy. You
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) are expected to do this during initialization.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) r = zd_reg2alpha2(mac->regdomain, alpha2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) if (!r)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) regulatory_hint(hw->wiphy, alpha2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) Example code - drivers providing a built in regulatory domain:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) --------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) [NOTE: This API is not currently available, it can be added when required]
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) If you have regulatory information you can obtain from your
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) driver and you *need* to use this we let you build a regulatory domain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) structure and pass it to the wireless core. To do this you should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) kmalloc() a structure big enough to hold your regulatory domain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) structure and you should then fill it with your data. Finally you simply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) call regulatory_hint() with the regulatory domain structure in it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) Bellow is a simple example, with a regulatory domain cached using the stack.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) Your implementation may vary (read EEPROM cache instead, for example).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) Example cache of some regulatory domain::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) struct ieee80211_regdomain mydriver_jp_regdom = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) .n_reg_rules = 3,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) .alpha2 = "JP",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) //.alpha2 = "99", /* If I have no alpha2 to map it to */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) .reg_rules = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) /* IEEE 802.11b/g, channels 1..14 */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) REG_RULE(2412-10, 2484+10, 40, 6, 20, 0),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) /* IEEE 802.11a, channels 34..48 */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) REG_RULE(5170-10, 5240+10, 40, 6, 20,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) NL80211_RRF_NO_IR),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) /* IEEE 802.11a, channels 52..64 */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) REG_RULE(5260-10, 5320+10, 40, 6, 20,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) NL80211_RRF_NO_IR|
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) NL80211_RRF_DFS),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Then in some part of your code after your wiphy has been registered::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) struct ieee80211_regdomain *rd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) int size_of_regd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) int num_rules = mydriver_jp_regdom.n_reg_rules;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) unsigned int i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) size_of_regd = sizeof(struct ieee80211_regdomain) +
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) (num_rules * sizeof(struct ieee80211_reg_rule));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) rd = kzalloc(size_of_regd, GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) if (!rd)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) memcpy(rd, &mydriver_jp_regdom, sizeof(struct ieee80211_regdomain));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) for (i=0; i < num_rules; i++)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) memcpy(&rd->reg_rules[i],
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) &mydriver_jp_regdom.reg_rules[i],
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) sizeof(struct ieee80211_reg_rule));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) regulatory_struct_hint(rd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Statically compiled regulatory database
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) ---------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) When a database should be fixed into the kernel, it can be provided as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) firmware file at build time that is then linked into the kernel.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags