About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / regulatory.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:11 EST.

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