Shape of My Heart

A madwifi device can be set to a pretty standard monitor mode, with a choice of several encapsulations. 802.11 is better than nothing, but doesn’t give the physical layer information I’m after. Radiotap and Prism monitoring headers are also supported, as well as output of the actual atheros descriptors used by the driver/HAL which contain HAL status information after each descriptor is processed by the hardware. The atheros descriptor format is something I’d like to look at later. With a choice of Prism or Radiotap, I’m going with Radiotap as it seems much saner.

Radiotap allows us to on a per-packet basis get RSSI (signal in db above noise floor), timing information (a 64-bit value in microseconds indicating when the first bit of the MPDU hit the MAC), rate, channel, and most importantly (for me at least) the 802.11 frame-check sequence which is usually stripped off the end of the frame before being passed up.

IEEE80211_RADIOTAP(9) DragonFly Kernel Developer's ManualIEEE80211_RADIOTAP(9)

NAME
ieee80211_radiotap -- software 802.11 stack packet capture definitions

SYNOPSIS
#include <net/bpf.h>
#include <netproto/802_11/ieee80211_var.h>
#include <netproto/802_11/ieee80211_ioctl.h>
#include <netproto/802_11/ieee80211_radiotap.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 pres-
ence 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 pres-
ence.

This typically includes information such as signal quality and time-
stamps. 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 {
uint8_t it_version; /* set to 0 */
uint8_t it_pad;
uint16_t it_len; /* entire length */
uint32_t it_present; /* fields present */
} __packed;

A device driver implementing radiotap typically defines a structure
embedding an instance of struct ieee80211_radiotap_header at the begin-
ning, 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, respec-
tively. 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 attach-
ment. It is necessary for the driver to create this attachment after
calling ieee80211_ifattach(9) by calling bpfattach_dlt() with the data-
link(2,5,1 ln) type set to DLT_IEEE_80211_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_ptap() 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 trans-
mitted 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 prop-
erties of the channel in use. These are documented within the
header file, <netproto/802_11/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 mea-
suring this at this time(1,3,9 boottime); 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.Mono-
tonically 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 fac-
tory calibration.0 indicates maximum transmit power. Monotoni-
cally 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 indi-
cates 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 indi-
cates the RF noise power at the antenna, in decibels difference
from an arbitrary, fixed reference.

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 64 bits. The bitmap can be extended
by multiples of 32 bits to 96, 128, 160 bits or longer, by set-
ting 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 Intel(R) PRO/Wireless 2200BG/2225BG/2915ABG
driver

struct iwi_rx_radiotap_header {
struct ieee80211_radiotap_header wr_ihdr;
uint8_t wr_flags;
uint8_t wr_rate;
uint16_t wr_chan_freq;
uint16_t wr_chan_flags;
uint8_t wr_antsignal;
uint8_t wr_antenna;
};

Bitmap indicating which fields are present in the above structure:

#define IWI_RX_RADIOTAP_PRESENT \
((1 << IEEE80211_RADIOTAP_FLAGS) | \
(1 << IEEE80211_RADIOTAP_RATE) | \
(1 << IEEE80211_RADIOTAP_CHANNEL) | \
(1 << IEEE80211_RADIOTAP_DB_ANTSIGNAL) | \
(1 << IEEE80211_RADIOTAP_ANTENNA))

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>.

DragonFly 1.7 December 25, 2006 DragonFly 1.7