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