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 August 4, 2009 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.Pp 108.Bd -literal -offset indent 109if (ieee80211_radiotap_active_vap(vap)) { 110 ... /* record transmit state */ 111 ieee80211_radiotap_tx(vap, m); /* capture transmit event */ 112} 113.Ed 114.Pp 115While in the receive path capture is handled in 116.Nm net80211 117but state must be captured before dispatching a frame: 118.Pp 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 net80211/_ieee80211.h 234(only a subset are found in 235.In net80211/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 bms@FreeBSD.org 303and 304.An Darron Broad Aq darron@kewl.org . 305