[RFC] Proposed structure for Regulatory/Geographical Wireless database

[RFC] Proposed structure for Regulatory/Geographical Wireless database

[Larry Finger]

Thanks to all that responded to my earlier RFC. A number of changes in my thinking are based on 
those comments, which came from Christoph Hellwig, Rick Jones, Ulrich Kunitz, Faidon Liambotis, 
Jouni Malinen,  and Harald Welte.  The important points of my proposal are as follows:

* The database will be maintained as a text file to be processed by a userland daemon that will 
transform this database into the data structure needed by the ieee80211 code. In addition to the 
regulatory data, this file will also contain the information needed for the daemon to set the size 
of its data arrays dynamically.

* A new routine (ieee80211_init_geo ?) will be written to be called by the driver to load the geo 
structure into the kernel. Information passed to the daemon will be the country code in ASCII and 
whether the interface is to be used indoors or outdoors.

* Checksum routines will be used to validate the data base. Such a simple scheme will not inhibit 
anyone with moderate skills from hacking the channel/power settings, but such hacking will require 
some effort.

* Each channel in the resulting kernel data structure will have appropriate flags set indicating if 
it is to be used indoors, outdoors, or both. In addition, if the channel should be used only for 
passive scanning, a suitable flag will be set. In the 2.4 GHz band, a flag will indicate if it 
should be used for 802.11b, otherwise both b and g mode will be assumed. In the 5.0 GHz bands, a 
flag will be set if the channel is to conform with 802.11h or 802.11a standards.

The database consists of two sections. The first relates the Country Codes to a wireless group. The 
second section describes the channel parameters for the groups. Shown below is a fragment showing 
the Country Code - Group info for a few countries and the definitions for a few of the groups.

Please send me any comments, etc.

Larry

===================================================================
# text file for IEEE80211 Regulatory/Geographical information
#
# Version of 04 May 2006
#
# Information for dynamic array sizing
#
Number of Countries: 100
Number of Groups: 15
#
# Countries listed first
#
# group Country Code    Description
#
1       AT              Austria (Standard EU)
1       DE              Germany (Standard EU)
2       FRI             France Indoor (Not Guyana or La Reunion)
3       FRO             France Outdoor (Not Guyana or La Reunion)
4       FR1             French Departments of Guyana and La Reunion Indoor
5       FR2             French Departments of Guyana and La Reunion Outdoor
.
.
.
9       US              United States (FCC)
#
#
# Groups follow countries
#
Group 0         - Unspecified Country
#
# Band  Ch. Range       Ch. Spacing     Power   Flags
#
# Band - b, bg, a, or h
# Ch. Range - Minimum and Maximum Channels for this range
# Ch. Spacing - Number of channels between adjacent entries
# Power in mW EIRP
# Flag Codes
# B - Both Indoor and Outdoor
# I - Indoor Only
# O - Outdoor Only
# P - Passive Scan Only
#
bg        1 - 11        1                100    B
#
Group 1         - General European Union (EU)
#
bg        1 -  13       1                100    B
h        36 -  40       4                200    I
h        52 -  64       4                200    IP
h       100 - 140       4               1000    BP
#
Group 2         - France Indoor (Not Guyana or La Reunion)
#
bg        1 -  13       1                100    I
h        36 -  48       4                200    I
h        52 -  64       4                200    IP
h       100 - 140       4               1000    IP
#
Group 3         - France Outdoor (Not Guyana or La Reunion)
#
bg        1 -   8       1                100    O
bg        9 -  13       1                 10    O
h       100 - 140       4               1000    OP
.
.
.
.
#
Group 9         - US (FCC)
#
bg        1 -  11       1                100    B
a        36 -  40       4                200    I
a        52 -  64       4                200    B
a       149 - 161       4               1000    B
#

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Uli Kunitz]

Larry Finger wrote:

> * A new routine (ieee80211_init_geo ?) will be written to be called by the
> driver to load the geo structure into the kernel. Information passed to the
> daemon will be the country code in ASCII and whether the interface is to be
> used indoors or outdoors.

Would it be possible to support the regulatory domain codes as
used in the outdated table 105 in Corrigendum 1 for 802.11b? The
ZD1211 EEPROM contains only this code. An easy translation
function would be sufficient. Maybe the group codes could be
misused for it.

Uli
--
Uli Kunitz (kune@deine-taler.de)

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Larry Finger]

