c0b4902f3cbdb3458d0a90575d122e122849cb4a
[openwrt/svn-archive/archive.git] / package / wprobe / src / user / wprobe.h
1 /*
2 * wprobe.h: Wireless probe user space library
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_USER_H
17 #define __WPROBE_USER_H
18 #include <inttypes.h>
19 #include <stdint.h>
20 #include <stdbool.h>
21 #include "list.h"
22
23 /**
24 * struct wprobe_value: data structure for attribute values
25 * @STRING: string value (currently unsupported)
26 * @U8: unsigned 8-bit integer value
27 * @U16: unsigned 16-bit integer value
28 * @U32: unsigned 32-bit integer value
29 * @U64: unsigned 64-bit integer value
30 * @S8: signed 8-bit integer value
31 * @S16: signed 16-bit integer value
32 * @S32: signed 32-bit integer value
33 * @S64: signed 64-bit integer value
34 *
35 * @n: number of sample values
36 * @avg: average value
37 * @stdev: standard deviation
38 * @s: sum of all sample values (internal use)
39 * @ss: sum of all sample values squared (internal use)
40 */
41 struct wprobe_value {
42 /* attribute value */
43 union {
44 const char *STRING;
45 uint8_t U8;
46 uint16_t U16;
47 uint32_t U32;
48 uint64_t U64;
49 int8_t S8;
50 int16_t S16;
51 int32_t S32;
52 int64_t S64;
53 };
54 /* statistics */
55 int64_t s, ss;
56 float avg, stdev;
57 unsigned int n;
58 };
59
60 /**
61 * struct wprobe_attribute: data structures for attribute descriptions
62 * @list: linked list data structure for a list of attributes
63 * @id: attribute id
64 * @type: netlink type for the attribute (see kernel api documentation)
65 * @flags: attribute flags (see kernel api documentation)
66 * @val: cached version of the last netlink query, will be overwritten on each request
67 * @name: attribute name
68 */
69 struct wprobe_attribute {
70 struct list_head list;
71 int id;
72 int type;
73 uint32_t flags;
74 struct wprobe_value val;
75 char name[];
76 };
77
78 /**
79 * struct wprobe_link: data structure for the link description
80 * @list: linked list data structure for a list of links
81 * @flags: link flags (see kernel api documentation)
82 * @addr: mac address of the remote link partner
83 */
84 struct wprobe_link {
85 struct list_head list;
86 uint32_t flags;
87 unsigned char addr[6];
88 };
89
90 struct wprobe_iface {
91 const char *ifname;
92 char addr[6];
93
94 struct list_head global_attr;
95 struct list_head link_attr;
96 struct list_head links;
97
98 /* config */
99 int interval;
100 int scale_min;
101 int scale_max;
102 int scale_m;
103 int scale_d;
104 };
105
106 /**
107 * wprobe_update_links: get a list of all link partners
108 * @ifname: name of the wprobe interface
109 * @list: linked list for storing link descriptions
110 *
111 * when wprobe_update_links is called multiple times, the linked list
112 * is updated with new link partners, old entries are automatically expired
113 */
114 extern int wprobe_update_links(struct wprobe_iface *dev);
115
116 /**
117 * wprobe_measure: start a measurement request for all global attributes
118 * @ifname: name of the wprobe interface
119 *
120 * not all attributes are automatically filled with data, since for some
121 * it may be desirable to control the sampling interval from user space
122 * you can use this function to do that.
123 */
124 extern int wprobe_measure(struct wprobe_iface *dev);
125
126 /**
127 * wprobe_get_dev: get device information
128 * @ifname: name of the wprobe interface
129 *
130 * queries the wprobe interface for all attributes
131 * must be freed with wprobe_free_dev
132 */
133 extern struct wprobe_iface *wprobe_get_dev(const char *ifname);
134
135 /**
136 * wprobe_get_dev: free all device information
137 * @dev: wprobe device structure
138 */
139 extern void wprobe_free_dev(struct wprobe_iface *dev);
140
141 /**
142 * wprobe_apply_config: apply configuration data
143 * @dev: wprobe device structure
144 *
145 * uploads all configuration values from @dev that are not set to -1
146 */
147 extern int wprobe_apply_config(struct wprobe_iface *dev);
148
149 /**
150 * wprobe_request_data: request new sampling values for the given list of attributes
151 * @dev: wprobe device structure
152 * @addr: (optional) mac address of the link partner
153 *
154 * if addr is unset, global values are stored in the global attributes list
155 * if addr is set, per-link values for the given address are stored in the link attributes list
156 */
157 extern int wprobe_request_data(struct wprobe_iface *dev, const unsigned char *addr);
158
159 #endif