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.3 2004/07/07 12:59:39 ru Exp $
  29 .\" $NetBSD: ieee80211_radiotap.9,v 1.9 2006/03/12 03:22:02 dyoung Exp $
  30 .\" $DragonFly: src/share/man/man9/ieee80211_radiotap.9,v 1.6 2007/02/25 01:09:09 swildner Exp $
  31 .\"
  32 .Dd December 25, 2006
  33 .Dt IEEE80211_RADIOTAP 9
  34 .Os
  35 .Sh NAME
  36 .Nm ieee80211_radiotap
  37 .Nd software 802.11 stack packet capture definitions
  38 .Sh SYNOPSIS
  39 .In net/bpf.h
  40 .In netproto/802_11/ieee80211_var.h
  41 .In netproto/802_11/ieee80211_ioctl.h
  42 .In netproto/802_11/ieee80211_radiotap.h
  43 .\"
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 definitions provide a device-independent
  48 .Xr bpf 4
  49 attachment for the
  50 capture of information about 802.11 traffic which is not part of
  51 the 802.11 frame structure.
  52 .Pp
  53 Radiotap was designed to balance the desire for a capture format
  54 that conserved CPU and memory bandwidth on embedded systems,
  55 with the desire for a hardware-independent, extensible format
  56 that would support the diverse capabilities of virtually all
  57 802.11 radios.
  58 .Pp
  59 These considerations led radiotap to settle on a format consisting of
  60 a standard preamble followed by an extensible bitmap indicating the
  61 presence of optional capture fields.
  62 .Pp
  63 The capture fields were packed into the header as compactly as possible,
  64 modulo the requirements that they had to be packed swiftly,
  65 with their natural alignment,
  66 in the same order as the bits indicating their presence.
  67 .Pp
  68 This typically includes information such as signal quality and
  69 timestamps.
  70 This information may be used by a variety of user agents, including
  71 .Xr tcpdump 1 .
  72 It is requested by using the
  73 .Xr bpf 4
  74 data-link type
  75 .Dv DLT_IEEE802_11_RADIO .
  76 .Pp
  77 .\"
  78 Each frame using this attachment has the following header prepended to it:
  79 .Bd -literal -offset indent
  80 struct ieee80211_radiotap_header {
  81         uint8_t         it_version;     /* set to 0 */
  82         uint8_t         it_pad;
  83         uint16_t        it_len;         /* entire length */
  84         uint32_t        it_present;     /* fields present */
  85 } __packed;
  86 .Ed
  87 .Pp
  88 .\"
  89 A device driver implementing
  90 .Vt radiotap
  91 typically defines a structure embedding an instance of
  92 .Vt "struct ieee80211_radiotap_header"
  93 at the beginning,
  94 with subsequent fields naturally aligned,
  95 and in the appropriate order.  Also, a driver defines
  96 a macro to set the bits of the
  97 .Va it_present
  98 bitmap to indicate which fields exist and are filled in by the driver.
  99 .\"
 100 .Pp
 101 Radiotap capture fields are in little-endian byte order.
 102 .Pp
 103 Radiotap capture fields
 104 .Em must be naturally aligned .
 105 That is, 16-, 32-, and 64-bit fields must begin on 16-, 32-, and
 106 64-bit boundaries, respectively.
 107 In this way, drivers can avoid unaligned accesses to radiotap
 108 capture fields.
 109 radiotap-compliant drivers must insert padding before a capture
 110 field to ensure its natural alignment.
 111 radiotap-compliant packet dissectors, such as
 112 .Xr tcpdump 1 ,
 113 expect the padding.
 114 .Pp
 115 Developers beware: all compilers may not pack structs alike.
 116 If a driver developer constructs their radiotap header with a packed
 117 structure, in order to ensure natural alignment, then it is important
 118 that they insert padding bytes by themselves.
 119 .Pp
 120 Radiotap headers are copied to the userland via a separate bpf attachment.
 121 It is necessary for the driver to create this attachment after calling
 122 .Xr ieee80211_ifattach 9
 123 by calling
 124 .Fn bpfattach_dlt
 125 with the data-link type set to
 126 .Dv DLT_IEEE_80211_RADIO .
 127 .Pp
 128 .\"
 129 When the information is available,
 130 usually immediately before a link-layer transmission or after a receive,
 131 the driver copies it to the bpf layer using the
 132 .Fn bpf_ptap
 133 function.
 134 .Pp
 135 .\"
 136 The following extension fields are defined for
 137 .Vt radiotap ,
 138 in the order in which they should appear in the buffer copied to userland:
 139 .Bl -tag -width indent
 140 .It Dv IEEE80211_RADIOTAP_TSFT
 141 This field contains the unsigned 64-bit value, in microseconds,
 142 of the MAC's 802.11 Time Synchronization Function timer,
 143 when the first bit of the MPDU arrived at the MAC.
 144 This field should be present for received frames only.
 145 .It Dv IEEE80211_RADIOTAP_FLAGS
 146 This field contains a single unsigned 8-bit value, containing a bitmap
 147 of flags specifying properties of the frame being transmitted or received.
 148 .It Dv IEEE80211_RADIOTAP_RATE
 149 This field contains a single unsigned 8-bit value, which is the data rate in
 150 use in units of 500Kbps.
 151 .It Dv IEEE80211_RADIOTAP_CHANNEL
 152 This field contains two unsigned 16-bit values.
 153 The first value is the frequency upon which this PDU was transmitted
 154 or received.
 155 The second value is a bitmap containing flags which specify properties of
 156 the channel in use.
 157 These are documented within the header file,
 158 .In netproto/802_11/ieee80211_radiotap.h .
 159 .It Dv IEEE80211_RADIOTAP_FHSS
 160 This field contains two 8-bit values.
 161 This field should be present for frequency-hopping radios only.
 162 The first byte is the hop set.
 163 The second byte is the pattern in use.
 164 .It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL
 165 This field contains a single signed 8-bit value, which indicates the
 166 RF signal power at the antenna, in decibels difference from 1mW.
 167 .It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE
 168 This field contains a single signed 8-bit value, which indicates the
 169 RF noise power at the antenna, in decibels difference from 1mW.
 170 .It Dv IEEE80211_RADIOTAP_LOCK_QUALITY
 171 This field contains a single unsigned 16-bit value, indicating the
 172 quality of the Barker Code lock.
 173 No unit is specified for this field.
 174 There does not appear to be a standard way of measuring this at this time;
 175 this quantity is often referred to as
 176 .Dq "Signal Quality"
 177 in some datasheets.
 178 .It Dv IEEE80211_RADIOTAP_TX_ATTENUATION
 179 This field contains a single unsigned 16-bit value, expressing transmit
 180 power as unitless distance from maximum power set at factory calibration.
 181 0 indicates maximum transmit power.
 182 Monotonically nondecreasing with lower power levels.
 183 .It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION
 184 This field contains a single unsigned 16-bit value, expressing transmit
 185 power as decibel distance from maximum power set at factory calibration.
 186 0 indicates maximum transmit power.
 187 Monotonically nondecreasing with lower power levels.
 188 .It Dv IEEE80211_RADIOTAP_DBM_TX_POWER
 189 Transmit power expressed as decibels from a 1mW reference.
 190 This field is a single signed 8-bit value.
 191 This is the absolute power level measured at the antenna port.
 192 .It Dv IEEE80211_RADIOTAP_ANTENNA
 193 For radios which support antenna diversity, this field contains a single
 194 unsigned 8-bit value specifying which antenna is being used to transmit
 195 or receive this frame.
 196 The first antenna is antenna 0.
 197 .It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL
 198 This field contains a single unsigned 8-bit value, which indicates the
 199 RF signal power at the antenna, in decibels difference from an
 200 arbitrary, fixed reference.
 201 .It Dv IEEE80211_RADIOTAP_DB_ANTNOISE
 202 This field contains a single unsigned 8-bit value, which indicates the
 203 RF noise power at the antenna, in decibels difference from an
 204 arbitrary, fixed reference.
 205 .It Dv IEEE80211_RADIOTAP_EXT
 206 This bit is reserved for any future extensions to the
 207 .Vt radiotap
 208 structure.
 209 A driver sets
 210 .Dv IEEE80211_RADIOTAP_EXT
 211 to extend the it_present bitmap
 212 by another 64 bits.
 213 The bitmap can be extended by multiples of 32 bits to 96, 128, 160
 214 bits or longer, by setting
 215 .Dv IEEE80211_RADIOTAP_EXT
 216 in the extensions.
 217 The bitmap ends at the first extension field where
 218 .Dv IEEE80211_RADIOTAP_EXT
 219 is not set.
 220 .El
 221 .Sh EXAMPLES
 222 Radiotap header for the Intel(R) PRO/Wireless 2200BG/2225BG/2915ABG driver
 223 .Bd -literal -offset indent
 224 struct iwi_rx_radiotap_header {
 225         struct ieee80211_radiotap_header wr_ihdr;
 226         uint8_t         wr_flags;
 227         uint8_t         wr_rate;
 228         uint16_t        wr_chan_freq;
 229         uint16_t        wr_chan_flags;
 230         uint8_t         wr_antsignal;
 231         uint8_t         wr_antenna;
 232 };
 233 .Ed
 234 .Pp
 235 Bitmap indicating which fields are present in the above structure:
 236 .Bd -literal -offset indent
 237 #define IWI_RX_RADIOTAP_PRESENT \\
 238         ((1 << IEEE80211_RADIOTAP_FLAGS) | \\
 239          (1 << IEEE80211_RADIOTAP_RATE) | \\
 240          (1 << IEEE80211_RADIOTAP_CHANNEL) | \\
 241          (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\
 242          (1 << IEEE80211_RADIOTAP_ANTENNA))
 243 .Ed
 244 .Sh SEE ALSO
 245 .Xr bpf 4 ,
 246 .Xr ieee80211 9
 247 .Sh HISTORY
 248 The
 249 .Nm
 250 definitions first appeared in
 251 .Nx 1.5 ,
 252 and were later ported to
 253 .Fx 4.6 .
 254 .\"
 255 .Sh AUTHORS
 256 .An -nosplit
 257 The
 258 .Nm
 259 interface was designed and implemented by
 260 .An David Young Aq dyoung@pobox.com .
 261 .An David Young
 262 is the maintainer of the radiotap capture format.
 263 Contact him to add new capture fields.
 264 .Pp
 265 This manual page was written by
 266 .An Bruce M. Simpson Aq bms@FreeBSD.org
 267 and
 268 .An Darron Broad Aq darron@kewl.org .