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