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