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.7 2007/11/23 23:03:57 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 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 radios. 58.Pp 59These considerations led radiotap to settle on a format consisting of 60a standard preamble followed by an extensible bitmap indicating the 61presence of optional capture fields. 62.Pp 63The capture fields were packed into the header as compactly as possible, 64modulo the requirements that they had to be packed swiftly, 65with their natural alignment, 66in the same order as the bits indicating their presence. 67.Pp 68This typically includes information such as signal quality and 69timestamps. 70This information may be used by a variety of user agents, including 71.Xr tcpdump 1 . 72It is requested by using the 73.Xr bpf 4 74data-link type 75.Dv DLT_IEEE802_11_RADIO . 76.Pp 77.\" 78Each frame using this attachment has the following header prepended to it: 79.Bd -literal -offset indent 80struct 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.\" 89A device driver implementing 90.Vt radiotap 91typically defines a structure embedding an instance of 92.Vt "struct ieee80211_radiotap_header" 93at the beginning, 94with subsequent fields naturally aligned, 95and in the appropriate order. Also, a driver defines 96a 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 capture fields are in little-endian byte order. 102.Pp 103Radiotap capture fields 104.Em must be naturally aligned . 105That is, 16-, 32-, and 64-bit fields must begin on 16-, 32-, and 10664-bit boundaries, respectively. 107In this way, drivers can avoid unaligned accesses to radiotap 108capture fields. 109radiotap-compliant drivers must insert padding before a capture 110field to ensure its natural alignment. 111radiotap-compliant packet dissectors, such as 112.Xr tcpdump 1 , 113expect the padding. 114.Pp 115Developers beware: all compilers may not pack structs alike. 116If a driver developer constructs their radiotap header with a packed 117structure, in order to ensure natural alignment, then it is important 118that they insert padding bytes by themselves. 119.Pp 120Radiotap headers are copied to the userland via a separate bpf attachment. 121It is necessary for the driver to create this attachment after calling 122.Xr ieee80211_ifattach 9 123by calling 124.Fn bpfattach_dlt 125with the data-link type set to 126.Dv DLT_IEEE802_11_RADIO . 127.Pp 128.\" 129When the information is available, 130usually immediately before a link-layer transmission or after a receive, 131the driver copies it to the bpf layer using the 132.Fn bpf_ptap 133function. 134.Pp 135.\" 136The following extension fields are defined for 137.Vt radiotap , 138in the order in which they should appear in the buffer copied to userland: 139.Bl -tag -width indent 140.It Dv IEEE80211_RADIOTAP_TSFT 141This field contains the unsigned 64-bit value, in microseconds, 142of the MAC's 802.11 Time Synchronization Function timer, 143when the first bit of the MPDU arrived at the MAC. 144This field should be present for received frames only. 145.It Dv IEEE80211_RADIOTAP_FLAGS 146This field contains a single unsigned 8-bit value, containing a bitmap 147of flags specifying properties of the frame being transmitted or received. 148.It Dv IEEE80211_RADIOTAP_RATE 149This field contains a single unsigned 8-bit value, which is the data rate in 150use in units of 500Kbps. 151.It Dv IEEE80211_RADIOTAP_CHANNEL 152This field contains two unsigned 16-bit values. 153The first value is the frequency upon which this PDU was transmitted 154or received. 155The second value is a bitmap containing flags which specify properties of 156the channel in use. 157These are documented within the header file, 158.In netproto/802_11/ieee80211_radiotap.h . 159.It Dv IEEE80211_RADIOTAP_FHSS 160This field contains two 8-bit values. 161This field should be present for frequency-hopping radios only. 162The first byte is the hop set. 163The second byte is the pattern in use. 164.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL 165This field contains a single signed 8-bit value, which indicates the 166RF signal power at the antenna, in decibels difference from 1mW. 167.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE 168This field contains a single signed 8-bit value, which indicates the 169RF noise power at the antenna, in decibels difference from 1mW. 170.It Dv IEEE80211_RADIOTAP_LOCK_QUALITY 171This field contains a single unsigned 16-bit value, indicating the 172quality of the Barker Code lock. 173No unit is specified for this field. 174There does not appear to be a standard way of measuring this at this time; 175this quantity is often referred to as 176.Dq "Signal Quality" 177in some datasheets. 178.It Dv IEEE80211_RADIOTAP_TX_ATTENUATION 179This field contains a single unsigned 16-bit value, expressing transmit 180power as unitless distance from maximum power set at factory calibration. 1810 indicates maximum transmit power. 182Monotonically nondecreasing with lower power levels. 183.It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION 184This field contains a single unsigned 16-bit value, expressing transmit 185power as decibel distance from maximum power set at factory calibration. 1860 indicates maximum transmit power. 187Monotonically nondecreasing with lower power levels. 188.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER 189Transmit power expressed as decibels from a 1mW reference. 190This field is a single signed 8-bit value. 191This is the absolute power level measured at the antenna port. 192.It Dv IEEE80211_RADIOTAP_ANTENNA 193For radios which support antenna diversity, this field contains a single 194unsigned 8-bit value specifying which antenna is being used to transmit 195or receive this frame. 196The first antenna is antenna 0. 197.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL 198This field contains a single unsigned 8-bit value, which indicates the 199RF signal power at the antenna, in decibels difference from an 200arbitrary, fixed reference. 201.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE 202This field contains a single unsigned 8-bit value, which indicates the 203RF noise power at the antenna, in decibels difference from an 204arbitrary, fixed reference. 205.It Dv IEEE80211_RADIOTAP_EXT 206This bit is reserved for any future extensions to the 207.Vt radiotap 208structure. 209A driver sets 210.Dv IEEE80211_RADIOTAP_EXT 211to extend the it_present bitmap 212by another 64 bits. 213The bitmap can be extended by multiples of 32 bits to 96, 128, 160 214bits or longer, by setting 215.Dv IEEE80211_RADIOTAP_EXT 216in the extensions. 217The bitmap ends at the first extension field where 218.Dv IEEE80211_RADIOTAP_EXT 219is not set. 220.El 221.Sh EXAMPLES 222Radiotap header for the Intel(R) PRO/Wireless 2200BG/2225BG/2915ABG driver 223.Bd -literal -offset indent 224struct 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 235Bitmap 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 248The 249.Nm 250definitions first appeared in 251.Nx 1.5 , 252and were later ported to 253.Fx 4.6 . 254.\" 255.Sh AUTHORS 256.An -nosplit 257The 258.Nm 259interface was designed and implemented by 260.An David Young Aq dyoung@pobox.com . 261.An David Young 262is the maintainer of the radiotap capture format. 263Contact him to add new capture fields. 264.Pp 265This manual page was written by 266.An Bruce M. Simpson Aq bms@FreeBSD.org 267and 268.An Darron Broad Aq darron@kewl.org . 269