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