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