ieee80211_radiotap(9)

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

dent bpf(4)
attachment for the capture of information about 802.11 traf

fic 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 con

sisting of a
standard preamble followed by an extensible bitmap indicat

ing 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(1). 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 pre

sent */

} __attribute__((__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 the userland via a separate

bpf attachment. It is necessary for the driver to create this attach

ment after
calling ieee80211_ifattach(9) by calling bpfattach2() with

the data-link
type set to DLT_IEEE_80211_RADIO.

When the the information is available, usually immediately

before a linklayer 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,

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 dif

ference 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 dif

ference 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 re

ferred 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 pow

er set at factory calibration. 0 indicates maximum transmit pow

er. Monotonically nondecreasing with lower power levels.

IEEE80211_RADIOTAP_DBM_TX_POWER

Transmit power expressed as decibels from a 1mW ref

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

bels 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_EXT

This bit is reserved for any future extensions to

the radiotap
structure. It should not be used at this time.

EXAMPLES

Radiotap header for the Cisco Aironet driver:

struct an_rx_radiotap_header {

struct ieee80211_radiotap_header ar_ih

dr;
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 implement

ed by David
Young <dyoung@pobox.com>.

This manual page was written by Bruce M. Simpson <bms@FreeB

SD.org> and
Darron Broad <darron@kewl.org>.

BSD March 2, 2004

BSD