[linux-2.6-block.git] / Documentation / networking / radiotap-headers.txt

How to use radiotap headers
===========================

Pointer to the radiotap include file
------------------------------------

Radiotap headers are variable-length and extensible, you can get most of the
information you need to know on them from:

./include/net/ieee80211_radiotap.h

This document gives an overview and warns on some corner cases.


Structure of the header
-----------------------

There is a fixed portion at the start which contains a u32 bitmap that defines
if the possible argument associated with that bit is present or not.  So if b0
of the it_present member of ieee80211_radiotap_header is set, it means that
the header for argument index 0 (IEEE80211_RADIOTAP_TSFT) is present in the
argument area.

   < 8-byte ieee80211_radiotap_header >
   [ <possible argument bitmap extensions ... > ]
   [ <argument> ... ]

At the moment there are only 13 possible argument indexes defined, but in case
we run out of space in the u32 it_present member, it is defined that b31 set
indicates that there is another u32 bitmap following (shown as "possible
argument bitmap extensions..." above), and the start of the arguments is moved
forward 4 bytes each time.

Note also that the it_len member __le16 is set to the total number of bytes
covered by the ieee80211_radiotap_header and any arguments following.


Requirements for arguments
--------------------------

After the fixed part of the header, the arguments follow for each argument
index whose matching bit is set in the it_present member of
ieee80211_radiotap_header.

 - the arguments are all stored little-endian!

 - the argument payload for a given argument index has a fixed size.  So
   IEEE80211_RADIOTAP_TSFT being present always indicates an 8-byte argument is
   present.  See the comments in ./include/net/ieee80211_radiotap.h for a nice
   breakdown of all the argument sizes

 - the arguments must be aligned to a boundary of the argument size using
   padding.  So a u16 argument must start on the next u16 boundary if it isn't
   already on one, a u32 must start on the next u32 boundary and so on.

 - "alignment" is relative to the start of the ieee80211_radiotap_header, ie,
   the first byte of the radiotap header.  The absolute alignment of that first
   byte isn't defined.  So even if the whole radiotap header is starting at, eg,
   address 0x00000003, still the first byte of the radiotap header is treated as
   0 for alignment purposes.

 - the above point that there may be no absolute alignment for multibyte
   entities in the fixed radiotap header or the argument region means that you
   have to take special evasive action when trying to access these multibyte
   entities.  Some arches like Blackfin cannot deal with an attempt to
   dereference, eg, a u16 pointer that is pointing to an odd address.  Instead
   you have to use a kernel API get_unaligned() to dereference the pointer,
   which will do it bytewise on the arches that require that.

 - The arguments for a given argument index can be a compound of multiple types
   together.  For example IEEE80211_RADIOTAP_CHANNEL has an argument payload
   consisting of two u16s of total length 4.  When this happens, the padding
   rule is applied dealing with a u16, NOT dealing with a 4-byte single entity.


Example valid radiotap header
-----------------------------

	0x00, 0x00, // <-- radiotap version + pad byte
	0x0b, 0x00, // <- radiotap header length
	0x04, 0x0c, 0x00, 0x00, // <-- bitmap
	0x6c, // <-- rate (in 500kHz units)
	0x0c, //<-- tx power
	0x01 //<-- antenna


Using the Radiotap Parser
-------------------------

If you are having to parse a radiotap struct, you can radically simplify the
job by using the radiotap parser that lives in net/wireless/radiotap.c and has
its prototypes available in include/net/cfg80211.h.  You use it like this:

#include <net/cfg80211.h>

/* buf points to the start of the radiotap header part */

int MyFunction(u8 * buf, int buflen)
{
	int pkt_rate_100kHz = 0, antenna = 0, pwr = 0;
	struct ieee80211_radiotap_iterator iterator;
	int ret = ieee80211_radiotap_iterator_init(&iterator, buf, buflen);

	while (!ret) {

		ret = ieee80211_radiotap_iterator_next(&iterator);

		if (ret)
			continue;

		/* see if this argument is something we can use */

		switch (iterator.this_arg_index) {
		/*
		 * You must take care when dereferencing iterator.this_arg
		 * for multibyte types... the pointer is not aligned.  Use
		 * get_unaligned((type *)iterator.this_arg) to dereference
		 * iterator.this_arg for type "type" safely on all arches.
		 */
		case IEEE80211_RADIOTAP_RATE:
			/* radiotap "rate" u8 is in
			 * 500kbps units, eg, 0x02=1Mbps
			 */
			pkt_rate_100kHz = (*iterator.this_arg) * 5;
			break;

		case IEEE80211_RADIOTAP_ANTENNA:
			/* radiotap uses 0 for 1st ant */
			antenna = *iterator.this_arg);
			break;

		case IEEE80211_RADIOTAP_DBM_TX_POWER:
			pwr = *iterator.this_arg;
			break;

		default:
			break;
		}
	}  /* while more rt headers */

	if (ret != -ENOENT)
		return TXRX_DROP;

	/* discard the radiotap header part */
	buf += iterator.max_length;
	buflen -= iterator.max_length;

	...

}

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