Uli Kunitz wrote:
> Larry Finger wrote:
> 
>> * A new routine (ieee80211_init_geo ?) will be written to be called by the
>> driver to load the geo structure into the kernel. Information passed to the
>> daemon will be the country code in ASCII and whether the interface is to be
>> used indoors or outdoors.
> 
> Would it be possible to support the regulatory domain codes as
> used in the outdated table 105 in Corrigendum 1 for 802.11b? The
> ZD1211 EEPROM contains only this code. An easy translation
> function would be sufficient. Maybe the group codes could be
> misused for it.

That certainly shouldn't be any difficulty. It could be done in the ZD1211 driver before it calls 
the ieee80211_init_geo routine, or it could be done in the regulatory daemon. I assume that the 
EEPROM contains X'10' for FCC regulations, X'31' for Spain, etc.

Larry

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Uli Kunitz]

Larry Finger wrote:

> Uli Kunitz wrote:
> > Larry Finger wrote:
> > 
> > > * A new routine (ieee80211_init_geo ?) will be written to be called by the
> > > driver to load the geo structure into the kernel. Information passed to
> > > the
> > > daemon will be the country code in ASCII and whether the interface is to
> > > be
> > > used indoors or outdoors.
> > 
> > Would it be possible to support the regulatory domain codes as
> > used in the outdated table 105 in Corrigendum 1 for 802.11b? The
> > ZD1211 EEPROM contains only this code. An easy translation
> > function would be sufficient. Maybe the group codes could be
> > misused for it.
> 
> That certainly shouldn't be any difficulty. It could be done in the ZD1211
> driver before it calls the ieee80211_init_geo routine, or it could be done in
> the regulatory daemon. I assume that the EEPROM contains X'10' for FCC
> regulations, X'31' for Spain, etc.
> 
> Larry

Yes, it could be done in the driver. But if there are other
drivers having the same issue, the helper function should be
integrated in the geo code.

Uli

-- 
Uli Kunitz - kune@deine-taler.de

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Dan Williams]

On Fri, 2006-05-05 at 15:14 -0500, Larry Finger wrote:
> Thanks to all that responded to my earlier RFC. A number of changes in my thinking are based on 
> those comments, which came from Christoph Hellwig, Rick Jones, Ulrich Kunitz, Faidon Liambotis, 
> Jouni Malinen,  and Harald Welte.  The important points of my proposal are as follows:
> 
> * The database will be maintained as a text file to be processed by a userland daemon that will 
> transform this database into the data structure needed by the ieee80211 code. In addition to the 
> regulatory data, this file will also contain the information needed for the daemon to set the size 
> of its data arrays dynamically.

Can you explain a bit more about the dynamic array aspect here?  What's
that about?  Shouldn't the geo-daemon be able to figure this stuff out
automatically and tell the ieee80211 stack how many countries and groups
there are?  It has to parse the file anyway, so it should surely know
how many groups and countries there are after parsing it.  (or do I just
not understand the issues...?)

> * A new routine (ieee80211_init_geo ?) will be written to be called by the driver to load the geo 
> structure into the kernel. Information passed to the daemon will be the country code in ASCII and 
> whether the interface is to be used indoors or outdoors.
> 
> * Checksum routines will be used to validate the data base. Such a simple scheme will not inhibit 
> anyone with moderate skills from hacking the channel/power settings, but such hacking will require 
> some effort.

What I'm concerned about is error reporting.  And as a distro packager,
I don't want any user to have to touch the geo file.  That's fine if
they do, but nobody should _have_ to.

For error reporting, if the geo file does not exist, or contains invalid
information, or if the checksum doesn't match for some reason, what's
the failure case?  It's not sufficient to just log that to dmesg and
fail the attempt, because then a program like wpa_supplicant or
NetworkManager will have no clue what the problem is if the driver just
returns ENOENT or EFILESUCKS or whatever.  This is the same problem we
currently have with missing firmware.  The failure case is not clearly
recognizable by the client.

If the geo data fails to be read, or fails to be validated by the
driver, user apps that are trying to make connection attempts need to
know exactly why the attempt failed, so they can inform users of the
failure in a smart way.  That information needs to come through the
driver, because user apps that make network connection attempts
shouldn't have to talk to the regulatory daemon _at all_.

Conceptually, the regulatory/geo daemon is part of the kernel and the
driver, and just happens to live in userspace because policy
+kernel==ohmygodbad.  But that means that it's the kernel's
responsibility to marshal the error information back to clients of the
wireless driver, not the clients problem to ask the regulatory/geo
daemon, if it's actually running, what the heck the problem is and why
the driver returned the error code it did.

U  NetworkManager     geo-daemon
------------|-----------|-----------
K           |           |
           driver/iee80211

Think of it as a V, not a triangle.  That's where we need to be WRT
error reporting.

Dan

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Larry Finger]

