Add the ieee80211(9) API manual pages.
[dragonfly.git] / share / man / man9 / ieee80211_radiotap.9
1 .\"
2 .\" Copyright (c) 2004  Bruce M. Simpson <bms@spc.org>,
3 .\"                     Darron Broad <darron@kewl.org>,
4 .\"                     David Young <dyoung@pobox.com>.
5 .\" All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\"    notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\"    notice, this list of conditions and the following disclaimer in the
14 .\"    documentation and/or other materials provided with the distribution.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" $FreeBSD$
29 .\: $DragonFly: src/share/man/man9/ieee80211_radiotap.9,v 1.1 2004/07/27 14:50:56 hmp Exp $
30 .\" $Id: ieee80211_radiotap.9,v 1.3 2004/07/07 12:59:39 ru Exp $
31 .\"
32 .Dd March 2, 2004
33 .Dt IEEE80211_RADIOTAP 9
34 .Os
35 .Sh NAME
36 .Nm ieee80211_radiotap
37 .Nd software 802.11 stack packet capture definitions
38 .Sh SYNOPSIS
39 .In net80211/ieee80211_var.h
40 .In net80211/ieee80211_ioctl.h
41 .In net80211/ieee80211_radiotap.h
42 .In net/bpf.h
43 .\"
44 .Sh DESCRIPTION
45 The
46 .Nm
47 definitions provide a device-independent
48 .Xr bpf 4
49 attachment for the
50 capture of information about 802.11 traffic which is not part of
51 the 802.11 frame structure.
52 .Pp
53 Radiotap was designed to balance the desire for a capture format
54 that conserved CPU and memory bandwidth on embedded systems,
55 with the desire for a hardware-independent, extensible format
56 that would support the diverse capabilities of virtually all
57 802.11
58 radios.
59 .Pp
60 These considerations led radiotap to settle on a format consisting of
61 a standard preamble followed by an extensible bitmap indicating the
62 presence of optional capture fields.
63 .Pp
64 The capture fields were packed into the header as compactly as possible,
65 modulo the requirements that they had to be packed swiftly,
66 with suitable alignment, in the same order as the bits indicating
67 their presence.
68 .Pp
69 This typically includes information such as signal quality and
70 timestamps.
71 This information may be used by a variety of user agents, including
72 .Xr tcpdump 1 .
73 It is requested by using the
74 .Xr bpf 4
75 data-link type
76 .Dv DLT_IEEE_80211_RADIO .
77 .Pp
78 .\"
79 Each frame using this attachment has the following header prepended to it:
80 .Bd -literal -offset indent
81 struct ieee80211_radiotap_header {
82         u_int8_t        it_version;     /* set to 0 */
83         u_int8_t        it_pad;
84         u_int16_t       it_len;         /* entire length */
85         u_int32_t       it_present;     /* fields present */
86 } __attribute__((__packed__));
87 .Ed
88 .Pp
89 .\"
90 A device driver implementing
91 .Vt radiotap
92 typically defines a packed structure embedding an instance of
93 .Vt "struct ieee80211_radiotap_header"
94 at the beginning,
95 with subsequent fields in the appropriate order,
96 and a macro to set the bits of the
97 .Va it_present
98 bitmap to indicate which fields exist and are filled in by the driver.
99 .\"
100 .Pp
101 Radiotap headers are copied to the userland via a separate bpf attachment.
102 It is necessary for the driver to create this attachment after calling
103 .Xr ieee80211_ifattach 9
104 by calling
105 .Fn bpfattach2
106 with the data-link type set to
107 .Dv DLT_IEEE_80211_RADIO .
108 .Pp
109 .\"
110 When the the information is available,
111 usually immediately before a link-layer transmission or after a receive,
112 the driver copies it to the bpf layer using the
113 .Fn bpf_mtap2
114 function.
115 .Pp
116 .\"
117 The following extension fields are defined for
118 .Vt radiotap ,
119 in the order in which they should appear in the buffer copied to userland:
120 .Bl -tag -width indent
121 .It Dv IEEE80211_RADIOTAP_TSFT
122 This field contains the unsigned 64-bit value, in microseconds,
123 of the MAC's 802.11 Time Synchronization Function timer,
124 when the first bit of the MPDU arrived at the MAC.
125 This field should be present for received frames only.
126 .It Dv IEEE80211_RADIOTAP_FLAGS
127 This field contains a single unsigned 8-bit value, containing a bitmap
128 of flags specifying properties of the frame being transmitted or received.
129 .It Dv IEEE80211_RADIOTAP_RATE
130 This field contains a single unsigned 8-bit value, which is the data rate in
131 use in units of 500Kbps.
132 .It Dv IEEE80211_RADIOTAP_CHANNEL
133 This field contains two unsigned 16-bit values.
134 The first value is the frequency upon which this PDU was transmitted
135 or received.
136 The second value is a bitmap containing flags which specify properties of
137 the channel in use.
138 These are documented within the header file,
139 .Pa net80211/ieee80211_radiotap.h .
140 .It Dv IEEE80211_RADIOTAP_FHSS
141 This field contains two 8-bit values.
142 This field should be present for frequency-hopping radios only.
143 The first byte is the hop set.
144 The second byte is the pattern in use.
145 .It Dv IEEE80211_RADIOTAP_DBM_ANTSIGNAL
146 This field contains a single signed 8-bit value, which indicates the
147 RF signal power at the antenna, in decibels difference from 1mW.
148 .It Dv IEEE80211_RADIOTAP_DBM_ANTNOISE
149 This field contains a single signed 8-bit value, which indicates the
150 RF noise power at the antenna, in decibels difference from 1mW.
151 .It Dv IEEE80211_RADIOTAP_LOCK_QUALITY
152 This field contains a single unsigned 16-bit value, indicating the
153 quality of the Barker Code lock.
154 No unit is specified for this field.
155 There does not appear to be a standard way of measuring this at this time;
156 this quantity is often referred to as
157 .Dq "Signal Quality"
158 in some datasheets.
159 .It Dv IEEE80211_RADIOTAP_TX_ATTENUATION
160 This field contains a single unsigned 16-bit value, expressing transmit
161 power as unitless distance from maximum power set at factory calibration.
162 0 indicates maximum transmit power.
163 Monotonically nondecreasing with lower power levels.
164 .It Dv IEEE80211_RADIOTAP_DB_TX_ATTENUATION
165 This field contains a single unsigned 16-bit value, expressing transmit
166 power as decibel distance from maximum power set at factory calibration.
167 0 indicates maximum transmit power.
168 Monotonically nondecreasing with lower power levels.
169 .It Dv IEEE80211_RADIOTAP_DBM_TX_POWER
170 Transmit power expressed as decibels from a 1mW reference.
171 This field is a single signed 8-bit value.
172 This is the absolute power level measured at the antenna port.
173 .It Dv IEEE80211_RADIOTAP_ANTENNA
174 For radios which support antenna diversity, this field contains a single
175 unsigned 8-bit value specifying which antenna is being used to transmit
176 or receive this frame.
177 The first antenna is antenna 0.
178 .It Dv IEEE80211_RADIOTAP_DB_ANTSIGNAL
179 This field contains a single unsigned 8-bit value, which indicates the
180 RF signal power at the antenna, in decibels difference from an
181 arbitrary, fixed reference.
182 .It Dv IEEE80211_RADIOTAP_DB_ANTNOISE
183 This field contains a single unsigned 8-bit value, which indicates the
184 RF noise power at the antenna, in decibels difference from an
185 arbitrary, fixed reference.
186 .It Dv IEEE80211_RADIOTAP_EXT
187 This bit is reserved for any future extensions to the
188 .Vt radiotap
189 structure.
190 It should not be used at this time.
191 .El
192 .Sh EXAMPLES
193 Radiotap header for the Cisco Aironet driver:
194 .Bd -literal -offset indent
195 struct an_rx_radiotap_header {
196         struct ieee80211_radiotap_header        ar_ihdr;
197         u_int8_t        ar_flags;
198         u_int8_t        ar_rate;
199         u_int16_t       ar_chan_freq;
200         u_int16_t       ar_chan_flags;
201         u_int8_t        ar_antsignal;
202         u_int8_t        ar_antnoise;
203 } __attribute__((__packed__));
204 .Ed
205 .Pp
206 Bitmap indicating which fields are present in the above structure:
207 .Bd -literal -offset indent
208 #define AN_RX_RADIOTAP_PRESENT \\
209         ((1 << IEEE80211_RADIOTAP_FLAGS) | \\
210          (1 << IEEE80211_RADIOTAP_RATE) | \\
211          (1 << IEEE80211_RADIOTAP_CHANNEL) | \\
212          (1 << IEEE80211_RADIOTAP_DBM_ANTSIGNAL) | \\
213          (1 << IEEE80211_RADIOTAP_DBM_ANTNOISE))
214 .Ed
215 .Sh SEE ALSO
216 .Xr bpf 4 ,
217 .Xr ieee80211 9
218 .Sh HISTORY
219 The
220 .Nm
221 definitions first appeared in
222 .Nx 1.5 ,
223 and were later ported to
224 .Fx 4.6 .
225 .\"
226 .Sh AUTHORS
227 .An -nosplit
228 The
229 .Nm
230 interface was designed and implemented by
231 .An David Young Aq dyoung@pobox.com .
232 .Pp
233 This manual page was written by
234 .An Bruce M. Simpson Aq bms@FreeBSD.org
235 and
236 .An Darron Broad Aq darron@kewl.org .