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