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.\" $FreeBSD: src/share/man/man9/ieee80211_regdomain.9,v 1.2 2009/09/18 00:33:47 brueffer Exp $ 27.\" 28.Dd April 28, 2010 29.Dt IEEE80211_REGDOMAIN 9 30.Os 31.Sh NAME 32.Nm ieee80211_regdomain 33.Nd 802.11 regulatory support 34.Sh SYNOPSIS 35.In net/if.h 36.In net/if_media.h 37.In netproto/802_11/ieee80211_var.h 38.In netproto/802_11/ieee80211_regdomain.h 39.Pp 40.Ft int 41.Fo ieee80211_init_channels 42.Fa "struct ieee80211com *" 43.Fa "const struct ieee80211_regdomain *" 44.Fa "const uint8_t bands[]" 45.Fc 46.\" 47.Ft void 48.Fo ieee80211_sort_channels 49.Fa "struct ieee80211_channel *" 50.Fa "int nchans" 51.Fc 52.\" 53.Ft "struct ieee80211_appie *" 54.Fn ieee80211_alloc_countryie "struct ieee80211com *" 55.Sh DESCRIPTION 56The 57.Nm net80211 58software layer provides a support framework for drivers that includes 59comprehensive regulatory support. 60.Nm net80211 61provides mechanisms that enforce 62.Em "regulatory policy" 63by privileged user applications. 64.Pp 65Drivers define a device's capabilities and can 66intercept and control regulatory changes requested through 67.Nm net80211 . 68The initial regulatory state, including the channel list, must be 69filled in by the driver before calling 70.Fn ieee80211_ifattach . 71The channel list should reflect the set of channels the device is 72.Em calibrated 73for use on. 74This list may also be requested later through the 75.Vt ic_getradiocaps 76method in the 77.Vt ieee80211com 78structure. 79The 80.Fn ieee80211_init_channels 81function is provided as a rudimentary fallback for drivers that do not 82(or cannot) fill in a proper channel list. 83Default regulatory state is supplied such as the regulatory SKU, 84ISO country code, location (e.g. indoor, outdoor), and a set of 85frequency bands the device is capable of operating on. 86.Nm net80211 87populates the channel table in 88.Vt ic_channels 89with a default set of channels and capabilities. 90Note this mechanism should be used with care as any mismatch between 91the channel list created and the device's capabilities can result 92in runtime errors (e.g. a request to operate on a channel the device 93does not support). 94The SKU and country information are used for generating 802.11h protocol 95elements and related operation such as for 802.11d; mis-setup by a 96driver is not fatal, only potentially confusing. 97.Pp 98Devices that do not have a fixed/default regulatory state can set 99the regulatory SKU to 100.Dv SKU_DEBUG 101and country code to 102.Dv CTRY_DEFAULT 103and leave proper setup to user applications. 104If default settings are known they can be installed and/or an event 105can be dispatched to user space using 106.Fn ieee80211_notify_country 107so that 108.Xr devd 8 109will do the appropriate setup work at system boot (or device insertion). 110.Pp 111The channel table is sorted to optimize lookups using the 112.Fn ieee80211_sort_channels 113routine. 114This should be done whenever the channel table contents are modified. 115.Pp 116The 117.Fn ieee80211_alloc_countryie 118function allocates an information element as specified by 802.11h. 119Because this is expensive to generate it is cached in 120.Vt ic_countryie 121and generated only when regulatory state changes. 122Drivers that call 123.Fn ieee80211_alloc_countryie 124directly should not help with this caching; doing so may confuse the 125.Nm net80211 126layer. 127.Sh DRIVER REGULATORY CONTROL 128Drivers can control regulatory change requests by overriding the 129.Vt ic_setregdomain 130method that checks change requests. 131While drivers can reject any request that does not meet its requirements 132it is recommended that one be lenient in what is accepted and, whenever 133possible, instead of rejecting a request, alter it to be correct. 134For example, if the transmit power cap for a channel is too high the 135driver can either reject the request or (better) reduce the cap to be 136compliant. 137Requests that include unacceptable channels should cause the request 138to be rejected as otherwise a mismatch may be created between application 139state and the state managed by 140.Nm net80211 . 141The exact rules by which to operate are still being codified. 142.Sh SEE ALSO 143.Xr regdomain 5 , 144.Xr ifconfig 8 , 145.Xr ieee80211 9 146