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