0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===========================
0004 How to use radiotap headers
0005 ===========================
0006
0007 Pointer to the radiotap include file
0008 ------------------------------------
0009
0010 Radiotap headers are variable-length and extensible, you can get most of the
0011 information you need to know on them from::
0012
0013 ./include/net/ieee80211_radiotap.h
0014
0015 This document gives an overview and warns on some corner cases.
0016
0017
0018 Structure of the header
0019 -----------------------
0020
0021 There is a fixed portion at the start which contains a u32 bitmap that defines
0022 if the possible argument associated with that bit is present or not. So if b0
0023 of the it_present member of ieee80211_radiotap_header is set, it means that
0024 the header for argument index 0 (IEEE80211_RADIOTAP_TSFT) is present in the
0025 argument area.
0026
0027 ::
0028
0029 < 8-byte ieee80211_radiotap_header >
0030 [ <possible argument bitmap extensions ... > ]
0031 [ <argument> ... ]
0032
0033 At the moment there are only 13 possible argument indexes defined, but in case
0034 we run out of space in the u32 it_present member, it is defined that b31 set
0035 indicates that there is another u32 bitmap following (shown as "possible
0036 argument bitmap extensions..." above), and the start of the arguments is moved
0037 forward 4 bytes each time.
0038
0039 Note also that the it_len member __le16 is set to the total number of bytes
0040 covered by the ieee80211_radiotap_header and any arguments following.
0041
0042
0043 Requirements for arguments
0044 --------------------------
0045
0046 After the fixed part of the header, the arguments follow for each argument
0047 index whose matching bit is set in the it_present member of
0048 ieee80211_radiotap_header.
0049
0050 - the arguments are all stored little-endian!
0051
0052 - the argument payload for a given argument index has a fixed size. So
0053 IEEE80211_RADIOTAP_TSFT being present always indicates an 8-byte argument is
0054 present. See the comments in ./include/net/ieee80211_radiotap.h for a nice
0055 breakdown of all the argument sizes
0056
0057 - the arguments must be aligned to a boundary of the argument size using
0058 padding. So a u16 argument must start on the next u16 boundary if it isn't
0059 already on one, a u32 must start on the next u32 boundary and so on.
0060
0061 - "alignment" is relative to the start of the ieee80211_radiotap_header, ie,
0062 the first byte of the radiotap header. The absolute alignment of that first
0063 byte isn't defined. So even if the whole radiotap header is starting at, eg,
0064 address 0x00000003, still the first byte of the radiotap header is treated as
0065 0 for alignment purposes.
0066
0067 - the above point that there may be no absolute alignment for multibyte
0068 entities in the fixed radiotap header or the argument region means that you
0069 have to take special evasive action when trying to access these multibyte
0070 entities. Some arches like Blackfin cannot deal with an attempt to
0071 dereference, eg, a u16 pointer that is pointing to an odd address. Instead
0072 you have to use a kernel API get_unaligned() to dereference the pointer,
0073 which will do it bytewise on the arches that require that.
0074
0075 - The arguments for a given argument index can be a compound of multiple types
0076 together. For example IEEE80211_RADIOTAP_CHANNEL has an argument payload
0077 consisting of two u16s of total length 4. When this happens, the padding
0078 rule is applied dealing with a u16, NOT dealing with a 4-byte single entity.
0079
0080
0081 Example valid radiotap header
0082 -----------------------------
0083
0084 ::
0085
0086 0x00, 0x00, // <-- radiotap version + pad byte
0087 0x0b, 0x00, // <- radiotap header length
0088 0x04, 0x0c, 0x00, 0x00, // <-- bitmap
0089 0x6c, // <-- rate (in 500kHz units)
0090 0x0c, //<-- tx power
0091 0x01 //<-- antenna
0092
0093
0094 Using the Radiotap Parser
0095 -------------------------
0096
0097 If you are having to parse a radiotap struct, you can radically simplify the
0098 job by using the radiotap parser that lives in net/wireless/radiotap.c and has
0099 its prototypes available in include/net/cfg80211.h. You use it like this::
0100
0101 #include <net/cfg80211.h>
0102
0103 /* buf points to the start of the radiotap header part */
0104
0105 int MyFunction(u8 * buf, int buflen)
0106 {
0107 int pkt_rate_100kHz = 0, antenna = 0, pwr = 0;
0108 struct ieee80211_radiotap_iterator iterator;
0109 int ret = ieee80211_radiotap_iterator_init(&iterator, buf, buflen);
0110
0111 while (!ret) {
0112
0113 ret = ieee80211_radiotap_iterator_next(&iterator);
0114
0115 if (ret)
0116 continue;
0117
0118 /* see if this argument is something we can use */
0119
0120 switch (iterator.this_arg_index) {
0121 /*
0122 * You must take care when dereferencing iterator.this_arg
0123 * for multibyte types... the pointer is not aligned. Use
0124 * get_unaligned((type *)iterator.this_arg) to dereference
0125 * iterator.this_arg for type "type" safely on all arches.
0126 */
0127 case IEEE80211_RADIOTAP_RATE:
0128 /* radiotap "rate" u8 is in
0129 * 500kbps units, eg, 0x02=1Mbps
0130 */
0131 pkt_rate_100kHz = (*iterator.this_arg) * 5;
0132 break;
0133
0134 case IEEE80211_RADIOTAP_ANTENNA:
0135 /* radiotap uses 0 for 1st ant */
0136 antenna = *iterator.this_arg);
0137 break;
0138
0139 case IEEE80211_RADIOTAP_DBM_TX_POWER:
0140 pwr = *iterator.this_arg;
0141 break;
0142
0143 default:
0144 break;
0145 }
0146 } /* while more rt headers */
0147
0148 if (ret != -ENOENT)
0149 return TXRX_DROP;
0150
0151 /* discard the radiotap header part */
0152 buf += iterator.max_length;
0153 buflen -= iterator.max_length;
0154
0155 ...
0156
0157 }
0158
0159 Andy Green <andy@warmcat.com>
