Linux wireless regulatory infrastructure

Userspace regulatory domain과 regulatory.db

이 문서는 Linux wireless regulatory infrastructure가 동작하는 방식을 간략히 설명합니다. 더 최신 정보는 원문에 연결된 wireless wiki의 Regulatory project page에서 확인할 수 있습니다.

국가별 무선 규정은 계속 바뀌므로 regulatory domain data는 userspace에 유지합니다. Framework는 userspace가 regulatory domain 하나를 kernel에 올려 중앙 core regulatory domain으로 사용하게 하며, system의 모든 wireless device는 이 제약을 따라야 합니다.

Regulatory subsystem을 처음 설정할 때 kernel은 모든 regulatory rule이 들어 있는 database firmware file `regulatory.db`를 요청합니다. 이후 특정 country의 규칙이 필요할 때 이 database에서 해당 alpha2 country code를 조회합니다.

.. 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:

https://wireless.wiki.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.

이전 CRDA·udev 해결 방식

이 절은 `old CRDA solution`을 설명합니다. Userspace agent가 요청된 regulatory domain을 구성해 `nl80211`로 kernel에 보내며, kernel은 자신이 기대한 regulatory domain만 받아들입니다.

그 역할을 수행하던 agent가 CRDA(Central Regulatory Domain Agent)입니다. Kernel이 새 regulatory domain이 필요하다고 판단하면 udev event를 내보내고, udev rule이 `/sbin/crda`를 실행해 특정 ISO/IEC 3166 alpha2에 해당하는 domain을 전달합니다.

예제 rule은 `/etc/udev/rules.d/regulatory.rules`에 두며 `regulatory*` kernel object의 platform subsystem `change` action에서 CRDA를 실행합니다. 요청 alpha2는 `COUNTRY` environment variable로 전달됩니다.

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:

https://wireless.wiki.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.

User·subsystem·driver의 regulatory request

User는 `iw`를 사용해 regulatory domain을 요청할 수 있습니다. 예를 들어 `iw reg set CR`은 Costa Rica를 뜻하는 alpha2 `CR`을 kernel에 지정합니다. Kernel은 userspace가 해당 alpha2의 regulatory domain을 제공하도록 uevent를 보냅니다.

Wireless subsystem도 Country Information element를 바탕으로 새 regulatory domain이 필요하다는 uevent를 userspace에 보낼 수 있습니다. 원문은 이 통합에 관한 설명이 향후 추가될 것이라고 명시합니다.

Driver가 특정 regulatory domain이 필요하다고 판단하면 `regulatory_hint()`로 wireless core에 알립니다. 첫 번째 방식은 alpha2를 제공해 CRDA가 해당 국가 domain을 돌려주게 하는 것이고, 두 번째 방식은 driver 내부 지식으로 자체 regulatory domain을 만들어 core가 이를 따르게 하는 것입니다.

대부분의 driver는 alpha2 hint 방식을 사용합니다. 이 경우 device EEPROM의 custom regulatory data로 중앙 domain을 한 번 더 제한하려면 `struct wiphy`에 `reg_notifier()` callback을 등록할 수 있습니다. Core regulatory domain이 바뀔 때 callback이 호출되며, driver는 변경 내용과 변경 주체가 driver·user·country IE 중 누구인지 확인해 EEPROM 기준으로 허용 범위를 결정합니다.

World roaming을 지원하려는 device driver는 이 callback을 사용해야 합니다. 반대로 자체 built regulatory domain을 제공한 driver는 자신이 등록한 channel만 허용되므로 callback이 없어도 추가 channel이 활성화될 수 없습니다.

Who asks for regulatory domains?
--------------------------------

* Users

Users can use iw:

https://wireless.wiki.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 specified 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.

EEPROM 값에서 alpha2를 hint하는 driver

`zd1211rw` 예제는 device EEPROM의 country 또는 regulatory domain 값을 ISO alpha2로 mapping합니다. `ZD_REGDOMAIN_FCC`는 `US`, `IC`는 `CA`, generic ETSI는 가장 보수적인 예로 `DE`, Japan 계열은 `JP`, Spain은 `ES`, France는 `FR`에 연결합니다.

`zd_reg2alpha2(u8 regdomain, char *alpha2)`는 `reg_alpha2_map` 배열을 순회해 EEPROM 값과 일치하는 entry를 찾고 두 글자를 output buffer에 복사합니다. 일치하면 0, 찾지 못하면 1을 반환합니다. 원문의 배열과 함수 code는 줄 좌표와 함께 그대로 보존됩니다.

Driver는 `wiphy`를 등록한 뒤 initialization 과정에서 mapping을 수행해야 합니다. Match가 발견되면 `regulatory_hint(hw->wiphy, alpha2)`를 호출해 wireless core에 발견한 alpha2를 알립니다.

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);

Driver built-in regulatory domain 예제

원문은 이 API가 현재 제공되지 않으며 필요할 때 추가할 수 있다고 명시합니다. Driver가 가진 regulatory 정보를 반드시 사용해야 하는 경우를 가정해, 충분한 크기의 regulatory domain 구조체를 `kmalloc()` 계열로 할당하고 rule을 채운 뒤 wireless core에 전달하는 설계를 설명합니다.

예제 `mydriver_jp_regdom`은 alpha2 `JP`와 세 rule을 갖습니다. 2.4 GHz IEEE 802.11b/g channel 1..14, 5 GHz 802.11a channel 34..48의 `NL80211_RRF_NO_IR`, channel 52..64의 `NL80211_RRF_NO_IR | NL80211_RRF_DFS` 제약을 `REG_RULE`로 정의합니다. 대응 alpha2가 없다면 `99`를 쓰는 주석도 보존되어 있습니다.

`wiphy` 등록 뒤 code는 `sizeof(struct ieee80211_regdomain)`에 rule 수만큼 `sizeof(struct ieee80211_reg_rule)`을 더해 동적 크기를 계산합니다. `kzalloc(..., GFP_KERNEL)`이 실패하면 `-ENOMEM`을 반환하고, 성공하면 기본 구조체와 각 `reg_rules[i]`를 복사한 뒤 `regulatory_struct_hint(rd)`를 호출합니다.

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.

Below 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);

Kernel에 정적으로 연결하는 database

Regulatory database를 kernel에 고정해야 한다면 build 시 firmware file로 제공하고 그 결과를 kernel image에 link할 수 있습니다. 이는 runtime userspace database와 달리 build artifact 안에 규칙을 포함하는 경로입니다.

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.