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.Dd March 11, 2019 29.Dt IEEE80211_RADIOTAP 9 30.Os 31.Sh NAME 32.Nm ieee80211_radiotap 33.Nd 802.11 device packet capture support 34.Sh SYNOPSIS 35.In net80211/ieee80211_var.h 36.\" 37.Pp 38.Ft void 39.Fo ieee80211_radiotap_attach 40.Fa "struct ieee80211com *" 41.Fa "struct ieee80211_radiotap_header *th" 42.Fa "int tlen" 43.Fa "uint32_t tx_radiotap" 44.Fa "struct ieee80211_radiotap_header *rh" 45.Fa "int rlen" 46.Fa "uint32_t rx_radiotap" 47.Fc 48.\" 49.Ft int 50.Fn ieee80211_radiotap_active_vap "struct ieee80211vap *" 51.\" 52.Ft int 53.Fn ieee80211_radiotap_active "struct ieee80211com *" 54.\" 55.Ft void 56.Fn ieee80211_radiotap_tx "struct ieee80211vap *" "struct mbuf *" 57.Sh DESCRIPTION 58The 59.Nm net80211 60layer used by 802.11 drivers includes support for a device-independent 61packet capture format called 62.Nm radiotap 63that is understood by tools such as 64.Xr tcpdump 1 . 65This facility is designed for capturing 802.11 traffic, 66including information that is not part of the normal 802.11 frame structure. 67.Pp 68Radiotap was designed to balance the desire for a hardware-independent, 69extensible capture format against the need to 70conserve CPU and memory bandwidth on embedded systems. 71These considerations led to a format consisting of 72a standard preamble followed by an extensible bitmap indicating the 73presence of optional capture fields. 74A 75.Nm net80211 76device driver supporting 77.Vt radiotap 78defines two packed structures that it shares with 79.Nm net80211 . 80These structures embed an instance of a 81.Vt ieee80211_radiotap_header 82structure at the beginning, 83with subsequent fields in the appropriate order, 84and macros to set the bits of the 85.Va it_present 86bitmap to indicate which fields exist and are filled in by the driver. 87This information is then supplied through the 88.Fn ieee80211_radiotap_attach 89call after a successful 90.Fn ieee80211_ifattach 91request. 92.Pp 93With radiotap setup, drivers just need to fill in per-packet 94capture state for frames sent/received and dispatch capture state 95in the transmit path (since control is not returned to the 96.Nm net80211 97layer before the packet is handed to the device). 98To minimize overhead this work should be done only when one 99or more processes are actively capturing data; 100this is checked with one of 101.Fn ieee80211_radiotap_active_vap 102and 103.Fn ieee80211_radiotap_active . 104In the transmit path capture work looks like this: 105.Bd -literal -offset indent 106if (ieee80211_radiotap_active_vap(vap)) { 107 ... /* record transmit state */ 108 ieee80211_radiotap_tx(vap, m); /* capture transmit event */ 109} 110.Ed 111.Pp 112While in the receive path capture is handled in 113.Nm net80211 114but state must be captured before dispatching a frame: 115.Bd -literal -offset indent 116if (ieee80211_radiotap_active(ic)) { 117 ... /* record receive state */ 118} 119\&... 120ieee80211_input(...); /* packet capture handled in net80211 */ 121.Ed 122.Pp 123.\" 124The following fields are defined for 125.Vt radiotap , 126in the order in which they should appear in the buffer supplied 127to 128.Nm net80211 . 129.Bl -tag -width indent 130.It Dv IEEE80211_RADIOTAP_TSFT 131This field contains the unsigned 64-bit value, in microseconds, 132of the MAC's 802.11 Time Synchronization Function (TSF). 133In theory, for each received frame, this value is recorded 134when the first bit of the MPDU arrived at the MAC. 135In practice, hardware snapshots the TSF otherwise and one cannot assume 136this data is accurate without driver adjustment. 137.It Dv IEEE80211_RADIOTAP_FLAGS 138This field contains a single unsigned 8-bit value, containing one or 139more of these bit flags: 140.Bl -tag -width indent 141.It Dv IEEE80211_RADIOTAP_F_CFP 142Frame was sent/received during the Contention Free Period (CFP). 143.It Dv IEEE80211_RADIOTAP_F_SHORTPRE 144Frame was sent/received with short preamble. 145.It Dv IEEE80211_RADIOTAP_F_WEP 146Frame was encrypted. 147.It Dv IEEE80211_RADIOTAP_F_FRAG 148Frame was an 802.11 fragment. 149.It Dv IEEE80211_RADIOTAP_F_FCS 150Frame contents includes the FCS. 151.It Dv IEEE80211_RADIOTAP_F_DATAPAD 152Frame contents potentially has padding between the 802.11 header and the 153data payload to align the payload to a 32-bit boundary. 154.It Dv IEEE80211_RADIOTAP_F_BADFCS 155Frame was received with an invalid FCS. 156.It Dv IEEE80211_RADIOTAP_F_SHORTGI 157Frame was sent/received with Short Guard Interval. 158.El 159.It Dv IEEE80211_RADIOTAP_RATE 160This field contains a single unsigned 8-bit value that is the data rate. 161Legacy rates are in units of 500Kbps. 162MCS rates (used on 802.11n/HT channels) have the high bit set and 163the MCS in the low 7 bits. 164.It Dv IEEE80211_RADIOTAP_CHANNEL 165This field contains two unsigned 16-bit values. 166The first value is the center frequency for the channel 167the frame was sent/received on. 168The second value is a bitmap containing flags that specify channel properties. 169.Pp 170This field is deprecated in favor of 171.Dv IEEE80211_RADIOTAP_XCHANNEL 172but may be used to save space in the capture file for legacy devices. 173.\".It Dv IEEE80211_RADIOTAP_FHSS 174.\"This field contains two 8-bit values. 175.\"This field should be present only for frequency-hopping radios. 176.\"The first byte is the hop set. 177.\"The second byte is the pattern in use. 178.It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL 179This field contains a single signed 8-bit value that indicates the 180RF signal power at the antenna, in decibels difference from 1mW. 181.It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE 182This field contains a single signed 8-bit value that indicates the 183RF noise power at the antenna, in decibels difference from 1mW. 184.\".It Dv IEEE80211_RADIOTAP_LOCK_QUALITY 185.\"This field contains a single unsigned 16-bit value, indicating the 186.\"quality of the Barker Code lock. 187.\"No unit is specified for this field. 188.\"There does not appear to be a standard way of measuring this at this time; 189.\"this quantity is often referred to as 190.\".Dq "Signal Quality" 191.\"in some datasheets. 192.\".It Dv IEEE80211_RADIOTAP_TX_ATTENUATION 193.\"This field contains a single unsigned 16-bit value, expressing transmit 194.\"power as unitless distance from maximum power set at factory calibration. 195.\"0 indicates maximum transmit power. 196.\"Monotonically nondecreasing with lower power levels. 197.\".It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION 198.\"This field contains a single unsigned 16-bit value, expressing transmit 199.\"power as decibel distance from maximum power set at factory calibration. 200.\"0 indicates maximum transmit power. 201.\"Monotonically nondecreasing with lower power levels. 202.It Dv IEEE80211_RADIOTAP_DBM_TX_POWER 203Transmit power expressed as decibels from a 1mW reference. 204This field is a single signed 8-bit value. 205This is the absolute power level measured at the antenna port. 206.It Dv IEEE80211_RADIOTAP_ANTENNA 207This field contains a single unsigned 8-bit value that specifies 208which antenna was used to transmit or receive the frame. 209Antenna numbering is device-specific but typically the primary antenna has 210the lowest number. 211On transmit a value of zero may be seen which typically means 212antenna selection is left to the device. 213.It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL 214This field contains a single unsigned 8-bit value that indicates the 215RF signal power at the antenna, in decibels difference from an 216arbitrary, fixed reference. 217.It Dv IEEE80211_RADIOTAP_DB_ANTNOISE 218This field contains a single unsigned 8-bit value that indicates the 219RF noise power at the antenna, in decibels difference from an 220arbitrary, fixed reference. 221.It Dv IEEE80211_RADIOTAP_XCHANNEL 222This field contains four values: a 32-bit unsigned bitmap of 223flags that describe the channel attributes, a 16-bit unsigned 224frequency in MHz (typically the channel center), an 8-bit 225unsigned IEEE channel number, and a signed 8-bit value that 226holds the maximum regulatory transmit power cap in .5 dBm 227(8 bytes total). 228Channel flags are defined in: 229.In net80211/_ieee80211.h 230(only a subset are found in 231.In net80211/ieee80211_radiotap.h ). 232This property supersedes 233.Dv IEEE80211_RADIOTAP_CHANNEL 234and is the only way to completely express all 235channel attributes and the 236mapping between channel frequency and IEEE channel number. 237.El 238.Sh EXAMPLES 239Radiotap receive definitions for the Intersil Prism driver: 240.Bd -literal -offset indent 241#define WI_RX_RADIOTAP_PRESENT \\ 242 ((1 << IEEE80211_RADIOTAP_TSFT) \\ 243 (1 << IEEE80211_RADIOTAP_FLAGS) | \\ 244 (1 << IEEE80211_RADIOTAP_RATE) | \\ 245 (1 << IEEE80211_RADIOTAP_CHANNEL) | \\ 246 (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \\ 247 (1 << IEEE80211_RADIOTAP_DB_ANTNOISE)) 248 249struct wi_rx_radiotap_header { 250 struct ieee80211_radiotap_header wr_ihdr; 251 uint64_t wr_tsf; 252 uint8_t wr_flags; 253 uint8_t wr_rate; 254 uint16_t wr_chan_freq; 255 uint16_t wr_chan_flags; 256 uint8_t wr_antsignal; 257 uint8_t wr_antnoise; 258} __packed __aligned(8); 259.Ed 260.Pp 261and transmit definitions for the Atheros driver: 262.Bd -literal -offset indent 263#define ATH_TX_RADIOTAP_PRESENT ( \\ 264 (1 << IEEE80211_RADIOTAP_FLAGS) | \\ 265 (1 << IEEE80211_RADIOTAP_RATE) | \\ 266 (1 << IEEE80211_RADIOTAP_DBM_TX_POWER) | \\ 267 (1 << IEEE80211_RADIOTAP_ANTENNA) | \\ 268 (1 << IEEE80211_RADIOTAP_XCHANNEL) | \\ 269 0) 270 271struct ath_tx_radiotap_header { 272 struct ieee80211_radiotap_header wt_ihdr; 273 uint8_t wt_flags; 274 uint8_t wt_rate; 275 uint8_t wt_txpower; 276 uint8_t wt_antenna; 277 uint32_t wt_chan_flags; 278 uint16_t wt_chan_freq; 279 uint8_t wt_chan_ieee; 280 int8_t wt_chan_maxpow; 281} __packed; 282.Ed 283.Sh SEE ALSO 284.Xr tcpdump 1 , 285.Xr bpf 4 , 286.Xr ieee80211 9 287.Sh HISTORY 288The 289.Nm 290definitions first appeared in 291.Nx 1.5 . 292.\" 293.Sh AUTHORS 294.An -nosplit 295The original version of this manual page was written by 296.An Bruce M. Simpson Aq Mt bms@FreeBSD.org 297and 298.An Darron Broad Aq Mt darron@kewl.org . 299