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)

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 .