diff options
author | bms <bms@FreeBSD.org> | 2004-03-04 12:52:10 +0000 |
---|---|---|
committer | bms <bms@FreeBSD.org> | 2004-03-04 12:52:10 +0000 |
commit | 2897d868a21fadca593fc93a20cd8a61061c7f17 (patch) | |
tree | 0e2b9dd2c2dbf20107bfa0e81386092cf230b2ca /share/man/man9/ieee80211_radiotap.9 | |
parent | 450e7b33b66881879fbf58001e0459335a249899 (diff) | |
download | FreeBSD-src-2897d868a21fadca593fc93a20cd8a61061c7f17.zip FreeBSD-src-2897d868a21fadca593fc93a20cd8a61061c7f17.tar.gz |
Initial import of documentation for net80211 interface code.
Of particular interest here is the ieee80211_radiotap(9) man page.
TODO: Flesh out ieee80211_node.9, ieee80211_proto.9.
Submitted by: bms (with help from Darron Broad)
Diffstat (limited to 'share/man/man9/ieee80211_radiotap.9')
-rw-r--r-- | share/man/man9/ieee80211_radiotap.9 | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/share/man/man9/ieee80211_radiotap.9 b/share/man/man9/ieee80211_radiotap.9 new file mode 100644 index 0000000..1adebed --- /dev/null +++ b/share/man/man9/ieee80211_radiotap.9 @@ -0,0 +1,214 @@ +.\" +.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org> +.\" Copyright (c) 2004 Darron Broad <darron@kewl.org> +.\" 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$ +.\" $Id: ieee80211_radiotap.9,v 1.3 2004/03/04 11:38:52 bruce Exp $ +.\" +.Dd March 2, 2004 +.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 +This typically includes information such as signal quality and +timestamps. +This information may be used by a variety of user agents, including +.Xr tcpdump 1 . +It is requested by using the +.Xr bpf 4 +data-link type +.Vt 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 packed structure embedding an instance of +.Vt struct ieee80211_radiotap_header +at the beginning, +with subsequent fields in the appropriate order, +and a macro to set the bits of the +.Vt it_present +bitmap to indicate which fields exist and are filled in by the driver. +.\" +.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 +.Fn ieee80211_ifattach +by calling +.Fn bpfattach2 +with the data-link type set to +.Vt DLT_IEEE_80211_RADIO . +.Pp +.\" +When the 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 ".Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION" +.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 '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_EXT +This bit is reserved for any future extensions to the +.Vt radiotap +structure. +It should not be used at this time. +.El +.Sh EXAMPLE +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 \\ + ((1 << IEEE80211_RADIOTAP_FLAGS) | \\ + (1 << IEEE80211_RADIOTAP_RATE) | \\ + (1 << IEEE80211_RADIOTAP_CHANNEL) | \\ + (1 << IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \\ + (1 << 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 +The +.Nm +interface was designed and implemented by +.An David Young Aq dyoung@pobox.com . +.Pp +This manual page was written by +.An Bruce M. Simpson Aq bms@FreeBSD.org +and +.An Darron Broad Aq darron@kewl.org . |