share/man/man9/ieee80211_radiotap.9

   1 .\"
   2 .\" Copyright (c) 2004  Bruce M. Simpson <bms@spc.org>,
   3 .\"                     Darron Broad <darron@kewl.org>,
   4 .\"                     David Young <dyoung@pobox.com>.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.7 2009/09/18 00:33:47 brueffer Exp $
  29 .\"
  30 .Dd April 28, 2010
  31 .Dt IEEE80211_RADIOTAP 9
  32 .Os
  33 .Sh NAME
  34 .Nm ieee80211_radiotap
  35 .Nd 802.11 device packet capture support
  36 .Sh SYNOPSIS
  37 .In net/if.h
  38 .In net/if_media.h
  39 .In netproto/802_11/ieee80211_var.h
  40 .\"
  41 .Pp
  42 .Ft void
  43 .Fo ieee80211_radiotap_attach
  44 .Fa "struct ieee80211com *"
  45 .Fa "struct ieee80211_radiotap_header *th"
  46 .Fa "int tlen"
  47 .Fa "uint32_t tx_radiotap"
  48 .Fa "struct ieee80211_radiotap_header *rh"
  49 .Fa "int rlen"
  50 .Fa "uint32_t rx_radiotap"
  51 .Fc
  52 .\"
  53 .Ft int
  54 .Fn ieee80211_radiotap_active_vap "struct ieee80211vap *"
  55 .\"
  56 .Ft int
  57 .Fn ieee80211_radiotap_active "struct ieee80211com *"
  58 .\"
  59 .Ft void
  60 .Fn ieee80211_radiotap_tx "struct ieee80211vap *" "struct mbuf *"
  61 .Sh DESCRIPTION
  62 The
  63 .Nm net80211
  64 layer used by 802.11 drivers includes support for a device-independent
  65 packet capture format called
  66 .Nm radiotap
  67 that is understood by tools such as
  68 .Xr tcpdump 1 .
  69 This facility is designed for capturing 802.11 traffic,
  70 including information that is not part of the normal 802.11 frame structure.
  71 .Pp
  72 Radiotap was designed to balance the desire for a hardware-independent,
  73 extensible capture format against the need to
  74 conserve CPU and memory bandwidth on embedded systems.
  75 These considerations led to a format consisting of
  76 a standard preamble followed by an extensible bitmap indicating the
  77 presence of optional capture fields.
  78 A
  79 .Nm net80211
  80 device driver supporting
  81 .Vt radiotap
  82 defines two packed structures that it shares with
  83 .Nm net80211 .
  84 These structures embed an instance of a
  85 .Vt ieee80211_radiotap_header
  86 structure at the beginning,
  87 with subsequent fields in the appropriate order,
  88 and macros to set the bits of the
  89 .Va it_present
  90 bitmap to indicate which fields exist and are filled in by the driver.
  91 This information is then supplied through the
  92 .Fn ieee80211_radiotap_attach
  93 call after a successful
  94 .Fn ieee80211_ifattach
  95 request.
  96 .Pp
  97 With radiotap setup, drivers just need to fill in per-packet
  98 capture state for frames sent/received and dispatch capture state
  99 in the transmit path (since control is not returned to the
 100 .Nm net80211
 101 layer before the packet is handed to the device).
 102 To minimize overhead this work should be done only when one
 103 or more processes are actively capturing data;
 104 this is checked with one of
 105 .Fn ieee80211_radiotap_active_vap
 106 and
 107 .Fn ieee80211_radiotap_active .
 108 In the transmit path capture work looks like this:
 109 .Bd -literal -offset indent
 110 if (ieee80211_radiotap_active_vap(vap)) {
 111         ... /* record transmit state */
 112         ieee80211_radiotap_tx(vap, m); /* capture transmit event */
 113 }
 114 .Ed
 115 .Pp
 116 While in the receive path capture is handled in
 117 .Nm net80211
 118 but state must be captured before dispatching a frame:
 119 .Bd -literal -offset indent
 120 if (ieee80211_radiotap_active(ic)) {
 121         ... /* record receive state */
 122 }
 123 \&...
 124 ieee80211_input(...);   /* packet capture handled in net80211 */
 125 .Ed
 126 .Pp
 127 .\"
 128 The following fields are defined for
 129 .Vt radiotap ,
 130 in the order in which they should appear in the buffer supplied
 131 to
 132 .Nm net80211 .
 133 .Bl -tag -width indent
 134 .It Dv IEEE80211_RADIOTAP_TSFT
 135 This field contains the unsigned 64-bit value, in microseconds,
 136 of the MAC's 802.11 Time Synchronization Function (TSF).
 137 In theory, for each received frame, this value is recorded
 138 when the first bit of the MPDU arrived at the MAC.
 139 In practice, hardware snapshots the TSF otherwise and one cannot assume
 140 this data is accurate without driver adjustment.
 141 .It Dv IEEE80211_RADIOTAP_FLAGS
 142 This field contains a single unsigned 8-bit value, containing one or
 143 more of these bit flags:
 144 .Bl -tag -width indent
 145 .It Dv IEEE80211_RADIOTAP_F_CFP
 146 Frame was sent/received during the Contention Free Period (CFP).
 147 .It Dv IEEE80211_RADIOTAP_F_SHORTPRE
 148 Frame was sent/received with short preamble.
 149 .It Dv IEEE80211_RADIOTAP_F_WEP
 150 Frame was encrypted.
 151 .It Dv IEEE80211_RADIOTAP_F_FRAG
 152 Frame was an 802.11 fragment.
 153 .It Dv IEEE80211_RADIOTAP_F_FCS
 154 Frame contents includes the FCS.
 155 .It Dv IEEE80211_RADIOTAP_F_DATAPAD
 156 Frame contents potentially has padding between the 802.11 header and the
 157 data payload to align the payload to a 32-bit boundary.
 158 .It Dv IEEE80211_RADIOTAP_F_BADFCS
 159 Frame was received with an invalid FCS.
 160 .It Dv IEEE80211_RADIOTAP_F_SHORTGI
 161 Frame was sent/received with Short Guard Interval.
 162 .El
 163 .It Dv IEEE80211_RADIOTAP_RATE
 164 This field contains a single unsigned 8-bit value that is the data rate.
 165 Legacy rates are in units of 500Kbps.
 166 MCS rates (used on 802.11n/HT channels) have the high bit set and
 167 the MCS in the low 7 bits.
 168 .It Dv IEEE80211_RADIOTAP_CHANNEL
 169 This field contains two unsigned 16-bit values.
 170 The first value is the center frequency for the channel
 171 the frame was sent/received on.
 172 The second value is a bitmap containing flags that specify channel properties.
 173 .Pp
 174 This field is deprecated in favor of
 175 .Dv IEEE80211_RADIOTAP_XCHANNEL
 176 but may be used to save space in the capture file for legacy devices.
 177 .\".It Dv IEEE80211_RADIOTAP_FHSS
 178 .\"This field contains two 8-bit values.
 179 .\"This field should be present only for frequency-hopping radios.
 180 .\"The first byte is the hop set.
 181 .\"The second byte is the pattern in use.
 182 .It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL
 183 This field contains a single signed 8-bit value that indicates the
 184 RF signal power at the antenna, in decibels difference from 1mW.
 185 .It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE
 186 This field contains a single signed 8-bit value that indicates the
 187 RF noise power at the antenna, in decibels difference from 1mW.
 188 .\".It Dv IEEE80211_RADIOTAP_LOCK_QUALITY
 189 .\"This field contains a single unsigned 16-bit value, indicating the
 190 .\"quality of the Barker Code lock.
 191 .\"No unit is specified for this field.
 192 .\"There does not appear to be a standard way of measuring this at this time;
 193 .\"this quantity is often referred to as
 194 .\".Dq "Signal Quality"
 195 .\"in some datasheets.
 196 .\".It Dv IEEE80211_RADIOTAP_TX_ATTENUATION
 197 .\"This field contains a single unsigned 16-bit value, expressing transmit
 198 .\"power as unitless distance from maximum power set at factory calibration.
 199 .\"0 indicates maximum transmit power.
 200 .\"Monotonically nondecreasing with lower power levels.
 201 .\".It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION
 202 .\"This field contains a single unsigned 16-bit value, expressing transmit
 203 .\"power as decibel distance from maximum power set at factory calibration.
 204 .\"0 indicates maximum transmit power.
 205 .\"Monotonically nondecreasing with lower power levels.
 206 .It Dv IEEE80211_RADIOTAP_DBM_TX_POWER
 207 Transmit power expressed as decibels from a 1mW reference.
 208 This field is a single signed 8-bit value.
 209 This is the absolute power level measured at the antenna port.
 210 .It Dv IEEE80211_RADIOTAP_ANTENNA
 211 This field contains a single unsigned 8-bit value that specifies
 212 which antenna was used to transmit or receive the frame.
 213 Antenna numbering is device-specific but typically the primary antenna has
 214 the lowest number.
 215 On transmit a value of zero may be seen which typically means
 216 antenna selection is left to the device.
 217 .It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL
 218 This field contains a single unsigned 8-bit value that indicates the
 219 RF signal power at the antenna, in decibels difference from an
 220 arbitrary, fixed reference.
 221 .It Dv IEEE80211_RADIOTAP_DB_ANTNOISE
 222 This field contains a single unsigned 8-bit value that indicates the
 223 RF noise power at the antenna, in decibels difference from an
 224 arbitrary, fixed reference.
 225 .It Dv IEEE80211_RADIOTAP_XCHANNEL
 226 This field contains four values: a 32-bit unsigned bitmap of
 227 flags that describe the channel attributes, a 16-bit unsigned
 228 frequency in MHz (typically the channel center), an 8-bit
 229 unsigned IEEE channel number, and a signed 8-bit value that
 230 holds the maximum regulatory transmit power cap in .5 dBm
 231 (8 bytes total).
 232 Channel flags are defined in:
 233 .In netproto/802_11/_ieee80211.h
 234 (only a subset are found in
 235 .In netproto/802_11/ieee80211_radiotap.h ).
 236 This property supersedes
 237 .Dv IEEE80211_RADIOTAP_CHANNEL
 238 and is the only way to completely express all
 239 channel attributes and the
 240 mapping between channel frequency and IEEE channel number.
 241 .El
 242 .Sh EXAMPLES
 243 Radiotap receive definitions for the Intersil Prism driver:
 244 .Bd -literal -offset indent
 245 #define WI_RX_RADIOTAP_PRESENT \\
 246         ((1 << IEEE80211_RADIOTAP_TSFT) \\
 247          (1 << IEEE80211_RADIOTAP_FLAGS) | \\
 248          (1 << IEEE80211_RADIOTAP_RATE) | \\
 249          (1 << IEEE80211_RADIOTAP_CHANNEL) | \\
 250          (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\
 251          (1 << IEEE80211_RADIOTAP_DB_ANTNOISE))
 252
 253 struct wi_rx_radiotap_header {
 254         struct ieee80211_radiotap_header wr_ihdr;
 255         uint64_t       wr_tsf;
 256         uint8_t        wr_flags;
 257         uint8_t        wr_rate;
 258         uint16_t       wr_chan_freq;
 259         uint16_t       wr_chan_flags;
 260         uint8_t        wr_antsignal;
 261         uint8_t        wr_antnoise;
 262 } __packed;
 263 .Ed
 264 .Pp
 265 and transmit definitions for the Atheros driver:
 266 .Bd -literal -offset indent
 267 #define ATH_TX_RADIOTAP_PRESENT (               \\
 268         (1 << IEEE80211_RADIOTAP_TSFT)          | \\
 269         (1 << IEEE80211_RADIOTAP_FLAGS)         | \\
 270         (1 << IEEE80211_RADIOTAP_RATE)          | \\
 271         (1 << IEEE80211_RADIOTAP_DBM_TX_POWER)  | \\
 272         (1 << IEEE80211_RADIOTAP_ANTENNA)       | \\
 273         (1 << IEEE80211_RADIOTAP_XCHANNEL)      | \\
 274         0)
 275
 276 struct ath_tx_radiotap_header {
 277         struct ieee80211_radiotap_header wt_ihdr;
 278         uint64_t       wt_tsf;
 279         uint8_t        wt_flags;
 280         uint8_t        wt_rate;
 281         uint8_t        wt_txpower;
 282         uint8_t        wt_antenna;
 283         uint32_t       wt_chan_flags;
 284         uint16_t       wt_chan_freq;
 285         uint8_t        wt_chan_ieee;
 286         int8_t         wt_chan_maxpow;
 287 } __packed;
 288 .Ed
 289 .Sh SEE ALSO
 290 .Xr tcpdump 1 ,
 291 .Xr bpf 4 ,
 292 .Xr ieee80211 9
 293 .Sh HISTORY
 294 The
 295 .Nm
 296 definitions first appeared in
 297 .Nx 1.5 .
 298 .\"
 299 .Sh AUTHORS
 300 .An -nosplit
 301 The original version of this manual page was written by
 302 .An Bruce M. Simpson Aq bms@FreeBSD.org
 303 and
 304 .An Darron Broad Aq darron@kewl.org .