1.\" $NetBSD: ieee80211.9,v 1.4 2006/09/17 12:11:46 wiz Exp $ 2.\" 3.\" 4.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> 5.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD: src/share/man/man9/ieee80211.9,v 1.3 2004/07/07 12:59:39 ru Exp $ 30.\" 31.Dd September 12, 2006 32.Dt IEEE80211 9 33.Os 34.Sh NAME 35.Nm ieee80211_ifattach , ieee80211_ifdetach , 36.Nm ieee80211_mhz2ieee , ieee80211_chan2ieee , ieee80211_ieee2mhz , 37.Nm ieee80211_media_init , ieee80211_media_change , ieee80211_media_status , 38.Nm ieee80211_watchdog , 39.Nm ieee80211_setmode , ieee80211_chan2mode , 40.Nm ieee80211_rate2media , ieee80211_media2rate 41.Nd core 802.11 network stack functions 42.Sh SYNOPSIS 43.In net80211/ieee80211_var.h 44.In net80211/ieee80211_proto.h 45.Ft void 46.Fn ieee80211_ifattach "struct ieee80211com *ic" 47.Ft void 48.Fn ieee80211_ifdetach "struct ieee80211com *ic" 49.Ft u_int 50.Fn ieee80211_mhz2ieee "u_int freq" "u_int flags" 51.Ft u_int 52.Fn ieee80211_chan2ieee "struct ieee80211com *ic" "struct ieee80211_channel *c" 53.Ft u_int 54.Fn ieee80211_ieee2mhz "u_int chan" "u_int flags" 55.Ft void 56.Fo ieee80211_media_init 57.Fa "struct ieee80211com *ic" "ifm_change_cb_t media_change" 58.Fa "ifm_stat_cb_t media_stat" 59.Fc 60.Ft int 61.Fn ieee80211_media_change "struct ifnet *ifp" 62.Ft void 63.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" 64.Ft void 65.Fn ieee80211_watchdog "struct ieee80211com *ic" 66.Ft int 67.Fn ieee80211_setmode "struct ieee80211com *ic" "enum ieee80211_phymode mode" 68.Ft enum ieee80211_phymode 69.Fo ieee80211_chan2mode 70.Fa "struct ieee80211com *ic" "struct ieee80211_channel *chan" 71.Fc 72.Ft int 73.Fo ieee80211_rate2media 74.Fa "struct ieee80211com *ic" "int rate" "enum ieee80211_phymode mode" 75.Fc 76.Ft int 77.Fn ieee80211_media2rate "int mword" 78.Sh DESCRIPTION 79The 80.Nm ieee80211 81collection of functions are used to manage wireless network interfaces in the 82system which use the system's software 802.11 network stack. 83Most of these functions require that attachment to the stack is performed 84before calling. 85Several utility functions are also provided; these are safe to call from 86any driver without prior initialization. 87.Pp 88.\" 89The 90.Fn ieee80211_ifattach 91function attaches the wireless network interface 92.Fa ic 93to the 802.11 network stack layer. 94This function must be called before using any of the 95.Nm ieee80211 96functions which need to store driver state across invocations. 97This function also performs Ethernet and BPF attachment (by calling 98.Fn ether_ifattach 99and 100.Fn bpfattach2 ) 101on behalf of the caller. 102.Pp 103.\" 104The 105.Fn ieee80211_ifdetach 106function frees any 107.Nm ieee80211 108structures associated with the driver, and performs Ethernet and BPF 109detachment on behalf of the caller. 110.Pp 111.\" 112The 113.Fn ieee80211_mhz2ieee 114utility function converts the frequency 115.Fa freq 116(specified in MHz) to an IEEE 802.11 channel number. 117The 118.Fa flags 119argument is a hint which specifies whether the frequency is in 120the 2GHz ISM band 121.Pq Vt IEEE80211_CHAN_2GHZ 122or the 5GHz band 123.Pq Vt IEEE80211_CHAN_5GHZ ; 124appropriate clipping of the result is then performed. 125.Pp 126.\" 127The 128.Fn ieee80211_chan2ieee 129function converts the channel specified in 130.Fa *c 131to an IEEE channel number for the driver 132.Fa ic . 133If the conversion would be invalid, an error message is printed to the 134system console. 135This function REQUIRES that the driver is hooked up to the 136.Nm ieee80211 137subsystem. 138.Pp 139.\" 140The 141.Fn ieee80211_ieee2mhz 142utility function converts the IEEE channel number 143.Ft chan 144to a frequency (in MHz). 145The 146.Fa flags 147argument is a hint which specifies whether the frequency is in 148the 2GHz ISM band 149.Pq Vt IEEE80211_CHAN_2GHZ 150or the 5GHz band 151.Pq Vt IEEE80211_CHAN_5GHZ ; 152appropriate clipping of the result is then performed. 153.Pp 154.\" 155The 156.Fn ieee80211_media_init 157function initializes media data structures used by the 158.Vt ifmedia 159interface for the driver 160.Fa ic . 161It must be called by the driver after calling 162.Fn ieee80211_ifattach 163and before calling most 164.Nm ieee80211 165functions. 166The 167.Fa media_change 168and 169.Fa media_stat 170arguments specify helper functions which will be invoked by the 171.Vt ifmedia 172framework when the user changes or queries media options, 173using a command such as 174.Xr ifconfig 8 . 175.Pp 176.\" 177The 178.Fn ieee80211_media_status 179and 180.Fn ieee80211_media_change 181functions are device-independent handlers for 182.Vt ifmedia 183commands and are not intended to be called directly. 184.Pp 185.\" 186The 187.Fn ieee80211_watchdog 188function is intended to be called from a driver's 189.Va if_watchdog 190routine. 191It is used to perform periodic cleanup of state within the software 802.11 192stack, as well as timing out scans. 193.Pp 194.\" 195The 196.Fn ieee80211_setmode 197function is called from within the 802.11 stack to change the mode 198of the driver's PHY; it is not intended to be called directly. 199.Pp 200.\" 201The 202.Fn ieee80211_chan2mode 203function returns the PHY mode required for use with the channel 204.Fa chan 205on the device 206.Fa ic . 207This is typically used when selecting a rate set, to be advertised in 208beacons, for example. 209.Pp 210.\" 211The 212.Fn ieee80211_rate2media 213function converts the bit rate 214.Fa rate 215(measured in units of 0.5Mbps) to an 216.Vt ifmedia 217sub-type, for the device 218.Fa ic 219running in PHY mode 220.Fa mode . 221The 222.Fn ieee80211_media2rate 223performs the reverse of this conversion, returning the bit rate (in 0.5Mbps 224units) corresponding to an 225.Vt ifmedia 226sub-type. 227.\" 228.Sh SEE ALSO 229.Xr ieee80211_crypto 9 , 230.Xr ieee80211_input 9 , 231.Xr ieee80211_ioctl 9 , 232.Xr ieee80211_node 9 , 233.Xr ieee80211_output 9 , 234.Xr ieee80211_proto 9 , 235.Xr ieee80211_radiotap 9 236.Sh HISTORY 237The 238.Nm ieee80211 239series of functions first appeared in 240.Nx 1.5 , 241and were later ported to 242.Fx 4.6 . 243.Sh AUTHORS 244.An -nosplit 245This man page was written by 246.An Bruce M. Simpson Aq bms@FreeBSD.org 247and 248.An Darron Broad Aq darron@kewl.org . 249