share/man/man9/ieee80211.9

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