1.\" $OpenBSD: ieee80211_radiotap.9,v 1.11 2010/03/26 19:30:40 jmc Exp $ 2.\" 3.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>, 4.\" Darron Broad <darron@kewl.org>, 5.\" David Young <dyoung@pobox.com>. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 27.\" SUCH DAMAGE. 28.\" 29.\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.3 2004/07/07 12:59:39 ru Exp $ 30.\" $Id: ieee80211_radiotap.9,v 1.11 2010/03/26 19:30:40 jmc Exp $ 31.\" 32.Dd $Mdocdate: March 26 2010 $ 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 net80211/ieee80211_var.h 40.In net80211/ieee80211_ioctl.h 41.In net80211/ieee80211_radiotap.h 42.In net/bpf.h 43.\" 44.Sh DESCRIPTION 45The 46.Nm 47definitions provide a device-independent 48.Xr bpf 4 49attachment for the 50capture of information about 802.11 traffic which is not part of 51the 802.11 frame structure. 52.Pp 53Radiotap was designed to balance the desire for a capture format 54that conserved CPU and memory bandwidth on embedded systems, 55with the desire for a hardware-independent, extensible format 56that would support the diverse capabilities of virtually all 57802.11 58radios. 59.Pp 60These considerations led radiotap to settle on a format consisting of 61a standard preamble followed by an extensible bitmap indicating the 62presence of optional capture fields. 63.Pp 64The capture fields were packed into the header as compactly as possible, 65modulo the requirements that they had to be packed swiftly, 66with suitable alignment, in the same order as the bits indicating 67their presence. 68.Pp 69This typically includes information such as signal quality and 70timestamps. 71This information may be used by a variety of user agents, including 72.Xr tcpdump 8 . 73It is requested by using the 74.Xr bpf 4 75data-link type 76.Dv DLT_IEEE802_11_RADIO . 77.Pp 78.\" 79Each frame using this attachment has the following header prepended to it: 80.Bd -literal -offset indent 81struct ieee80211_radiotap_header { 82 u_int8_t it_version; /* set to 0 */ 83 u_int8_t it_pad; 84 u_int16_t it_len; /* entire length */ 85 u_int32_t it_present; /* fields present */ 86} __packed; 87.Ed 88.Pp 89.\" 90A device driver implementing 91.Vt radiotap 92typically defines a packed structure embedding an instance of 93.Vt "struct ieee80211_radiotap_header" 94at the beginning, 95with subsequent fields in the appropriate order, 96and a macro to set the bits of the 97.Va it_present 98bitmap to indicate which fields exist and are filled in by the driver. 99.\" 100.Pp 101Radiotap headers are copied to userland via a separate bpf attachment. 102It is necessary for the driver to create this attachment after calling 103.Xr ieee80211_ifattach 9 104by calling 105.Fn bpfattach2 106with the data-link type set to 107.Dv DLT_IEEE802_11_RADIO . 108.Pp 109.\" 110When the information is available, 111usually immediately before a link-layer transmission or after a receive, 112the driver copies it to the bpf layer using the 113.Fn bpf_mtap2 114function. 115.Pp 116.\" 117The following extension fields are defined for 118.Vt radiotap , 119in the order in which they should appear in the buffer copied to userland: 120.Bl -tag -width indent 121.It Dv IEEE80211_RADIOTAP_TSFT 122This field contains the unsigned 64-bit value, in microseconds, 123of the MAC's 802.11 Time Synchronization Function timer, 124when the first bit of the MPDU arrived at the MAC. 125This field should be present for received frames only. 126.It Dv IEEE80211_RADIOTAP_FLAGS 127This field contains a single unsigned 8-bit value, containing a bitmap 128of flags specifying properties of the frame being transmitted or received. 129.It Dv IEEE80211_RADIOTAP_RATE 130This field contains a single unsigned 8-bit value, which is the data rate in 131use in units of 500Kbps. 132.It Dv IEEE80211_RADIOTAP_CHANNEL 133This field contains two unsigned 16-bit values. 134The first value is the frequency upon which this PDU was transmitted 135or received. 136The second value is a bitmap containing flags which specify properties of 137the channel in use. 138These are documented within the header file 139.Aq Pa net80211/ieee80211_radiotap.h . 140.It Dv IEEE80211_RADIOTAP_FHSS 141This field contains two 8-bit values. 142This field should be present for frequency-hopping radios only. 143The first byte is the hop set. 144The second byte is the pattern in use. 145.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL 146This field contains a single signed 8-bit value, which indicates the 147RF signal power at the antenna, in decibels difference from 1mW. 148.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE 149This field contains a single signed 8-bit value, which indicates the 150RF noise power at the antenna, in decibels difference from 1mW. 151.It Dv IEEE80211_RADIOTAP_LOCK_QUALITY 152This field contains a single unsigned 16-bit value, indicating the 153quality of the Barker Code lock. 154No unit is specified for this field. 155There does not appear to be a standard way of measuring this at this time; 156this quantity is often referred to as 157.Dq "Signal Quality" 158in some datasheets. 159.It Dv IEEE80211_RADIOTAP_TX_ATTENUATION 160This field contains a single unsigned 16-bit value, expressing transmit 161power as unitless distance from maximum power set at factory calibration. 1620 indicates maximum transmit power. 163Monotonically nondecreasing with lower power levels. 164.It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION 165This field contains a single unsigned 16-bit value, expressing transmit 166power as decibel distance from maximum power set at factory calibration. 1670 indicates maximum transmit power. 168Monotonically nondecreasing with lower power levels. 169.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER 170Transmit power expressed as decibels from a 1mW reference. 171This field is a single signed 8-bit value. 172This is the absolute power level measured at the antenna port. 173.It Dv IEEE80211_RADIOTAP_ANTENNA 174For radios which support antenna diversity, this field contains a single 175unsigned 8-bit value specifying which antenna is being used to transmit 176or receive this frame. 177The first antenna is antenna 0. 178.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL 179This field contains a single unsigned 8-bit value, which indicates the 180RF signal power at the antenna, in decibels difference from an 181arbitrary, fixed reference. 182.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE 183This field contains a single unsigned 8-bit value, which indicates the 184RF noise power at the antenna, in decibels difference from an 185arbitrary, fixed reference. 186.It Dv IEEE80211_RADIOTAP_HWQUEUE 187This field contains a single unsigned 8-bit value specifying which 188hardware queue is being used to transmit the frame. 189.It Dv IEEE80211_RADIOTAP_RSSI 190This field contains two unsigned 8-bit values. 191The first value is the received signal strength index (RSSI) 192which indicates the RF signal power at the antenna. 193The second value is the relative maximum RSSI value of the RF 194interface. 195.It Dv IEEE80211_RADIOTAP_EXT 196This bit is reserved for any future extensions to the 197.Vt radiotap 198structure. 199A driver can set 200.Dv IEEE80211_RADIOTAP_EXT 201to extend the it_present bitmap by another 64 bits. 202The bitmap can be extended by multiples of 32 bits to 96, 128, 160 bits, 203or longer, by setting 204.Dv IEEE80211_RADIOTAP_EXT 205in the extensions. 206The bitmap ends at the first extension field where 207.Dv IEEE80211_RADIOTAP_EXT 208is not set. 209.El 210.Sh EXAMPLES 211Radiotap header for the Realtek RTL8180L driver 212.Xr rtw 4 : 213.Bd -literal -offset indent 214struct rtw_rx_radiotap_header { 215 struct ieee80211_radiotap_header rr_ihdr; 216 u_int64_t rr_tsft; 217 u_int8_t rr_flags; 218 u_int8_t rr_rate; 219 u_int16_t rr_chan_freq; 220 u_int16_t rr_chan_flags; 221 u_int16_t rr_barker_lock; 222 u_int8_t rr_antsignal; 223} __packed; 224.Ed 225.Pp 226Bitmap indicating which fields are present in the above structure: 227.Bd -literal -offset indent 228#define RTW_RX_RADIOTAP_PRESENT \e 229 ((1 << IEEE80211_RADIOTAP_TSFT) | \e 230 (1 << IEEE80211_RADIOTAP_FLAGS) | \e 231 (1 << IEEE80211_RADIOTAP_RATE) | \e 232 (1 << IEEE80211_RADIOTAP_CHANNEL) | \e 233 (1 << IEEE80211_RADIOTAP_LOCK_QUALITY) | \e 234 (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \e 235 0) 236.Ed 237.Sh SEE ALSO 238.Xr bpf 4 , 239.Xr ieee80211 9 240.Sh HISTORY 241The 242.Nm 243definitions first appeared in 244.Nx 1.5 , 245and were later ported to 246.Fx 4.6 247and 248.Ox 3.6 . 249.\" 250.Sh AUTHORS 251.An -nosplit 252The 253.Nm 254interface was designed and implemented by 255.An David Young Aq dyoung@pobox.com . 256.Pp 257This manual page was written by 258.An Bruce M. Simpson Aq bms@FreeBSD.org 259and 260.An Darron Broad Aq darron@kewl.org . 261