unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

IEEE80211_RADIOTAP(9)    BSD Kernel Developer's Manual   IEEE80211_RADIOTAP(9)

NAME
     ieee80211_radiotap -- software 802.11 stack packet capture definitions

SYNOPSIS
     #include <&lt;net80211/ieee80211_var.h>&gt;
     #include <&lt;net80211/ieee80211_ioctl.h>&gt;
     #include <&lt;net80211/ieee80211_radiotap.h>&gt;
     #include <&lt;net/bpf.h>&gt;

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 suitable
     alignment, in the same order as the bits indicating their presence.

     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 {
                   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 struc-
     ture 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 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 <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 mea-
             suring 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.  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_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 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 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
     bpf(4), ieee80211(9)

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

BSD                            January 21, 2014                            BSD