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