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