160 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===========================4How to use radiotap headers5===========================6 7Pointer to the radiotap include file8------------------------------------9 10Radiotap headers are variable-length and extensible, you can get most of the11information you need to know on them from::12 13 ./include/net/ieee80211_radiotap.h14 15This document gives an overview and warns on some corner cases.16 17 18Structure of the header19-----------------------20 21There is a fixed portion at the start which contains a u32 bitmap that defines22if the possible argument associated with that bit is present or not. So if b023of the it_present member of ieee80211_radiotap_header is set, it means that24the header for argument index 0 (IEEE80211_RADIOTAP_TSFT) is present in the25argument 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 case34we run out of space in the u32 it_present member, it is defined that b31 set35indicates that there is another u32 bitmap following (shown as "possible36argument bitmap extensions..." above), and the start of the arguments is moved37forward 4 bytes each time.38 39Note also that the it_len member __le16 is set to the total number of bytes40covered by the ieee80211_radiotap_header and any arguments following.41 42 43Requirements for arguments44--------------------------45 46After the fixed part of the header, the arguments follow for each argument47index whose matching bit is set in the it_present member of48ieee80211_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. So53 IEEE80211_RADIOTAP_TSFT being present always indicates an 8-byte argument is54 present. See the comments in ./include/net/ieee80211_radiotap.h for a nice55 breakdown of all the argument sizes56 57 - the arguments must be aligned to a boundary of the argument size using58 padding. So a u16 argument must start on the next u16 boundary if it isn't59 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 first63 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 as65 0 for alignment purposes.66 67 - the above point that there may be no absolute alignment for multibyte68 entities in the fixed radiotap header or the argument region means that you69 have to take special evasive action when trying to access these multibyte70 entities. Some arches like Blackfin cannot deal with an attempt to71 dereference, eg, a u16 pointer that is pointing to an odd address. Instead72 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 types76 together. For example IEEE80211_RADIOTAP_CHANNEL has an argument payload77 consisting of two u16s of total length 4. When this happens, the padding78 rule is applied dealing with a u16, NOT dealing with a 4-byte single entity.79 80 81Example valid radiotap header82-----------------------------83 84::85 86 0x00, 0x00, // <-- radiotap version + pad byte87 0x0b, 0x00, // <- radiotap header length88 0x04, 0x0c, 0x00, 0x00, // <-- bitmap89 0x6c, // <-- rate (in 500kHz units)90 0x0c, //<-- tx power91 0x01 //<-- antenna92 93 94Using the Radiotap Parser95-------------------------96 97If you are having to parse a radiotap struct, you can radically simplify the98job by using the radiotap parser that lives in net/wireless/radiotap.c and has99its 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_arg123 * for multibyte types... the pointer is not aligned. Use124 * get_unaligned((type *)iterator.this_arg) to dereference125 * iterator.this_arg for type "type" safely on all arches.126 */127 case IEEE80211_RADIOTAP_RATE:128 /* radiotap "rate" u8 is in129 * 500kbps units, eg, 0x02=1Mbps130 */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