Dan Williams wrote:
> On Fri, 2006-05-05 at 15:14 -0500, Larry Finger wrote:
>> Thanks to all that responded to my earlier RFC. A number of changes in my thinking are based on 
>> those comments, which came from Christoph Hellwig, Rick Jones, Ulrich Kunitz, Faidon Liambotis, 
>> Jouni Malinen,  and Harald Welte.  The important points of my proposal are as follows:
>>
>> * The database will be maintained as a text file to be processed by a userland daemon that will 
>> transform this database into the data structure needed by the ieee80211 code. In addition to the 
>> regulatory data, this file will also contain the information needed for the daemon to set the size 
>> of its data arrays dynamically.
> 
> Can you explain a bit more about the dynamic array aspect here?  What's
> that about?  Shouldn't the geo-daemon be able to figure this stuff out
> automatically and tell the ieee80211 stack how many countries and groups
> there are?  It has to parse the file anyway, so it should surely know
> how many groups and countries there are after parsing it.  (or do I just
> not understand the issues...?)

The kernel only has a single geo object for each wireless interface initialized. The kernel routine 
would state which country it wanted to the daemon, which would supply that one from the entities 
created one when if parsed the database file. The dynamic aspect is to code the daemon in such a way 
that changing the number of countries and/or groups will not necessitate changing the code in the 
daemon.

>> * A new routine (ieee80211_init_geo ?) will be written to be called by the driver to load the geo 
>> structure into the kernel. Information passed to the daemon will be the country code in ASCII and 
>> whether the interface is to be used indoors or outdoors.
>>
>> * Checksum routines will be used to validate the data base. Such a simple scheme will not inhibit 
>> anyone with moderate skills from hacking the channel/power settings, but such hacking will require 
>> some effort.
> 
> What I'm concerned about is error reporting.  And as a distro packager,
> I don't want any user to have to touch the geo file.  That's fine if
> they do, but nobody should _have_ to.

I agree.

> For error reporting, if the geo file does not exist, or contains invalid
> information, or if the checksum doesn't match for some reason, what's
> the failure case?  It's not sufficient to just log that to dmesg and
> fail the attempt, because then a program like wpa_supplicant or
> NetworkManager will have no clue what the problem is if the driver just
> returns ENOENT or EFILESUCKS or whatever.  This is the same problem we
> currently have with missing firmware.  The failure case is not clearly
> recognizable by the client.

I plan to put the "unknown country" data into the init_geo routine. In case the geo database is not 
available, has been corrupted, or the daemon is not running, the parameters will be the minimal set 
of only bg channels 1-11 at minimum power and indoor usage. There would be a valid set of geo 
parameters in the ieee80211 structure - likely not the ones that were wanted, but a valid set. In 
addition, a failure code would be sent back to the driver, and the exact reason for the failure 
logged to dmesg.

> If the geo data fails to be read, or fails to be validated by the
> driver, user apps that are trying to make connection attempts need to
> know exactly why the attempt failed, so they can inform users of the
> failure in a smart way.  That information needs to come through the
> driver, because user apps that make network connection attempts
> shouldn't have to talk to the regulatory daemon _at all_.

Agreed.

> Conceptually, the regulatory/geo daemon is part of the kernel and the
> driver, and just happens to live in userspace because policy
> +kernel==ohmygodbad.  But that means that it's the kernel's
> responsibility to marshal the error information back to clients of the
> wireless driver, not the clients problem to ask the regulatory/geo
> daemon, if it's actually running, what the heck the problem is and why
> the driver returned the error code it did.
> 
> U  NetworkManager     geo-daemon
> ------------|-----------|-----------
> K           |           |
>            driver/iee80211
> 
> Think of it as a V, not a triangle.  That's where we need to be WRT
> error reporting.

I'm not sure what additional error reporting mechanisms could/should be implemented. Any suggestions?

Larry

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Jouni Malinen]

On Fri, May 05, 2006 at 03:14:35PM -0500, Larry Finger wrote:

> * A new routine (ieee80211_init_geo ?) will be written to be called by the 
> driver to load the geo structure into the kernel. Information passed to the 
> daemon will be the country code in ASCII and whether the interface is to be 
> used indoors or outdoors.

The driver may not know the country code, so there should be mechanism
for user space to override this.

> * Checksum routines will be used to validate the data base. Such a simple 
> scheme will not inhibit anyone with moderate skills from hacking the 
> channel/power settings, but such hacking will require some effort.

I did not see this included in the example file. Did you have more
detailed plans on how this would be done?

