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