Documentation/networking/radiotap-headers.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===========================
   4 How to use radiotap headers
   5 ===========================
   6
   7 Pointer to the radiotap include file
   8 ------------------------------------
   9
  10 Radiotap headers are variable-length and extensible, you can get most of the
  11 information you need to know on them from::
  12
  13     ./include/net/ieee80211_radiotap.h
  14
  15 This document gives an overview and warns on some corner cases.
  16
  17
  18 Structure of the header
  19 -----------------------
  20
  21 There is a fixed portion at the start which contains a u32 bitmap that defines
  22 if the possible argument associated with that bit is present or not.  So if b0
  23 of the it_present member of ieee80211_radiotap_header is set, it means that
  24 the header for argument index 0 (IEEE80211_RADIOTAP_TSFT) is present in the
  25 argument area.
  26
  27 ::
  28
  29    < 8-byte ieee80211_radiotap_header >
  30    [ <possible argument bitmap extensions ... > ]
  31    [ <argument> ... ]
  32
  33 At the moment there are only 13 possible argument indexes defined, but in case
  34 we run out of space in the u32 it_present member, it is defined that b31 set
  35 indicates that there is another u32 bitmap following (shown as "possible
  36 argument bitmap extensions..." above), and the start of the arguments is moved
  37 forward 4 bytes each time.
  38
  39 Note also that the it_len member __le16 is set to the total number of bytes
  40 covered by the ieee80211_radiotap_header and any arguments following.
  41
  42
  43 Requirements for arguments
  44 --------------------------
  45
  46 After the fixed part of the header, the arguments follow for each argument
  47 index whose matching bit is set in the it_present member of
  48 ieee80211_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
  81 Example 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
  94 Using the Radiotap Parser
  95 -------------------------
  96
  97 If you are having to parse a radiotap struct, you can radically simplify the
  98 job by using the radiotap parser that lives in net/wireless/radiotap.c and has
  99 its 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
 159 Andy Green <andy@warmcat.com>