> * Each channel in the resulting kernel data structure will have appropriate 
> flags set indicating if it is to be used indoors, outdoors, or both. In 
> addition, if the channel should be used only for passive scanning, a 
> suitable flag will be set. In the 2.4 GHz band, a flag will indicate if it 
> should be used for 802.11b, otherwise both b and g mode will be assumed. In 
> the 5.0 GHz bands, a flag will be set if the channel is to conform with 
> 802.11h or 802.11a standards.

802.11h, radar detection, and DFS may need to be more complex than just
a one-bit value of it being enabled. Countries may have different
requirements for different areas related to 802.11h..

> The database consists of two sections. The first relates the Country Codes 
> to a wireless group. The second section describes the channel parameters 
> for the groups. Shown below is a fragment showing the Country Code - Group 
> info for a few countries and the definitions for a few of the groups.

One way to compress this and possible make maintaining quite a bit
easier would be to use two different set of groups: one for 2.4 GHz band
and another one for 5 GHz band. Many countries share the same
requirements for 2.4 GHz, but have different 5 GHz requirements.. This
is not really a requirement, but could end up making this easier to use.

> Number of Countries: 100
> Number of Groups: 15

These are not really needed and unless a tool is used to update this
file, they will most likely end up being out of sync at some point ;-).
The parser can just read through the file twice if it need to know these
numbers before parsing (though, that should not really be needed with
dynamic data structures)..

> # group Country Code    Description
> #
> 1       AT              Austria (Standard EU)
> 1       DE              Germany (Standard EU)
> 2       FRI             France Indoor (Not Guyana or La Reunion)
> 3       FRO             France Outdoor (Not Guyana or La Reunion)
> 4       FR1             French Departments of Guyana and La Reunion Indoor
> 5       FR2             French Departments of Guyana and La Reunion Outdoor

Country code has to be two characters to fit into country IE..

AT and DE are a good example of possible use for different 2.4 GHz and 5
GHz groups.. If I remember correctly, they have the same rules for 2.4
GHz, but different for 5 GHz.. (unless--of course--they already changed
them since I looked last time.. ;-)

> # Ch. Range - Minimum and Maximum Channels for this range
> # Ch. Spacing - Number of channels between adjacent entries

Other option would be to use start channel and number of channels.
Channel spacing is also fixed in practice (1 for 2.4 GHz, 4 for 5 GHz),
so it may not be needed here.

> # Power in mW EIRP

I would prefer to see the maximum TX power in dBm, not mW.

> # Flag Codes
> # B - Both Indoor and Outdoor
> # I - Indoor Only
> # O - Outdoor Only
> # P - Passive Scan Only

Some more flags may need to be added in the future. It looks like the
format used here makes this trivial to extend.

-- 
Jouni Malinen                                            PGP id EFC895FA

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Larry Finger]

Jouni Malinen wrote:
> On Fri, May 05, 2006 at 03:14:35PM -0500, Larry Finger wrote:
> 
> The driver may not know the country code, so there should be mechanism
> for user space to override this.

Do you think an environment variable would suffice, or do you propose another scheme?

>> * Checksum routines will be used to validate the data base. Such a simple 
>> scheme will not inhibit anyone with moderate skills from hacking the 
>> channel/power settings, but such hacking will require some effort.
> 
> I did not see this included in the example file. Did you have more
> detailed plans on how this would be done?

I was anticipating storing the output of an md5sum command in a separate file and comparing the 
contents of that file with one computed for the database when the daemon initializes. Is there a 
better scheme?

>> * Each channel in the resulting kernel data structure will have appropriate 
>> flags set indicating if it is to be used indoors, outdoors, or both. In 
>> addition, if the channel should be used only for passive scanning, a 
>> suitable flag will be set. In the 2.4 GHz band, a flag will indicate if it 
>> should be used for 802.11b, otherwise both b and g mode will be assumed. In 
>> the 5.0 GHz bands, a flag will be set if the channel is to conform with 
>> 802.11h or 802.11a standards.
> 
> 802.11h, radar detection, and DFS may need to be more complex than just
> a one-bit value of it being enabled. Countries may have different
> requirements for different areas related to 802.11h..

I'm afraid that I'm not quite ready for the complexity of 802.11h. Obviously, I need to do more reading.

>> The database consists of two sections. The first relates the Country Codes 
>> to a wireless group. The second section describes the channel parameters 
>> for the groups. Shown below is a fragment showing the Country Code - Group 
>> info for a few countries and the definitions for a few of the groups.
> 
> One way to compress this and possible make maintaining quite a bit
> easier would be to use two different set of groups: one for 2.4 GHz band
> and another one for 5 GHz band. Many countries share the same
> requirements for 2.4 GHz, but have different 5 GHz requirements.. This
> is not really a requirement, but could end up making this easier to use.

