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