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