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