docs: networking: convert regulatory.txt to ReST
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Thu, 30 Apr 2020 16:04:20 +0000 (18:04 +0200)
committerDavid S. Miller <davem@davemloft.net>
Thu, 30 Apr 2020 19:56:37 +0000 (12:56 -0700)
- add SPDX header;
- adjust title markup;
- mark code blocks and literals as such;
- adjust identation, whitespaces and blank lines where needed;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
Documentation/networking/index.rst
Documentation/networking/regulatory.rst [new file with mode: 0644]
Documentation/networking/regulatory.txt [deleted file]
MAINTAINERS

index e63a2cb2e4cb5f399c04232ce6cf7685f4f143e0..bc3b04a2edde11a8672708fd8d4ffbcdac862fe7 100644 (file)
@@ -98,6 +98,7 @@ Contents:
    radiotap-headers
    ray_cs
    rds
+   regulatory
 
 .. only::  subproject and html
 
diff --git a/Documentation/networking/regulatory.rst b/Documentation/networking/regulatory.rst
new file mode 100644 (file)
index 0000000..8701b91
--- /dev/null
@@ -0,0 +1,209 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================================
+Linux wireless regulatory documentation
+=======================================
+
+This document gives a brief review over how the Linux wireless
+regulatory infrastructure works.
+
+More up to date information can be obtained at the project's web page:
+
+http://wireless.kernel.org/en/developers/Regulatory
+
+Keeping regulatory domains in userspace
+---------------------------------------
+
+Due to the dynamic nature of regulatory domains we keep them
+in userspace and provide a framework for userspace to upload
+to the kernel one regulatory domain to be used as the central
+core regulatory domain all wireless devices should adhere to.
+
+How to get regulatory domains to the kernel
+-------------------------------------------
+
+When the regulatory domain is first set up, the kernel will request a
+database file (regulatory.db) containing all the regulatory rules. It
+will then use that database when it needs to look up the rules for a
+given country.
+
+How to get regulatory domains to the kernel (old CRDA solution)
+---------------------------------------------------------------
+
+Userspace gets a regulatory domain in the kernel by having
+a userspace agent build it and send it via nl80211. Only
+expected regulatory domains will be respected by the kernel.
+
+A currently available userspace agent which can accomplish this
+is CRDA - central regulatory domain agent. Its documented here:
+
+http://wireless.kernel.org/en/developers/Regulatory/CRDA
+
+Essentially the kernel will send a udev event when it knows
+it needs a new regulatory domain. A udev rule can be put in place
+to trigger crda to send the respective regulatory domain for a
+specific ISO/IEC 3166 alpha2.
+
+Below is an example udev rule which can be used:
+
+# Example file, should be put in /etc/udev/rules.d/regulatory.rules
+KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"
+
+The alpha2 is passed as an environment variable under the variable COUNTRY.
+
+Who asks for regulatory domains?
+--------------------------------
+
+* Users
+
+Users can use iw:
+
+http://wireless.kernel.org/en/users/Documentation/iw
+
+An example::
+
+  # set regulatory domain to "Costa Rica"
+  iw reg set CR
+
+This will request the kernel to set the regulatory domain to
+the specificied alpha2. The kernel in turn will then ask userspace
+to provide a regulatory domain for the alpha2 specified by the user
+by sending a uevent.
+
+* Wireless subsystems for Country Information elements
+
+The kernel will send a uevent to inform userspace a new
+regulatory domain is required. More on this to be added
+as its integration is added.
+
+* Drivers
+
+If drivers determine they need a specific regulatory domain
+set they can inform the wireless core using regulatory_hint().
+They have two options -- they either provide an alpha2 so that
+crda can provide back a regulatory domain for that country or
+they can build their own regulatory domain based on internal
+custom knowledge so the wireless core can respect it.
+
+*Most* drivers will rely on the first mechanism of providing a
+regulatory hint with an alpha2. For these drivers there is an additional
+check that can be used to ensure compliance based on custom EEPROM
+regulatory data. This additional check can be used by drivers by
+registering on its struct wiphy a reg_notifier() callback. This notifier
+is called when the core's regulatory domain has been changed. The driver
+can use this to review the changes made and also review who made them
+(driver, user, country IE) and determine what to allow based on its
+internal EEPROM data. Devices drivers wishing to be capable of world
+roaming should use this callback. More on world roaming will be
+added to this document when its support is enabled.
+
+Device drivers who provide their own built regulatory domain
+do not need a callback as the channels registered by them are
+the only ones that will be allowed and therefore *additional*
+channels cannot be enabled.
+
+Example code - drivers hinting an alpha2:
+------------------------------------------
+
+This example comes from the zd1211rw device driver. You can start
+by having a mapping of your device's EEPROM country/regulatory
+domain value to a specific alpha2 as follows::
+
+  static struct zd_reg_alpha2_map reg_alpha2_map[] = {
+       { ZD_REGDOMAIN_FCC, "US" },
+       { ZD_REGDOMAIN_IC, "CA" },
+       { ZD_REGDOMAIN_ETSI, "DE" }, /* Generic ETSI, use most restrictive */
+       { ZD_REGDOMAIN_JAPAN, "JP" },
+       { ZD_REGDOMAIN_JAPAN_ADD, "JP" },
+       { ZD_REGDOMAIN_SPAIN, "ES" },
+       { ZD_REGDOMAIN_FRANCE, "FR" },
+
+Then you can define a routine to map your read EEPROM value to an alpha2,
+as follows::
+
+  static int zd_reg2alpha2(u8 regdomain, char *alpha2)
+  {
+       unsigned int i;
+       struct zd_reg_alpha2_map *reg_map;
+               for (i = 0; i < ARRAY_SIZE(reg_alpha2_map); i++) {
+                       reg_map = &reg_alpha2_map[i];
+                       if (regdomain == reg_map->reg) {
+                       alpha2[0] = reg_map->alpha2[0];
+                       alpha2[1] = reg_map->alpha2[1];
+                       return 0;
+               }
+       }
+       return 1;
+  }
+
+Lastly, you can then hint to the core of your discovered alpha2, if a match
+was found. You need to do this after you have registered your wiphy. You
+are expected to do this during initialization.
+
+::
+
+       r = zd_reg2alpha2(mac->regdomain, alpha2);
+       if (!r)
+               regulatory_hint(hw->wiphy, alpha2);
+
+Example code - drivers providing a built in regulatory domain:
+--------------------------------------------------------------
+
+[NOTE: This API is not currently available, it can be added when required]
+
+If you have regulatory information you can obtain from your
+driver and you *need* to use this we let you build a regulatory domain
+structure and pass it to the wireless core. To do this you should
+kmalloc() a structure big enough to hold your regulatory domain
+structure and you should then fill it with your data. Finally you simply
+call regulatory_hint() with the regulatory domain structure in it.
+
+Bellow is a simple example, with a regulatory domain cached using the stack.
+Your implementation may vary (read EEPROM cache instead, for example).
+
+Example cache of some regulatory domain::
+
+  struct ieee80211_regdomain mydriver_jp_regdom = {
+       .n_reg_rules = 3,
+       .alpha2 =  "JP",
+       //.alpha2 =  "99", /* If I have no alpha2 to map it to */
+       .reg_rules = {
+               /* IEEE 802.11b/g, channels 1..14 */
+               REG_RULE(2412-10, 2484+10, 40, 6, 20, 0),
+               /* IEEE 802.11a, channels 34..48 */
+               REG_RULE(5170-10, 5240+10, 40, 6, 20,
+                       NL80211_RRF_NO_IR),
+               /* IEEE 802.11a, channels 52..64 */
+               REG_RULE(5260-10, 5320+10, 40, 6, 20,
+                       NL80211_RRF_NO_IR|
+                       NL80211_RRF_DFS),
+       }
+  };
+
+Then in some part of your code after your wiphy has been registered::
+
+       struct ieee80211_regdomain *rd;
+       int size_of_regd;
+       int num_rules = mydriver_jp_regdom.n_reg_rules;
+       unsigned int i;
+
+       size_of_regd = sizeof(struct ieee80211_regdomain) +
+               (num_rules * sizeof(struct ieee80211_reg_rule));
+
+       rd = kzalloc(size_of_regd, GFP_KERNEL);
+       if (!rd)
+               return -ENOMEM;
+
+       memcpy(rd, &mydriver_jp_regdom, sizeof(struct ieee80211_regdomain));
+
+       for (i=0; i < num_rules; i++)
+               memcpy(&rd->reg_rules[i],
+                      &mydriver_jp_regdom.reg_rules[i],
+                      sizeof(struct ieee80211_reg_rule));
+       regulatory_struct_hint(rd);
+
+Statically compiled regulatory database
+---------------------------------------
+
+When a database should be fixed into the kernel, it can be provided as a
+firmware file at build time that is then linked into the kernel.
diff --git a/Documentation/networking/regulatory.txt b/Documentation/networking/regulatory.txt
deleted file mode 100644 (file)
index 381e5b2..0000000
+++ /dev/null
@@ -1,204 +0,0 @@
-Linux wireless regulatory documentation
----------------------------------------
-
-This document gives a brief review over how the Linux wireless
-regulatory infrastructure works.
-
-More up to date information can be obtained at the project's web page:
-
-http://wireless.kernel.org/en/developers/Regulatory
-
-Keeping regulatory domains in userspace
----------------------------------------
-
-Due to the dynamic nature of regulatory domains we keep them
-in userspace and provide a framework for userspace to upload
-to the kernel one regulatory domain to be used as the central
-core regulatory domain all wireless devices should adhere to.
-
-How to get regulatory domains to the kernel
--------------------------------------------
-
-When the regulatory domain is first set up, the kernel will request a
-database file (regulatory.db) containing all the regulatory rules. It
-will then use that database when it needs to look up the rules for a
-given country.
-
-How to get regulatory domains to the kernel (old CRDA solution)
----------------------------------------------------------------
-
-Userspace gets a regulatory domain in the kernel by having
-a userspace agent build it and send it via nl80211. Only
-expected regulatory domains will be respected by the kernel.
-
-A currently available userspace agent which can accomplish this
-is CRDA - central regulatory domain agent. Its documented here:
-
-http://wireless.kernel.org/en/developers/Regulatory/CRDA
-
-Essentially the kernel will send a udev event when it knows
-it needs a new regulatory domain. A udev rule can be put in place
-to trigger crda to send the respective regulatory domain for a
-specific ISO/IEC 3166 alpha2.
-
-Below is an example udev rule which can be used:
-
-# Example file, should be put in /etc/udev/rules.d/regulatory.rules
-KERNEL=="regulatory*", ACTION=="change", SUBSYSTEM=="platform", RUN+="/sbin/crda"
-
-The alpha2 is passed as an environment variable under the variable COUNTRY.
-
-Who asks for regulatory domains?
---------------------------------
-
-* Users
-
-Users can use iw:
-
-http://wireless.kernel.org/en/users/Documentation/iw
-
-An example:
-
-  # set regulatory domain to "Costa Rica"
-  iw reg set CR
-
-This will request the kernel to set the regulatory domain to
-the specificied alpha2. The kernel in turn will then ask userspace
-to provide a regulatory domain for the alpha2 specified by the user
-by sending a uevent.
-
-* Wireless subsystems for Country Information elements
-
-The kernel will send a uevent to inform userspace a new
-regulatory domain is required. More on this to be added
-as its integration is added.
-
-* Drivers
-
-If drivers determine they need a specific regulatory domain
-set they can inform the wireless core using regulatory_hint().
-They have two options -- they either provide an alpha2 so that
-crda can provide back a regulatory domain for that country or
-they can build their own regulatory domain based on internal
-custom knowledge so the wireless core can respect it.
-
-*Most* drivers will rely on the first mechanism of providing a
-regulatory hint with an alpha2. For these drivers there is an additional
-check that can be used to ensure compliance based on custom EEPROM
-regulatory data. This additional check can be used by drivers by
-registering on its struct wiphy a reg_notifier() callback. This notifier
-is called when the core's regulatory domain has been changed. The driver
-can use this to review the changes made and also review who made them
-(driver, user, country IE) and determine what to allow based on its
-internal EEPROM data. Devices drivers wishing to be capable of world
-roaming should use this callback. More on world roaming will be
-added to this document when its support is enabled.
-
-Device drivers who provide their own built regulatory domain
-do not need a callback as the channels registered by them are
-the only ones that will be allowed and therefore *additional*
-channels cannot be enabled.
-
-Example code - drivers hinting an alpha2:
-------------------------------------------
-
-This example comes from the zd1211rw device driver. You can start
-by having a mapping of your device's EEPROM country/regulatory
-domain value to a specific alpha2 as follows:
-
-static struct zd_reg_alpha2_map reg_alpha2_map[] = {
-       { ZD_REGDOMAIN_FCC, "US" },
-       { ZD_REGDOMAIN_IC, "CA" },
-       { ZD_REGDOMAIN_ETSI, "DE" }, /* Generic ETSI, use most restrictive */
-       { ZD_REGDOMAIN_JAPAN, "JP" },
-       { ZD_REGDOMAIN_JAPAN_ADD, "JP" },
-       { ZD_REGDOMAIN_SPAIN, "ES" },
-       { ZD_REGDOMAIN_FRANCE, "FR" },
-
-Then you can define a routine to map your read EEPROM value to an alpha2,
-as follows:
-
-static int zd_reg2alpha2(u8 regdomain, char *alpha2)
-{
-       unsigned int i;
-       struct zd_reg_alpha2_map *reg_map;
-               for (i = 0; i < ARRAY_SIZE(reg_alpha2_map); i++) {
-                       reg_map = &reg_alpha2_map[i];
-                       if (regdomain == reg_map->reg) {
-                       alpha2[0] = reg_map->alpha2[0];
-                       alpha2[1] = reg_map->alpha2[1];
-                       return 0;
-               }
-       }
-       return 1;
-}
-
-Lastly, you can then hint to the core of your discovered alpha2, if a match
-was found. You need to do this after you have registered your wiphy. You
-are expected to do this during initialization.
-
-       r = zd_reg2alpha2(mac->regdomain, alpha2);
-       if (!r)
-               regulatory_hint(hw->wiphy, alpha2);
-
-Example code - drivers providing a built in regulatory domain:
---------------------------------------------------------------
-
-[NOTE: This API is not currently available, it can be added when required]
-
-If you have regulatory information you can obtain from your
-driver and you *need* to use this we let you build a regulatory domain
-structure and pass it to the wireless core. To do this you should
-kmalloc() a structure big enough to hold your regulatory domain
-structure and you should then fill it with your data. Finally you simply
-call regulatory_hint() with the regulatory domain structure in it.
-
-Bellow is a simple example, with a regulatory domain cached using the stack.
-Your implementation may vary (read EEPROM cache instead, for example).
-
-Example cache of some regulatory domain
-
-struct ieee80211_regdomain mydriver_jp_regdom = {
-       .n_reg_rules = 3,
-       .alpha2 =  "JP",
-       //.alpha2 =  "99", /* If I have no alpha2 to map it to */
-       .reg_rules = {
-               /* IEEE 802.11b/g, channels 1..14 */
-               REG_RULE(2412-10, 2484+10, 40, 6, 20, 0),
-               /* IEEE 802.11a, channels 34..48 */
-               REG_RULE(5170-10, 5240+10, 40, 6, 20,
-                       NL80211_RRF_NO_IR),
-               /* IEEE 802.11a, channels 52..64 */
-               REG_RULE(5260-10, 5320+10, 40, 6, 20,
-                       NL80211_RRF_NO_IR|
-                       NL80211_RRF_DFS),
-       }
-};
-
-Then in some part of your code after your wiphy has been registered:
-
-       struct ieee80211_regdomain *rd;
-       int size_of_regd;
-       int num_rules = mydriver_jp_regdom.n_reg_rules;
-       unsigned int i;
-
-       size_of_regd = sizeof(struct ieee80211_regdomain) +
-               (num_rules * sizeof(struct ieee80211_reg_rule));
-
-       rd = kzalloc(size_of_regd, GFP_KERNEL);
-       if (!rd)
-               return -ENOMEM;
-
-       memcpy(rd, &mydriver_jp_regdom, sizeof(struct ieee80211_regdomain));
-
-       for (i=0; i < num_rules; i++)
-               memcpy(&rd->reg_rules[i],
-                      &mydriver_jp_regdom.reg_rules[i],
-                      sizeof(struct ieee80211_reg_rule));
-       regulatory_struct_hint(rd);
-
-Statically compiled regulatory database
----------------------------------------
-
-When a database should be fixed into the kernel, it can be provided as a
-firmware file at build time that is then linked into the kernel.
index ea5dd3d1df9d0d857e1fc435e5ca4529f86aae18..b28823ab48c52590d8a188f3ee552430b0d8cae9 100644 (file)
@@ -193,7 +193,7 @@ W:  https://wireless.wiki.kernel.org/
 T:     git git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211.git
 T:     git git://git.kernel.org/pub/scm/linux/kernel/git/jberg/mac80211-next.git
 F:     Documentation/driver-api/80211/cfg80211.rst
-F:     Documentation/networking/regulatory.txt
+F:     Documentation/networking/regulatory.rst
 F:     include/linux/ieee80211.h
 F:     include/net/cfg80211.h
 F:     include/net/ieee80211_radiotap.h