2 * wprobe.h: API for the wireless probe interface
3 * Copyright (C) 2008-2009 Felix Fietkau <nbd@openwrt.org>
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.
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.
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>
29 * enum wprobe_attr: netlink attribute list
31 * @WPROBE_ATTR_UNSPEC: unused
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)
38 * @WPROBE_ATTR_ID: attribute id (NLA_U32)
39 * @WPROBE_ATTR_NAME: attribute name (NLA_STRING)
40 * @WPROBE_ATTR_TYPE: attribute type (NLA_U8)
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)
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
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)
67 * @WPROBE_ATTR_LAST: unused
70 /* query attributes */
72 WPROBE_ATTR_INTERFACE
,
82 /* value type attributes */
93 /* aggregates for statistics */
97 WPROBE_VAL_SCALE_TIME
,
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
,
111 * enum wprobe_cmd: netlink commands for interacting with wprobe
113 * @WPROBE_CMD_UNSPEC: unused
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
121 * @WPROBE_CMD_LAST: unused
123 * options for GET_INFO and SET_FLAGS:
124 * - mac address set: per-link
125 * - mac address unset: globalsa
131 WPROBE_CMD_SET_FLAGS
,
133 WPROBE_CMD_GET_LINKS
,
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
145 WPROBE_F_KEEPSTAT
= (1 << 0),
146 WPROBE_F_RESET
= (1 << 1),
147 WPROBE_F_NEWDATA
= (1 << 2),
154 struct wprobe_source
;
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
163 * @list: for internal use
164 * @val: for internal use
167 struct list_head list
;
168 struct wprobe_iface
*iface
;
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)
183 enum wprobe_attr type
;
187 struct wprobe_value
{
191 * the following are kept uppercase to allow
192 * for automated checking against WPROBE_VAL_*
214 * struct wprobe_source - data structure describing a wireless interface
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
225 * @list: head for the list of interfaces
226 * @priv: user pointer
227 * @lock: spinlock protecting value data access
229 * @query_val: internal use
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
235 struct wprobe_iface
{
236 /* to be filled in by wprobe source drivers */
239 const struct wprobe_item
*link_items
;
241 const struct wprobe_item
*global_items
;
244 int (*sync_data
)(struct wprobe_iface
*dev
, struct wprobe_link
*l
,
245 struct wprobe_value
*val
, bool measure
);
248 /* handled by the wprobe core */
249 struct list_head list
;
250 struct list_head links
;
255 u32 measure_interval
;
256 struct timer_list measure_timer
;
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)
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__); \
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
280 #define WPROBE_FILL_END() \
284 * wprobe_add_iface: register an interface with the wireless probe subsystem
285 * @dev: wprobe_iface structure describing the interface
287 extern int __weak
wprobe_add_iface(struct wprobe_iface
*dev
);
290 * wprobe_remove_iface: deregister an interface from the wireless probe subsystem
291 * @dev: wprobe_iface structure describing the interface
293 extern void __weak
wprobe_remove_iface(struct wprobe_iface
*dev
);
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
301 * the entire wprobe_link structure is overwritten by this function call
303 extern int __weak
wprobe_add_link(struct wprobe_iface
*dev
, struct wprobe_link
*l
, const char *addr
);
306 * wprobe_remove_link: deregister a previously registered wireless link
307 * @dev: wprobe_iface structure describing the interface
308 * @l: wprobe_link data structure
310 extern void __weak
wprobe_remove_link(struct wprobe_iface
*dev
, struct wprobe_link
*l
);
313 * wprobe_update_stats: update statistics after sampling values
314 * @dev: wprobe_iface structure describing the interface
315 * @l: wprobe_link data structure
317 * if l == NULL, then the stats for globals are updated
319 extern void __weak
wprobe_update_stats(struct wprobe_iface
*dev
, struct wprobe_link
*l
);
321 #endif /* __KERNEL__ */