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