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