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.1 2004/07/27 14:50:56 hmp 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 , 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 ifnet *ifp" 47.Ft void 48.Fn ieee80211_ifdetach "struct ifnet *ifp" 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 ifnet *ifp" "ifm_change_cb_t media_change" 58.Fa "ifm_stat_cb_t media_stat" 59.Fc 60.Fa int 61.Fn ieee80211_media_change "struct ifnet *ifp" 62.Fa void 63.Fn ieee80211_media_status "struct ifnet *ifp" "struct ifmediareq *imr" 64.Ft void 65.Fn ieee80211_watchdog "struct ifnet *ifp" 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 network interface 92.Fa ifp 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; 97The 98.Vt struct ifnet 99instance pointed to by 100.Fa ifp 101MUST be an instance of 102.Vt struct ieee80211com , 103with various fields initialized to tell 104.Nm ieee80211 105about its capabilities. 106This function performs Ethernet and BPF attachment (by calling 107.Fn ether_ifattach 108and 109.Fn bpfattach2 ) 110on behalf of the caller. 111It also implements the 112.Vt ifmedia 113interface. 114.Pp 115.\" 116The 117.Fn ieee80211_ifdetach 118function frees any 119.Nm ieee80211 120structures associated with the driver, and performs Ethernet and BPF 121detachment on behalf of the caller. 122.Pp 123.\" 124The 125.Fn ieee80211_mhz2ieee 126utility function converts the frequency 127.Fa freq 128(specified in MHz) to an IEEE 802.11 channel number. 129The 130.Fa flags 131argument is a hint which specifies whether the frequency is in 132the 2GHz ISM band 133.Pq Vt IEEE80211_CHAN_2GHZ 134or the 5GHz band 135.Pq Vt IEEE80211_CHAN_5GHZ ; 136appropriate clipping of the result is then performed. 137.Pp 138.\" 139The 140.Fn ieee80211_chan2ieee 141function converts the channel specified in 142.Fa *c 143to an IEEE channel number for the driver 144.Fa ic . 145If the conversion would be invalid, an error message is printed to the 146system console. 147This function REQUIRES that the driver is hooked up to the 148.Nm ieee80211 149subsystem. 150.Pp 151.\" 152The 153.Fn ieee80211_ieee2mhz 154utility function converts the IEEE channel number 155.Ft chan 156to a frequency (in MHz). 157The 158.Fa flags 159argument is a hint which specifies whether the frequency is in 160the 2GHz ISM band 161.Pq Vt IEEE80211_CHAN_2GHZ 162or the 5GHz band 163.Pq Vt IEEE80211_CHAN_5GHZ ; 164appropriate clipping of the result is then performed. 165.Pp 166.\" 167The 168.Fn ieee80211_media_init 169function initializes media data structures used by the 170.Vt ifmedia 171interface, for the driver 172.Fa ifp . 173It must be called by the driver after calling 174.Fn ieee80211_attach 175and before calling most 176.Nm ieee80211 177functions. 178The 179.Fa media_change 180and 181.Fa media_stat 182arguments specify helper functions which will be invoked by the 183.Vt ifmedia 184framework when the user changes or queries media options, 185using a command such as 186.Xr ifconfig 8 . 187.Pp 188.\" 189The 190.Fn ieee80211_media_status 191and 192.Fn ieee80211_media_change 193functions are device-independent handlers for 194.Vt ifmedia 195commands and are not intended to be called directly. 196.Pp 197.\" 198The 199.Fn ieee80211_watchdog 200function is intended to be called from a driver's 201.Va if_watchdog 202routine. 203It is used to perform periodic cleanup of state within the software 802.11 204stack, as well as timing out scans. 205.Pp 206.\" 207The 208.Fn ieee80211_setmode 209function is called from within the 802.11 stack to change the mode 210of the driver's PHY; it is not intended to be called directly. 211.Pp 212.\" 213The 214.Fn ieee80211_chan2mode 215function returns the PHY mode required for use with the channel 216.Fa chan 217on the device 218.Fa ic . 219This is typically used when selecting a rate set, to be advertised in 220beacons, for example. 221.Pp 222.\" 223The 224.Fn ieee80211_rate2media 225function converts the bit rate 226.Fa rate 227(measured in units of 0.5Mbps) to an 228.Vt ifmedia 229sub-type, for the device 230.Fa ic 231running in PHY mode 232.Fa mode . 233The 234.Fn ieee80211_media2rate 235performs the reverse of this conversion, returning the bit rate (in 0.5Mbps 236units) corresponding to an 237.Vt ifmedia 238sub-type. 239.\" 240.Sh SEE ALSO 241.Xr ieee80211_crypto 9 , 242.Xr ieee80211_input 9 , 243.Xr ieee80211_ioctl 9 , 244.Xr ieee80211_node 9 , 245.Xr ieee80211_output 9 , 246.Xr ieee80211_proto 9 , 247.Xr ieee80211_radiotap 9 , 248.Xr ifnet 9 249.Sh HISTORY 250The 251.Nm ieee80211 252series of functions first appeared in 253.Nx 1.5 , 254and were later ported to 255.Fx 4.6 . 256.Sh AUTHORS 257.An -nosplit 258This man page was written by 259.An Bruce M. Simpson Aq bms@FreeBSD.org 260and 261.An Darron Broad Aq darron@kewl.org . 262