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