I don't think it makes too much difference, but I will consider your suggestion as the database 
starts to be more complete.

>> Number of Countries: 100
>> Number of Groups: 15
> 
> These are not really needed and unless a tool is used to update this
> file, they will most likely end up being out of sync at some point ;-).
> The parser can just read through the file twice if it need to know these
> numbers before parsing (though, that should not really be needed with
> dynamic data structures)..

Your point is well taken. I will remove that data.

>> # group Country Code    Description
>> #
>> 1       AT              Austria (Standard EU)
>> 1       DE              Germany (Standard EU)
>> 2       FRI             France Indoor (Not Guyana or La Reunion)
>> 3       FRO             France Outdoor (Not Guyana or La Reunion)
>> 4       FR1             French Departments of Guyana and La Reunion Indoor
>> 5       FR2             French Departments of Guyana and La Reunion Outdoor
> 
> Country code has to be two characters to fit into country IE..

This problem can be resolved for most of France as long as the driver supplies the country code and 
the indoor/outdoor flag. The table would then be:

Group 2         - France (Not Guyana or La Reunion)
#
bg        1 -   8       1                100    B
bg        9 -  13       1                100    I
bg        9 -  13       1                 10    O
h        36 -  48       4                200    I
h        52 -  64       4                200    IP
h       100 - 140       4               1000    IP
h       100 - 140       4               1000    OP

The details for the two unique French departments may have to come from the still undetermined 
802.11h information.

> AT and DE are a good example of possible use for different 2.4 GHz and 5
> GHz groups.. If I remember correctly, they have the same rules for 2.4
> GHz, but different for 5 GHz.. (unless--of course--they already changed
> them since I looked last time.. ;-)

Yes they have. Following the decision contained in 
http://europa.eu.int/eur-lex/lex/LexUriServ/LexUriServ.do?uri=CELEX:32005D0513:EN:NOT, all EU 
members and candidates are to adopt the same standards. Most already have. The differences are 
outlined in Appendix 3 of the the document downloaded through 
http://www.ero.dk/documentation/docs/docfiles.asp?docid=1622&wd=N. Things are changing so fast that 
the information for Greece has already changed. The bottom line is that for most EU countries, the 
requirements are identical.

>> # Ch. Range - Minimum and Maximum Channels for this range
>> # Ch. Spacing - Number of channels between adjacent entries
> 
> Other option would be to use start channel and number of channels.
> Channel spacing is also fixed in practice (1 for 2.4 GHz, 4 for 5 GHz),
> so it may not be needed here.

I decided that if I didn't use the channel spacing, someone would implement a 6 or 8 channel spacing 
in the 5 GHz bands.

>> # Power in mW EIRP
> 
> I would prefer to see the maximum TX power in dBm, not mW.

This change would have the advantage that the max power in Q5.2 format would fit in the u8 variable 
now allocated. I still have to check if any current driver is using this information.

>> # Flag Codes
>> # B - Both Indoor and Outdoor
>> # I - Indoor Only
>> # O - Outdoor Only
>> # P - Passive Scan Only
> 
> Some more flags may need to be added in the future. It looks like the
> format used here makes this trivial to extend.

I hope so.

Thanks for your thoughtful comments.

Larry

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Michael Buesch]

On Friday 05 May 2006 22:14, you wrote:
> # Groups follow countries
> #
> Group 0         - Unspecified Country
> #
> # Band  Ch. Range       Ch. Spacing     Power   Flags
          ^^^^^^^^^
Aren't there countries around, where there are gaps in the
allowed channel numbers? (Especially for 802.11a) So it would
not be an allowed "range", but an allowed list of channels.

-- 
Greetings Michael.

Re: [RFC] Proposed structure for Regulatory/Geographical Wireless database

[Larry Finger]

Michael Buesch wrote:
> On Friday 05 May 2006 22:14, you wrote:
>> # Groups follow countries
>> #
>> Group 0         - Unspecified Country
>> #
>> # Band  Ch. Range       Ch. Spacing     Power   Flags
>           ^^^^^^^^^
> Aren't there countries around, where there are gaps in the
> allowed channel numbers? (Especially for 802.11a) So it would
> not be an allowed "range", but an allowed list of channels.
> 

Yes, but the gaps are only in 802.11a that I know about. If there is a gap, then I use a second line 
as was shown in the example for the standard EU specs. In most cases, other factors change as well. 
I initially was going to specify the allowed channels, but the tables got very long. This way is 
more compact.

Larry