1.\" 2.\" Copyright (c) 2009 Sam Leffler, Errno Consulting 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd August 4, 2009 27.Dt IEEE80211_REGDOMAIN 9 28.Os 29.Sh NAME 30.Nm ieee80211_regdomain 31.Nd 802.11 regulatory support 32.Sh SYNOPSIS 33.In net80211/ieee80211_var.h 34.In net80211/ieee80211_regdomain.h 35.Pp 36.Ft int 37.Fo ieee80211_init_channels 38.Fa "struct ieee80211com *" 39.Fa "const struct ieee80211_regdomain *" 40.Fa "const uint8_t bands[]" 41.Fc 42.\" 43.Ft void 44.Fo ieee80211_sort_channels 45.Fa "struct ieee80211_channel *" 46.Fa "int nchans" 47.Fc 48.\" 49.Ft "struct ieee80211_appie *" 50.Fn ieee80211_alloc_countryie "struct ieee80211com *" 51.Sh DESCRIPTION 52The 53.Nm net80211 54software layer provides a support framework for drivers that includes 55comprehensive regulatory support. 56.Nm net80211 57provides mechanisms that enforce 58.Em "regulatory policy" 59by privileged user applications. 60.Pp 61Drivers define a device's capabilities and can 62intercept and control regulatory changes requested through 63.Nm net80211 . 64The initial regulatory state, including the channel list, must be 65filled in by the driver before calling 66.Fn ieee80211_ifattach . 67The channel list should reflect the set of channels the device is 68.Em calibrated 69for use on. 70This list may also be requested later through the 71.Vt ic_getradiocaps 72method in the 73.Vt ieee80211com 74structure. 75The 76.Fn ieee80211_init_channels 77function is provided as a rudimentary fallback for drivers that do not 78(or cannot) fill in a proper channel list. 79Default regulatory state is supplied such as the regulatory SKU, 80ISO country code, location (e.g. indoor, outdoor), and a set of 81frequency bands the device is capable of operating on. 82.Nm net80211 83populates the channel table in 84.Vt ic_channels 85with a default set of channels and capabilities. 86Note this mechanism should be used with care as any mismatch between 87the channel list created and the device's capabilities can result 88in runtime errors (e.g. a request to operate on a channel the device 89does not support). 90The SKU and country information are used for generating 802.11h protocol 91elements and related operation such as for 802.11d; mis-setup by a 92driver is not fatal, only potentially confusing. 93.Pp 94Devices that do not have a fixed/default regulatory state can set 95the regulatory SKU to 96.Dv SKU_DEBUG 97and country code to 98.Dv CTRY_DEFAULT 99and leave proper setup to user applications. 100If default settings are known they can be installed and/or an event 101can be dispatched to user space using 102.Fn ieee80211_notify_country 103so that 104.Xr devd 8 105will do the appropriate setup work at system boot (or device insertion). 106.Pp 107The channel table is sorted to optimize lookups using the 108.Fn ieee80211_sort_channels 109routine. 110This should be done whenever the channel table contents are modified. 111.Pp 112The 113.Fn ieee80211_alloc_countryie 114function allocates an information element as specified by 802.11h. 115Because this is expensive to generate it is cached in 116.Vt ic_countryie 117and generated only when regulatory state changes. 118Drivers that call 119.Fn ieee80211_alloc_countryie 120directly should not help with this caching; doing so may confuse the 121.Nm net80211 122layer. 123.Sh DRIVER REGULATORY CONTROL 124Drivers can control regulatory change requests by overriding the 125.Vt ic_setregdomain 126method that checks change requests. 127While drivers can reject any request that does not meet its requirements 128it is recommended that one be lenient in what is accepted and, whenever 129possible, instead of rejecting a request, alter it to be correct. 130For example, if the transmit power cap for a channel is too high the 131driver can either reject the request or (better) reduce the cap to be 132compliant. 133Requests that include unacceptable channels should cause the request 134to be rejected as otherwise a mismatch may be created between application 135state and the state managed by 136.Nm net80211 . 137The exact rules by which to operate are still being codified. 138.Sh SEE ALSO 139.Xr regdomain 5 , 140.Xr ifconfig 8 , 141.Xr ieee80211 9 142