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