wprobe: move measurement task to the kernel, add some configurability (work in progress)
[openwrt/svn-archive/archive.git] / package / wprobe / src / kernel / linux / wprobe.h
1 /*
2 * wprobe.h: API for the wireless probe interface
3 * Copyright (C) 2008-2009 Felix Fietkau <nbd@openwrt.org>
4 *
5 * This program is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU General Public License
7 * as published by the Free Software Foundation; either version 2
8 * of the License, or (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 */
15
16 #ifndef __WPROBE_H
17 #define __WPROBE_H
18
19 #ifdef __KERNEL__
20 #include <linux/types.h>
21 #include <linux/if_ether.h>
22 #include <linux/spinlock.h>
23 #include <linux/module.h>
24 #include <linux/list.h>
25 #include <net/genetlink.h>
26 #endif
27
28 /**
29 * enum wprobe_attr: netlink attribute list
30 *
31 * @WPROBE_ATTR_UNSPEC: unused
32 *
33 * @WPROBE_ATTR_INTERFACE: interface name to process query on (NLA_STRING)
34 * @WPROBE_ATTR_MAC: mac address (used for wireless links) (NLA_STRING)
35 * @WPROBE_ATTR_FLAGS: interface/link/attribute flags (see enum wprobe_flags) (NLA_U32)a
36 * @WPROBE_ATTR_DURATION: sampling duration (in milliseconds) (NLA_MSECS)
37 *
38 * @WPROBE_ATTR_ID: attribute id (NLA_U32)
39 * @WPROBE_ATTR_NAME: attribute name (NLA_STRING)
40 * @WPROBE_ATTR_TYPE: attribute type (NLA_U8)
41 *
42 * attribute values:
43 *
44 * @WPROBE_VAL_STRING: string value (NLA_STRING)
45 * @WPROBE_VAL_S8: signed 8-bit integer (NLA_U8)
46 * @WPROBE_VAL_S16: signed 16-bit integer (NLA_U16)
47 * @WPROBE_VAL_S32: signed 32-bit integer (NLA_U32)
48 * @WPROBE_VAL_S64: signed 64-bit integer (NLA_U64)
49 * @WPROBE_VAL_U8: unsigned 8-bit integer (NLA_U8)
50 * @WPROBE_VAL_U16: unsigned 16-bit integer (NLA_U16)
51 * @WPROBE_VAL_U32: unsigned 32-bit integer (NLA_U32)
52 * @WPROBE_VAL_U64: unsigned 64-bit integer (NLA_U64)
53 *
54 * statistics:
55 * @WPROBE_VAL_SUM: sum of all samples
56 * @WPROBE_VAL_SUM_SQ: sum of all samples^2
57 * @WPROBE_VAL_SAMPLES: number of samples
58 * @WPROBE_VAL_SCALE_TIME: last time the samples were scaled down
59 *
60 * configuration:
61 * @WPROBE_ATTR_INTERVAL: (measurement interval in milliseconds) (NLA_MSECS)
62 * @WPROBE_ATTR_SAMPLES_MIN: minimum samples to keep during inactivity (NLA_U32)
63 * @WPROBE_ATTR_SAMPLES_MAX: maximum samples to keep before scaling down (NLA_U32)
64 * @WPROBE_ATTR_SAMPLES_SCALE_M: multiplier for scaling down samples (NLA_U32)
65 * @WPROBE_ATTR_SAMPLES_SCALE_D: divisor for scaling down samples (NLA_U32)
66 *
67 * @WPROBE_ATTR_LAST: unused
68 */
69 enum wprobe_attr {
70 /* query attributes */
71 WPROBE_ATTR_UNSPEC,
72 WPROBE_ATTR_INTERFACE,
73 WPROBE_ATTR_MAC,
74 WPROBE_ATTR_FLAGS,
75
76 /* response data */
77 WPROBE_ATTR_ID,
78 WPROBE_ATTR_NAME,
79 WPROBE_ATTR_TYPE,
80 WPROBE_ATTR_DURATION,
81
82 /* value type attributes */
83 WPROBE_VAL_STRING,
84 WPROBE_VAL_S8,
85 WPROBE_VAL_S16,
86 WPROBE_VAL_S32,
87 WPROBE_VAL_S64,
88 WPROBE_VAL_U8,
89 WPROBE_VAL_U16,
90 WPROBE_VAL_U32,
91 WPROBE_VAL_U64,
92
93 /* aggregates for statistics */
94 WPROBE_VAL_SUM,
95 WPROBE_VAL_SUM_SQ,
96 WPROBE_VAL_SAMPLES,
97 WPROBE_VAL_SCALE_TIME,
98
99 /* config attributes */
100 WPROBE_ATTR_INTERVAL,
101 WPROBE_ATTR_SAMPLES_MIN,
102 WPROBE_ATTR_SAMPLES_MAX,
103 WPROBE_ATTR_SAMPLES_SCALE_M,
104 WPROBE_ATTR_SAMPLES_SCALE_D,
105
106 WPROBE_ATTR_LAST
107 };
108
109
110 /**
111 * enum wprobe_cmd: netlink commands for interacting with wprobe
112 *
113 * @WPROBE_CMD_UNSPEC: unused
114 *
115 * @WPROBE_CMD_GET_LIST: get global/link property list
116 * @WPROBE_CMD_GET_INFO: get global/link properties
117 * @WPROBE_CMD_SET_FLAGS: set global/link flags
118 * @WPROBE_CMD_MEASURE: take a snapshot of the current data
119 * @WPROBE_CMD_GET_LINKS: get a list of links
120 *
121 * @WPROBE_CMD_LAST: unused
122 *
123 * options for GET_INFO and SET_FLAGS:
124 * - mac address set: per-link
125 * - mac address unset: globalsa
126 */
127 enum wprobe_cmd {
128 WPROBE_CMD_UNSPEC,
129 WPROBE_CMD_GET_LIST,
130 WPROBE_CMD_GET_INFO,
131 WPROBE_CMD_SET_FLAGS,
132 WPROBE_CMD_MEASURE,
133 WPROBE_CMD_GET_LINKS,
134 WPROBE_CMD_CONFIG,
135 WPROBE_CMD_LAST
136 };
137
138 /**
139 * enum wprobe_flags: flags for wprobe links and items
140 * @WPROBE_F_KEEPSTAT: keep statistics for this link/device
141 * @WPROBE_F_RESET: reset statistics now (used only in WPROBE_CMD_SET_LINK)
142 * @WPROBE_F_NEWDATA: used to indicate that a value has been updated
143 */
144 enum wprobe_flags {
145 WPROBE_F_KEEPSTAT = (1 << 0),
146 WPROBE_F_RESET = (1 << 1),
147 WPROBE_F_NEWDATA = (1 << 2),
148 };
149
150 #ifdef __KERNEL__
151
152 struct wprobe_link;
153 struct wprobe_item;
154 struct wprobe_source;
155
156 /**
157 * struct wprobe_link - data structure describing a wireless link
158 * @iface: pointer to the wprobe_iface that this link belongs to
159 * @addr: BSSID of the remote link partner
160 * @flags: link flags (see wprobe_flags)
161 * @priv: user pointer
162 *
163 * @list: for internal use
164 * @val: for internal use
165 */
166 struct wprobe_link {
167 struct list_head list;
168 struct wprobe_iface *iface;
169 char addr[ETH_ALEN];
170 u32 flags;
171 void *priv;
172 void *val;
173 };
174
175 /**
176 * struct wprobe_item - data structure describing the format of wprobe_link::data or wprobe_iface::data
177 * @name: name of the field
178 * @type: data type of this field
179 * @flags: measurement item flags (see wprobe_flags)
180 */
181 struct wprobe_item {
182 const char *name;
183 enum wprobe_attr type;
184 u32 flags;
185 };
186
187 struct wprobe_value {
188 bool pending;
189 union {
190 /*
191 * the following are kept uppercase to allow
192 * for automated checking against WPROBE_VAL_*
193 * via BUG_ON()
194 */
195 const char *STRING;
196 u8 U8;
197 u16 U16;
198 u32 U32;
199 u64 U64;
200 s8 S8;
201 s16 S16;
202 s32 S32;
203 s64 S64;
204 };
205 s64 s, ss;
206 unsigned int n;
207
208 /* timestamps */
209 u64 first, last;
210 u64 scale_timestamp;
211 };
212
213 /**
214 * struct wprobe_source - data structure describing a wireless interface
215 *
216 * @name: name of the interface
217 * @addr: local mac address of the interface
218 * @links: list of wireless links to poll
219 * @link_items: description of the per-link data structure
220 * @n_link_items: number of link description items
221 * @global_items: description of the per-interface data structure
222 * @n_global_items: number of per-interface description items
223 * @sync_data: callback allowing the driver to prepare data for the wprobe poll
224 *
225 * @list: head for the list of interfaces
226 * @priv: user pointer
227 * @lock: spinlock protecting value data access
228 * @val: internal use
229 * @query_val: internal use
230 *
231 * if sync_data is NULL, wprobe assumes that it can access the data structure
232 * at any time (in atomic context). if sync_data returns a negative error code,
233 * the poll request will not be handled for the given link
234 */
235 struct wprobe_iface {
236 /* to be filled in by wprobe source drivers */
237 const char *name;
238 const char *addr;
239 const struct wprobe_item *link_items;
240 int n_link_items;
241 const struct wprobe_item *global_items;
242 int n_global_items;
243
244 int (*sync_data)(struct wprobe_iface *dev, struct wprobe_link *l,
245 struct wprobe_value *val, bool measure);
246 void *priv;
247
248 /* handled by the wprobe core */
249 struct list_head list;
250 struct list_head links;
251 spinlock_t lock;
252 void *val;
253 void *query_val;
254
255 u32 measure_interval;
256 struct timer_list measure_timer;
257
258 u32 scale_min;
259 u32 scale_max;
260 u32 scale_m;
261 u32 scale_d;
262 };
263
264 #define WPROBE_FILL_BEGIN(_ptr, _list) do { \
265 struct wprobe_value *__val = (_ptr); \
266 const struct wprobe_item *__item = _list; \
267 u64 __msecs = jiffies_to_msecs(jiffies)
268
269 #define WPROBE_SET(_idx, _type, _value) \
270 if (__item[_idx].type != WPROBE_VAL_##_type) { \
271 printk("ERROR: invalid data type at %s:%d\n", __FILE__, __LINE__); \
272 break; \
273 } \
274 __val[_idx].pending = true; \
275 __val[_idx]._type = _value; \
276 if (!__val[_idx].first) \
277 __val[_idx].first = __msecs; \
278 __val[_idx].first = __msecs
279
280 #define WPROBE_FILL_END() \
281 } while(0)
282
283 /**
284 * wprobe_add_iface: register an interface with the wireless probe subsystem
285 * @dev: wprobe_iface structure describing the interface
286 */
287 extern int __weak wprobe_add_iface(struct wprobe_iface *dev);
288
289 /**
290 * wprobe_remove_iface: deregister an interface from the wireless probe subsystem
291 * @dev: wprobe_iface structure describing the interface
292 */
293 extern void __weak wprobe_remove_iface(struct wprobe_iface *dev);
294
295 /**
296 * wprobe_add_link: register a new wireless link
297 * @dev: wprobe_iface structure describing the interface
298 * @l: storage space for the wprobe_link structure
299 * @addr: mac address of the new link
300 *
301 * the entire wprobe_link structure is overwritten by this function call
302 */
303 extern int __weak wprobe_add_link(struct wprobe_iface *dev, struct wprobe_link *l, const char *addr);
304
305 /**
306 * wprobe_remove_link: deregister a previously registered wireless link
307 * @dev: wprobe_iface structure describing the interface
308 * @l: wprobe_link data structure
309 */
310 extern void __weak wprobe_remove_link(struct wprobe_iface *dev, struct wprobe_link *l);
311
312 /**
313 * wprobe_update_stats: update statistics after sampling values
314 * @dev: wprobe_iface structure describing the interface
315 * @l: wprobe_link data structure
316 *
317 * if l == NULL, then the stats for globals are updated
318 */
319 extern void __weak wprobe_update_stats(struct wprobe_iface *dev, struct wprobe_link *l);
320
321 #endif /* __KERNEL__ */
322
323 #endif