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$
  29 .\" $Id: ieee80211_radiotap.9,v 1.3 2004/03/04 11:38:52 bruce Exp $
  30 .\"
  31 .Dd March 17, 2008
  32 .Dt IEEE80211_RADIOTAP 9
  33 .Os
  34 .Sh NAME
  35 .Nm ieee80211_radiotap
  36 .Nd software 802.11 stack packet capture definitions
  37 .Sh SYNOPSIS
  38 .In net80211/ieee80211_var.h
  39 .In net80211/ieee80211_ioctl.h
  40 .In net80211/ieee80211_radiotap.h
  41 .In net/bpf.h
  42 .\"
  43 .Sh DESCRIPTION
  44 The
  45 .Nm
  46 definitions provide a device-independent
  47 .Xr bpf 4
  48 attachment for the
  49 capture of information about 802.11 traffic which is not part of
  50 the 802.11 frame structure.
  51 .Pp
  52 Radiotap was designed to balance the desire for a capture format
  53 that conserved CPU and memory bandwidth on embedded systems,
  54 with the desire for a hardware-independent, extensible format
  55 that would support the diverse capabilities of virtually all
  56 802.11
  57 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 suitable alignment, in the same order as the bits indicating
  66 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         u_int8_t        it_version;     /* set to 0 */
  82         u_int8_t        it_pad;
  83         u_int16_t       it_len;         /* entire length */
  84         u_int32_t       it_present;     /* fields present */
  85 } __attribute__((__packed__));
  86 .Ed
  87 .Pp
  88 .\"
  89 A device driver implementing
  90 .Vt radiotap
  91 typically defines a packed structure embedding an instance of
  92 .Vt "struct ieee80211_radiotap_header"
  93 at the beginning,
  94 with subsequent fields in the appropriate order,
  95 and a macro to set the bits of the
  96 .Va it_present
  97 bitmap to indicate which fields exist and are filled in by the driver.
  98 .\"
  99 .Pp
 100 Radiotap headers are copied to the userland via a separate bpf attachment.
 101 It is necessary for the driver to create this attachment after calling
 102 .Xr ieee80211_ifattach 9
 103 by calling
 104 .Fn bpfattach2
 105 with the data-link type set to
 106 .Dv DLT_IEEE802_11_RADIO .
 107 .Pp
 108 .\"
 109 When the the information is available,
 110 usually immediately before a link-layer transmission or after a receive,
 111 the driver copies it to the bpf layer using the
 112 .Fn bpf_mtap2
 113 function.
 114 .Pp
 115 .\"
 116 The following extension fields are defined for
 117 .Vt radiotap ,
 118 in the order in which they should appear in the buffer copied to userland:
 119 .Bl -tag -width indent
 120 .It Dv IEEE80211_RADIOTAP_TSFT
 121 This field contains the unsigned 64-bit value, in microseconds,
 122 of the MAC's 802.11 Time Synchronization Function timer,
 123 when the first bit of the MPDU arrived at the MAC.
 124 This field should be present for received frames only.
 125 .It Dv IEEE80211_RADIOTAP_FLAGS
 126 This field contains a single unsigned 8-bit value, containing a bitmap
 127 of flags specifying properties of the frame being transmitted or received.
 128 .It Dv IEEE80211_RADIOTAP_RATE
 129 This field contains a single unsigned 8-bit value, which is the data rate in
 130 use in units of 500Kbps.
 131 .It Dv IEEE80211_RADIOTAP_CHANNEL
 132 This field contains two unsigned 16-bit values.
 133 The first value is the frequency upon which this PDU was transmitted
 134 or received.
 135 The second value is a bitmap containing flags which specify properties of
 136 the channel in use.
 137 These are documented within the header file,
 138 .In net80211/ieee80211_radiotap.h .
 139 .It Dv IEEE80211_RADIOTAP_FHSS
 140 This field contains two 8-bit values.
 141 This field should be present for frequency-hopping radios only.
 142 The first byte is the hop set.
 143 The second byte is the pattern in use.
 144 .It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL
 145 This field contains a single signed 8-bit value, which indicates the
 146 RF signal power at the antenna, in decibels difference from 1mW.
 147 .It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE
 148 This field contains a single signed 8-bit value, which indicates the
 149 RF noise power at the antenna, in decibels difference from 1mW.
 150 .It Dv IEEE80211_RADIOTAP_LOCK_QUALITY
 151 This field contains a single unsigned 16-bit value, indicating the
 152 quality of the Barker Code lock.
 153 No unit is specified for this field.
 154 There does not appear to be a standard way of measuring this at this time;
 155 this quantity is often referred to as
 156 .Dq "Signal Quality"
 157 in some datasheets.
 158 .It Dv IEEE80211_RADIOTAP_TX_ATTENUATION
 159 This field contains a single unsigned 16-bit value, expressing transmit
 160 power as unitless distance from maximum power set at factory calibration.
 161 0 indicates maximum transmit power.
 162 Monotonically nondecreasing with lower power levels.
 163 .It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION
 164 This field contains a single unsigned 16-bit value, expressing transmit
 165 power as decibel distance from maximum power set at factory calibration.
 166 0 indicates maximum transmit power.
 167 Monotonically nondecreasing with lower power levels.
 168 .It Dv IEEE80211_RADIOTAP_DBM_TX_POWER
 169 Transmit power expressed as decibels from a 1mW reference.
 170 This field is a single signed 8-bit value.
 171 This is the absolute power level measured at the antenna port.
 172 .It Dv IEEE80211_RADIOTAP_ANTENNA
 173 For radios which support antenna diversity, this field contains a single
 174 unsigned 8-bit value specifying which antenna is being used to transmit
 175 or receive this frame.
 176 The first antenna is antenna 0.
 177 .It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL
 178 This field contains a single unsigned 8-bit value, which indicates the
 179 RF signal power at the antenna, in decibels difference from an
 180 arbitrary, fixed reference.
 181 .It Dv IEEE80211_RADIOTAP_DB_ANTNOISE
 182 This field contains a single unsigned 8-bit value, which indicates the
 183 RF noise power at the antenna, in decibels difference from an
 184 arbitrary, fixed reference.
 185 .It Dv IEEE80211_RADIOTAP_EXT
 186 This bit is reserved for any future extensions to the
 187 .Vt radiotap
 188 structure.
 189 It should not be used at this time.
 190 .El
 191 .Sh EXAMPLES
 192 Radiotap header for the Cisco Aironet driver:
 193 .Bd -literal -offset indent
 194 struct an_rx_radiotap_header {
 195         struct ieee80211_radiotap_header        ar_ihdr;
 196         u_int8_t        ar_flags;
 197         u_int8_t        ar_rate;
 198         u_int16_t       ar_chan_freq;
 199         u_int16_t       ar_chan_flags;
 200         u_int8_t        ar_antsignal;
 201         u_int8_t        ar_antnoise;
 202 } __attribute__((__packed__));
 203 .Ed
 204 .Pp
 205 Bitmap indicating which fields are present in the above structure:
 206 .Bd -literal -offset indent
 207 #define AN_RX_RADIOTAP_PRESENT \\
 208         ((1 << IEEE80211_RADIOTAP_FLAGS) | \\
 209          (1 << IEEE80211_RADIOTAP_RATE) | \\
 210          (1 << IEEE80211_RADIOTAP_CHANNEL) | \\
 211          (1 << IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \\
 212          (1 << IEEE80211_RADIOTAP_DBM_ANTNOISE))
 213 .Ed
 214 .Sh SEE ALSO
 215 .Xr bpf 4 ,
 216 .Xr ieee80211 9
 217 .Sh HISTORY
 218 The
 219 .Nm
 220 definitions first appeared in
 221 .Nx 1.5 ,
 222 and were later ported to
 223 .Fx 4.6 .
 224 .\"
 225 .Sh AUTHORS
 226 .An -nosplit
 227 The
 228 .Nm
 229 interface was designed and implemented by
 230 .An David Young Aq dyoung@pobox.com .
 231 .Pp
 232 This manual page was written by
 233 .An Bruce M. Simpson Aq bms@FreeBSD.org
 234 and
 235 .An Darron Broad Aq darron@kewl.org .