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