NAME
ieee80211_radiotap
—
software 802.11 stack packet capture
definitions
SYNOPSIS
#include
<net80211/ieee80211_var.h>
#include
<net80211/ieee80211_ioctl.h>
#include
<net80211/ieee80211_radiotap.h>
#include <net/bpf.h>
DESCRIPTION
The ieee80211_radiotap
definitions provide
a device-independent
bpf(4) attachment for the capture of information about 802.11 traffic
which is not part of the 802.11 frame structure.
Radiotap was designed to balance the desire for a capture format that conserved CPU and memory bandwidth on embedded systems, with the desire for a hardware-independent, extensible format that would support the diverse capabilities of virtually all 802.11 radios.
These considerations led radiotap to settle on a format consisting of a standard preamble followed by an extensible bitmap indicating the presence of optional capture fields.
The capture fields were packed into the header as compactly as possible, modulo the requirements that they had to be packed swiftly, with suitable alignment, in the same order as the bits indicating their presence.
This typically includes information such as signal quality and
timestamps. This information may be used by a variety of user agents,
including tcpdump(8). It is requested by using the
bpf(4) data-link type
DLT_IEEE802_11_RADIO
.
Each frame using this attachment has the following header prepended to it:
struct ieee80211_radiotap_header { u_int8_t it_version; /* set to 0 */ u_int8_t it_pad; u_int16_t it_len; /* entire length */ u_int32_t it_present; /* fields present */ } __packed;
A device driver implementing radiotap typically defines a packed structure embedding an instance of struct ieee80211_radiotap_header at the beginning, with subsequent fields in the appropriate order, and a macro to set the bits of the it_present bitmap to indicate which fields exist and are filled in by the driver.
Radiotap headers are copied to userland via a
separate bpf attachment. It is necessary for the driver to create this
attachment after calling
ieee80211_ifattach(9) by calling
bpfattach2
()
with the data-link type set to
DLT_IEEE802_11_RADIO
.
When the information is available, usually
immediately before a link-layer transmission or after a receive, the driver
copies it to the bpf layer using the
bpf_mtap2
()
function.
The following extension fields are defined for radiotap, in the order in which they should appear in the buffer copied to userland:
IEEE80211_RADIOTAP_TSFT
- This field contains the unsigned 64-bit value, in microseconds, of the MAC's 802.11 Time Synchronization Function timer, when the first bit of the MPDU arrived at the MAC. This field should be present for received frames only.
IEEE80211_RADIOTAP_FLAGS
- This field contains a single unsigned 8-bit value, containing a bitmap of flags specifying properties of the frame being transmitted or received.
IEEE80211_RADIOTAP_RATE
- This field contains a single unsigned 8-bit value, which is the data rate in use in units of 500Kbps.
IEEE80211_RADIOTAP_CHANNEL
- This field contains two unsigned 16-bit values. The first value is the
frequency upon which this PDU was transmitted or received. The second
value is a bitmap containing flags which specify properties of the channel
in use. These are documented within the header file
<net80211/ieee80211_radiotap.h>
. IEEE80211_RADIOTAP_FHSS
- This field contains two 8-bit values. This field should be present for frequency-hopping radios only. The first byte is the hop set. The second byte is the pattern in use.
IEEE80211_RADIOTAP_DBM_ANTSIGNAL
- This field contains a single signed 8-bit value, which indicates the RF signal power at the antenna, in decibels difference from 1mW.
IEEE80211_RADIOTAP_DBM_ANTNOISE
- This field contains a single signed 8-bit value, which indicates the RF noise power at the antenna, in decibels difference from 1mW.
IEEE80211_RADIOTAP_LOCK_QUALITY
- This field contains a single unsigned 16-bit value, indicating the quality of the Barker Code lock. No unit is specified for this field. There does not appear to be a standard way of measuring this at this time; this quantity is often referred to as “Signal Quality” in some datasheets.
IEEE80211_RADIOTAP_TX_ATTENUATION
- This field contains a single unsigned 16-bit value, expressing transmit power as unitless distance from maximum power set at factory calibration. 0 indicates maximum transmit power. Monotonically nondecreasing with lower power levels.
IEEE80211_RADIOTAP_DB_TX_ATTENUATION
- This field contains a single unsigned 16-bit value, expressing transmit power as decibel distance from maximum power set at factory calibration. 0 indicates maximum transmit power. Monotonically nondecreasing with lower power levels.
IEEE80211_RADIOTAP_DBM_TX_POWER
- Transmit power expressed as decibels from a 1mW reference. This field is a single signed 8-bit value. This is the absolute power level measured at the antenna port.
IEEE80211_RADIOTAP_ANTENNA
- For radios which support antenna diversity, this field contains a single unsigned 8-bit value specifying which antenna is being used to transmit or receive this frame. The first antenna is antenna 0.
IEEE80211_RADIOTAP_DB_ANTSIGNAL
- This field contains a single unsigned 8-bit value, which indicates the RF signal power at the antenna, in decibels difference from an arbitrary, fixed reference.
IEEE80211_RADIOTAP_DB_ANTNOISE
- This field contains a single unsigned 8-bit value, which indicates the RF noise power at the antenna, in decibels difference from an arbitrary, fixed reference.
IEEE80211_RADIOTAP_HWQUEUE
- This field contains a single unsigned 8-bit value specifying which hardware queue is being used to transmit the frame.
IEEE80211_RADIOTAP_RSSI
- This field contains two unsigned 8-bit values. The first value is the received signal strength index (RSSI) which indicates the RF signal power at the antenna. The second value is the relative maximum RSSI value of the RF interface.
IEEE80211_RADIOTAP_EXT
- This bit is reserved for any future extensions to the
radiotap structure. A driver can set
IEEE80211_RADIOTAP_EXT
to extend the it_present bitmap by another 64 bits. The bitmap can be extended by multiples of 32 bits to 96, 128, 160 bits, or longer, by settingIEEE80211_RADIOTAP_EXT
in the extensions. The bitmap ends at the first extension field whereIEEE80211_RADIOTAP_EXT
is not set.
EXAMPLES
Radiotap header for the Realtek RTL8180L driver rtw(4):
struct rtw_rx_radiotap_header { struct ieee80211_radiotap_header rr_ihdr; u_int64_t rr_tsft; u_int8_t rr_flags; u_int8_t rr_rate; u_int16_t rr_chan_freq; u_int16_t rr_chan_flags; u_int16_t rr_barker_lock; u_int8_t rr_antsignal; } __packed;
Bitmap indicating which fields are present in the above structure:
#define RTW_RX_RADIOTAP_PRESENT \ ((1 << IEEE80211_RADIOTAP_TSFT) | \ (1 << IEEE80211_RADIOTAP_FLAGS) | \ (1 << IEEE80211_RADIOTAP_RATE) | \ (1 << IEEE80211_RADIOTAP_CHANNEL) | \ (1 << IEEE80211_RADIOTAP_LOCK_QUALITY) | \ (1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \ 0)
SEE ALSO
HISTORY
The ieee80211_radiotap
definitions first
appeared in NetBSD 1.5, and were later ported to
FreeBSD 4.6 and OpenBSD
3.6.
AUTHORS
The ieee80211_radiotap
interface was
designed and implemented by David Young
<dyoung@pobox.com>.
This manual page was written by Bruce M. Simpson <bms@FreeBSD.org> and Darron Broad <darron@kewl.org>.