About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / networking / radiotap-headers.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:04 EST.

1	How to use radiotap headers
2	===========================
3	
4	Pointer to the radiotap include file
5	------------------------------------
6	
7	Radiotap headers are variable-length and extensible, you can get most of the
8	information you need to know on them from:
9	
10	./include/net/ieee80211_radiotap.h
11	
12	This document gives an overview and warns on some corner cases.
13	
14	
15	Structure of the header
16	-----------------------
17	
18	There is a fixed portion at the start which contains a u32 bitmap that defines
19	if the possible argument associated with that bit is present or not.  So if b0
20	of the it_present member of ieee80211_radiotap_header is set, it means that
21	the header for argument index 0 (IEEE80211_RADIOTAP_TSFT) is present in the
22	argument area.
23	
24	   < 8-byte ieee80211_radiotap_header >
25	   [ <possible argument bitmap extensions ... > ]
26	   [ <argument> ... ]
27	
28	At the moment there are only 13 possible argument indexes defined, but in case
29	we run out of space in the u32 it_present member, it is defined that b31 set
30	indicates that there is another u32 bitmap following (shown as "possible
31	argument bitmap extensions..." above), and the start of the arguments is moved
32	forward 4 bytes each time.
33	
34	Note also that the it_len member __le16 is set to the total number of bytes
35	covered by the ieee80211_radiotap_header and any arguments following.
36	
37	
38	Requirements for arguments
39	--------------------------
40	
41	After the fixed part of the header, the arguments follow for each argument
42	index whose matching bit is set in the it_present member of
43	ieee80211_radiotap_header.
44	
45	 - the arguments are all stored little-endian!
46	
47	 - the argument payload for a given argument index has a fixed size.  So
48	   IEEE80211_RADIOTAP_TSFT being present always indicates an 8-byte argument is
49	   present.  See the comments in ./include/net/ieee80211_radiotap.h for a nice
50	   breakdown of all the argument sizes
51	
52	 - the arguments must be aligned to a boundary of the argument size using
53	   padding.  So a u16 argument must start on the next u16 boundary if it isn't
54	   already on one, a u32 must start on the next u32 boundary and so on.
55	
56	 - "alignment" is relative to the start of the ieee80211_radiotap_header, ie,
57	   the first byte of the radiotap header.  The absolute alignment of that first
58	   byte isn't defined.  So even if the whole radiotap header is starting at, eg,
59	   address 0x00000003, still the first byte of the radiotap header is treated as
60	   0 for alignment purposes.
61	
62	 - the above point that there may be no absolute alignment for multibyte
63	   entities in the fixed radiotap header or the argument region means that you
64	   have to take special evasive action when trying to access these multibyte
65	   entities.  Some arches like Blackfin cannot deal with an attempt to
66	   dereference, eg, a u16 pointer that is pointing to an odd address.  Instead
67	   you have to use a kernel API get_unaligned() to dereference the pointer,
68	   which will do it bytewise on the arches that require that.
69	
70	 - The arguments for a given argument index can be a compound of multiple types
71	   together.  For example IEEE80211_RADIOTAP_CHANNEL has an argument payload
72	   consisting of two u16s of total length 4.  When this happens, the padding
73	   rule is applied dealing with a u16, NOT dealing with a 4-byte single entity.
74	
75	
76	Example valid radiotap header
77	-----------------------------
78	
79		0x00, 0x00, // <-- radiotap version + pad byte
80		0x0b, 0x00, // <- radiotap header length
81		0x04, 0x0c, 0x00, 0x00, // <-- bitmap
82		0x6c, // <-- rate (in 500kHz units)
83		0x0c, //<-- tx power
84		0x01 //<-- antenna
85	
86	
87	Using the Radiotap Parser
88	-------------------------
89	
90	If you are having to parse a radiotap struct, you can radically simplify the
91	job by using the radiotap parser that lives in net/wireless/radiotap.c and has
92	its prototypes available in include/net/cfg80211.h.  You use it like this:
93	
94	#include <net/cfg80211.h>
95	
96	/* buf points to the start of the radiotap header part */
97	
98	int MyFunction(u8 * buf, int buflen)
99	{
100		int pkt_rate_100kHz = 0, antenna = 0, pwr = 0;
101		struct ieee80211_radiotap_iterator iterator;
102		int ret = ieee80211_radiotap_iterator_init(&iterator, buf, buflen);
103	
104		while (!ret) {
105	
106			ret = ieee80211_radiotap_iterator_next(&iterator);
107	
108			if (ret)
109				continue;
110	
111			/* see if this argument is something we can use */
112	
113			switch (iterator.this_arg_index) {
114			/*
115			 * You must take care when dereferencing iterator.this_arg
116			 * for multibyte types... the pointer is not aligned.  Use
117			 * get_unaligned((type *)iterator.this_arg) to dereference
118			 * iterator.this_arg for type "type" safely on all arches.
119			 */
120			case IEEE80211_RADIOTAP_RATE:
121				/* radiotap "rate" u8 is in
122				 * 500kbps units, eg, 0x02=1Mbps
123				 */
124				pkt_rate_100kHz = (*iterator.this_arg) * 5;
125				break;
126	
127			case IEEE80211_RADIOTAP_ANTENNA:
128				/* radiotap uses 0 for 1st ant */
129				antenna = *iterator.this_arg);
130				break;
131	
132			case IEEE80211_RADIOTAP_DBM_TX_POWER:
133				pwr = *iterator.this_arg;
134				break;
135	
136			default:
137				break;
138			}
139		}  /* while more rt headers */
140	
141		if (ret != -ENOENT)
142			return TXRX_DROP;
143	
144		/* discard the radiotap header part */
145		buf += iterator.max_length;
146		buflen -= iterator.max_length;
147	
148		...
149	
150	}
151	
152	Andy Green <andy@warmcat.com>
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.