[src/uebayasi-xip]: src/share/man/man9 \\ -> \e

[joerg <joerg%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7391b06f1eaf
branches:  uebayasi-xip
changeset: 751641:7391b06f1eaf
user:      joerg <joerg%NetBSD.org@localhost>
date:      Mon Apr 05 19:34:29 2010 +0000

description:
\\ -> \e

diffstat:

 share/man/man9/ieee80211_radiotap.9 |  277 ++++++++++++++++++++++++++++++++++++
 1 files changed, 277 insertions(+), 0 deletions(-)

diffs (281 lines):

diff -r 366d056ee4ea -r 7391b06f1eaf share/man/man9/ieee80211_radiotap.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/ieee80211_radiotap.9       Mon Apr 05 19:34:29 2010 +0000
@@ -0,0 +1,277 @@
+.\" $NetBSD: ieee80211_radiotap.9,v 1.12.2.2 2010/04/05 19:34:29 joerg Exp $
+.\"
+.\" Copyright (c) 2004 Bruce M. Simpson <bms%spc.org@localhost>,
+.\"                    Darron Broad <darron%kewl.org@localhost>.
+.\" Copyright (c) 2004, 2007   David Young <dyoung%pobox.com@localhost>.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" $FreeBSD: src/share/man/man9/ieee80211_radiotap.9,v 1.3 2004/07/07 12:59:39 ru Exp $
+.\"
+.Dd March 12, 2006
+.Dt IEEE80211_RADIOTAP 9
+.Os
+.Sh NAME
+.Nm ieee80211_radiotap
+.Nd software 802.11 stack packet capture definitions
+.Sh SYNOPSIS
+.In net80211/ieee80211_var.h
+.In net80211/ieee80211_ioctl.h
+.In net80211/ieee80211_radiotap.h
+.In net/bpf.h
+.\"
+.Sh DESCRIPTION
+The
+.Nm
+definitions provide a device-independent
+.Xr bpf 4
+attachment for the
+capture of information about 802.11 traffic which is not part of
+the 802.11 frame structure.
+.Pp
+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.
+.Pp
+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.
+.Pp
+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.
+.Pp
+This typically includes information such as signal quality and
+timestamps.
+This information may be used by a variety of user agents, including
+.Xr tcpdump 8 .
+It is requested by using the
+.Xr bpf 4
+data-link type
+.Dv DLT_IEEE_80211_RADIO .
+.Pp
+.\"
+Each frame using this attachment has the following header prepended to it:
+.Bd -literal -offset indent
+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__));
+.Ed
+.Pp
+.\"
+A device driver implementing
+.Vt radiotap
+typically defines a structure embedding an instance of
+.Vt "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
+.Va it_present
+bitmap to indicate which fields exist and are filled in by the driver.
+.\"
+.Pp
+Radiotap capture fields are in little-endian byte order.
+.Pp
+Radiotap capture fields
+.Em 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
+.Xr tcpdump 8 ,
+expect the padding.
+.Pp
+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.
+.Pp
+Radiotap headers are copied to the userland via a separate bpf attachment.
+It is necessary for the driver to create this attachment after calling
+.Xr ieee80211_ifattach 9
+by calling
+.Fn bpfattach2
+with the data-link type set to
+.Dv DLT_IEEE802_11_RADIO .
+.Pp
+.\"
+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
+.Fn bpf_mtap2
+function.
+.Pp
+.\"
+The following extension fields are defined for
+.Vt radiotap ,
+in the order in which they should appear in the buffer copied to userland:
+.Bl -tag -width indent
+.It Dv 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.
+.It Dv 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.
+.It Dv IEEE80211_RADIOTAP_RATE
+This field contains a single unsigned 8-bit value, which is the data rate in
+use in units of 500Kbps.
+.It Dv 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,
+.In net80211/ieee80211_radiotap.h .
+.It Dv 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.
+.It Dv 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.
+.It Dv 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.
+.It Dv 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
+.Dq "Signal Quality"
+in some datasheets.
+.It Dv 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.
+.It Dv 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.
+.It Dv 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.
+.It Dv 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.
+.It Dv 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.
+.It Dv 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.
+.It Dv IEEE80211_RADIOTAP_RX_FLAGS
+An unsigned 16-bit bitmap indicating properties of received frames.
+.It Dv IEEE80211_RADIOTAP_TX_FLAGS
+An unsigned 16-bit bitmap indicating properties of transmitted frames.
+.It Dv 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).
+.It Dv 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.
+.It Dv IEEE80211_RADIOTAP_EXT
+This bit is reserved for any future extensions to the
+.Vt radiotap
+structure.
+A driver sets
+.Dv 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 setting
+.Dv IEEE80211_RADIOTAP_EXT
+in the extensions.
+The bitmap ends at the first extension field where
+.Dv IEEE80211_RADIOTAP_EXT
+is not set.
+.El
+.Sh EXAMPLES
+Radiotap header for the Cisco Aironet driver:
+.Bd -literal -offset indent
+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__));
+.Ed
+.Pp
+Bitmap indicating which fields are present in the above structure:
+.Bd -literal -offset indent
+#define AN_RX_RADIOTAP_PRESENT \e
+       ((1 \*[Gt]\*[Gt] IEEE80211_RADIOTAP_FLAGS) | \e
+        (1 \*[Gt]\*[Gt] IEEE80211_RADIOTAP_RATE) | \e
+        (1 \*[Gt]\*[Gt] IEEE80211_RADIOTAP_CHANNEL) | \e
+        (1 \*[Gt]\*[Gt] IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \e
+        (1 \*[Gt]\*[Gt] IEEE80211_RADIOTAP_DBM_ANTNOISE))
+.Ed
+.Sh SEE ALSO
+.Xr bpf 4 ,
+.Xr ieee80211 9
+.Sh HISTORY
+The
+.Nm
+definitions first appeared in
+.Nx 1.5 ,
+and were later ported to
+.Fx 4.6 .
+.\"
+.Sh AUTHORS
+.An -nosplit
+The
+.Nm
+interface was designed and implemented by
+.An David Young Aq dyoung%pobox.com@localhost .
+.An David Young
+is the maintainer of the radiotap capture format.
+Contact him to add new capture fields.
+.Pp
+This manual page was written by
+.An Bruce M. Simpson Aq bms%FreeBSD.org@localhost
+and
+.An Darron Broad Aq darron%kewl.org@localhost .