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