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 their natural
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_IEEE_80211_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 */
} __attribute__((__packed__));
A device driver implementing
radiotap typically defines a
structure embedding an instance of
struct
ieee80211_radiotap_header at the beginning, with subsequent fields
naturally aligned, and in the appropriate order. Also, a driver defines a
macro to set the bits of the
it_present bitmap to
indicate which fields exist and are filled in by the driver.
Radiotap capture fields are in little-endian byte order.
Radiotap capture fields
must be naturally aligned. That is,
16-, 32-, and 64-bit fields must begin on 16-, 32-, and 64-bit boundaries,
respectively. In this way, drivers can avoid unaligned accesses to radiotap
capture fields. radiotap-compliant drivers must insert padding before a
capture field to ensure its natural alignment. radiotap-compliant packet
dissectors, such as
tcpdump(8),
expect the padding.
Developers beware: all compilers may not pack structs alike. If a driver
developer constructs their radiotap header with a packed structure, in order
to ensure natural alignment, then it is important that they insert padding
bytes by themselves.
Radiotap headers are copied to the 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_RX_FLAGS
- An unsigned 16-bit bitmap indicating properties of received
frames.
-
-
IEEE80211_RADIOTAP_TX_FLAGS
- An unsigned 16-bit bitmap indicating properties of
transmitted frames.
-
-
IEEE80211_RADIOTAP_RTS_RETRIES
u_int8_t data
- Unsigned 8-bit value indicating how many times the NIC
retransmitted the Request to Send (RTS) in an RTS/CTS handshake before
receiving an 802.11 Clear to Send (CTS).
-
-
IEEE80211_RADIOTAP_DATA_RETRIES
- Unsigned 8-bit value indicating how many times the NIC
retransmitted a unicast data packet before receiving an 802.11
Acknowledgement.
-
-
IEEE80211_RADIOTAP_EXT
- This bit is reserved for any future extensions to the
radiotap structure. A driver sets
IEEE80211_RADIOTAP_EXT
to extend the it_present
bitmap by another 32 bits. The bitmap can be extended by multiples of 32
bits to 96, 128, 160 bits or longer, by setting
IEEE80211_RADIOTAP_EXT
in the extensions. The
bitmap ends at the first extension field where
IEEE80211_RADIOTAP_EXT
is not set.
EXAMPLES
Radiotap header for the Cisco Aironet driver:
struct an_rx_radiotap_header {
struct ieee80211_radiotap_header ar_ihdr;
u_int8_t ar_flags;
u_int8_t ar_rate;
u_int16_t ar_chan_freq;
u_int16_t ar_chan_flags;
u_int8_t ar_antsignal;
u_int8_t ar_antnoise;
} __attribute__((__packed__));
Bitmap indicating which fields are present in the above structure:
#define AN_RX_RADIOTAP_PRESENT \
((1 >> IEEE80211_RADIOTAP_FLAGS) | \
(1 >> IEEE80211_RADIOTAP_RATE) | \
(1 >> IEEE80211_RADIOTAP_CHANNEL) | \
(1 >> IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \
(1 >> IEEE80211_RADIOTAP_DBM_ANTNOISE))
SEE ALSO
bpf(4),
ieee80211(9)
HISTORY
The
ieee80211_radiotap definitions first appeared in
NetBSD 1.5, and were later ported to
FreeBSD 4.6.
AUTHORS
The
ieee80211_radiotap interface was designed and implemented
by
David Young
<
dyoung@pobox.com>.
David Young is the maintainer of the radiotap capture
format. Contact him to add new capture fields.
This manual page was written by
Bruce M. Simpson
<
bms@FreeBSD.org> and
Darron Broad
<
darron@kewl.org>.