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 2, 2004 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 57radios. 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 suitable alignment, in the same order as the bits indicating 66their 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_IEEE_80211_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 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.\" 89A device driver implementing 90.Vt radiotap 91typically defines a packed structure embedding an instance of 92.Vt "struct ieee80211_radiotap_header" 93at the beginning, 94with subsequent fields in the appropriate order, 95and 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 headers are copied to the userland via a separate bpf attachment. 101It is necessary for the driver to create this attachment after calling 102.Xr ieee80211_ifattach 9 103by calling 104.Fn bpfattach2 105with the data-link type set to 106.Dv DLT_IEEE_80211_RADIO . 107.Pp 108.\" 109When the the information is available, 110usually immediately before a link-layer transmission or after a receive, 111the driver copies it to the bpf layer using the 112.Fn bpf_mtap2 113function. 114.Pp 115.\" 116The following extension fields are defined for 117.Vt radiotap , 118in the order in which they should appear in the buffer copied to userland: 119.Bl -tag -width indent 120.It Dv IEEE80211_RADIOTAP_TSFT 121This field contains the unsigned 64-bit value, in microseconds, 122of the MAC's 802.11 Time Synchronization Function timer, 123when the first bit of the MPDU arrived at the MAC. 124This field should be present for received frames only. 125.It Dv IEEE80211_RADIOTAP_FLAGS 126This field contains a single unsigned 8-bit value, containing a bitmap 127of flags specifying properties of the frame being transmitted or received. 128.It Dv IEEE80211_RADIOTAP_RATE 129This field contains a single unsigned 8-bit value, which is the data rate in 130use in units of 500Kbps. 131.It Dv IEEE80211_RADIOTAP_CHANNEL 132This field contains two unsigned 16-bit values. 133The first value is the frequency upon which this PDU was transmitted 134or received. 135The second value is a bitmap containing flags which specify properties of 136the channel in use. 137These are documented within the header file, 138.In net80211/ieee80211_radiotap.h . 139.It Dv IEEE80211_RADIOTAP_FHSS 140This field contains two 8-bit values. 141This field should be present for frequency-hopping radios only. 142The first byte is the hop set. 143The second byte is the pattern in use. 144.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL 145This field contains a single signed 8-bit value, which indicates the 146RF signal power at the antenna, in decibels difference from 1mW. 147.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE 148This field contains a single signed 8-bit value, which indicates the 149RF noise power at the antenna, in decibels difference from 1mW. 150.It Dv IEEE80211_RADIOTAP_LOCK_QUALITY 151This field contains a single unsigned 16-bit value, indicating the 152quality of the Barker Code lock. 153No unit is specified for this field. 154There does not appear to be a standard way of measuring this at this time; 155this quantity is often referred to as 156.Dq "Signal Quality" 157in some datasheets. 158.It Dv IEEE80211_RADIOTAP_TX_ATTENUATION 159This field contains a single unsigned 16-bit value, expressing transmit 160power as unitless distance from maximum power set at factory calibration. 1610 indicates maximum transmit power. 162Monotonically nondecreasing with lower power levels. 163.It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION 164This field contains a single unsigned 16-bit value, expressing transmit 165power as decibel distance from maximum power set at factory calibration. 1660 indicates maximum transmit power. 167Monotonically nondecreasing with lower power levels. 168.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER 169Transmit power expressed as decibels from a 1mW reference. 170This field is a single signed 8-bit value. 171This is the absolute power level measured at the antenna port. 172.It Dv IEEE80211_RADIOTAP_ANTENNA 173For radios which support antenna diversity, this field contains a single 174unsigned 8-bit value specifying which antenna is being used to transmit 175or receive this frame. 176The first antenna is antenna 0. 177.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL 178This field contains a single unsigned 8-bit value, which indicates the 179RF signal power at the antenna, in decibels difference from an 180arbitrary, fixed reference. 181.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE 182This field contains a single unsigned 8-bit value, which indicates the 183RF noise power at the antenna, in decibels difference from an 184arbitrary, fixed reference. 185.It Dv IEEE80211_RADIOTAP_EXT 186This bit is reserved for any future extensions to the 187.Vt radiotap 188structure. 189It should not be used at this time. 190.El 191.Sh EXAMPLES 192Radiotap header for the Cisco Aironet driver: 193.Bd -literal -offset indent 194struct 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 205Bitmap 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 218The 219.Nm 220definitions first appeared in 221.Nx 1.5 , 222and were later ported to 223.Fx 4.6 . 224.\" 225.Sh AUTHORS 226.An -nosplit 227The 228.Nm 229interface was designed and implemented by 230.An David Young Aq dyoung@pobox.com . 231.Pp 232This manual page was written by 233.An Bruce M. Simpson Aq bms@FreeBSD.org 234and 235.An Darron Broad Aq darron@kewl.org . 236