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_filter_item {
  91         char name[32];
  92         uint64_t rx;
  93         uint64_t tx;
  94 };
  95
  96 struct wprobe_iface_ops;
  97 struct wprobe_iface {
  98         const struct wprobe_iface_ops *ops;
  99
 100         int sockfd;
 101         const char *ifname;
 102         unsigned int genl_family;
 103         char addr[6];
 104
 105         struct list_head global_attr;
 106         struct list_head link_attr;
 107         struct list_head links;
 108
 109         /* config */
 110         int interval;
 111         int scale_min;
 112         int scale_max;
 113         int scale_m;
 114         int scale_d;
 115
 116         /* filter */
 117         void *filter;
 118
 119         /* filter_len:
 120          *   set to -1 to drop the current filter
 121          *   automatically reset to 0 after config apply
 122          */
 123         int filter_len;
 124 };
 125
 126 typedef void (*wprobe_filter_cb)(void *arg, const char *group, struct wprobe_filter_item *items, int n_items);
 127 extern int wprobe_port;
 128
 129 /**
 130  * wprobe_update_links: get a list of all link partners
 131  * @dev: wprobe device structure
 132  * @list: linked list for storing link descriptions
 133  *
 134  * when wprobe_update_links is called multiple times, the linked list
 135  * is updated with new link partners, old entries are automatically expired
 136  */
 137 extern int wprobe_update_links(struct wprobe_iface *dev);
 138
 139 /**
 140  * wprobe_dump_filters: dump all layer 2 filter counters
 141  * @dev: wprobe device structure
 142  * @cb: callback (called once per filter group)
 143  * @arg: user argument for the callback
 144  */
 145 extern int wprobe_dump_filters(struct wprobe_iface *dev, wprobe_filter_cb cb, void *arg);
 146
 147 /**
 148  * wprobe_measure: start a measurement request for all global attributes
 149  * @dev: wprobe device structure
 150  *
 151  * not all attributes are automatically filled with data, since for some
 152  * it may be desirable to control the sampling interval from user space
 153  * you can use this function to do that.
 154  */
 155 extern int wprobe_measure(struct wprobe_iface *dev);
 156
 157 /**
 158  * wprobe_get_dev: get a handle to a local wprobe device
 159  * @ifname: name of the wprobe interface
 160  *
 161  * queries the wprobe interface for all attributes
 162  * must be freed with wprobe_free_dev
 163  */
 164 extern struct wprobe_iface *wprobe_get_dev(const char *ifname);
 165
 166 /**
 167  * wprobe_get_auto: get a handle to a local or remote wprobe device
 168  * @arg: pointer to the wprobe device, either <dev> (local) or <host>:<dev> (remote)
 169  */
 170 extern struct wprobe_iface *wprobe_get_auto(const char *arg, char **err);
 171
 172 /**
 173  * wprobe_get_dev: free all device information
 174  * @dev: wprobe device structure
 175  */
 176 extern void wprobe_free_dev(struct wprobe_iface *dev);
 177
 178 /**
 179  * wprobe_apply_config: apply configuration data
 180  * @dev: wprobe device structure
 181  *
 182  * uploads all configuration values from @dev that are not set to -1
 183  */
 184 extern int wprobe_apply_config(struct wprobe_iface *dev);
 185
 186 /**
 187  * wprobe_request_data: request new sampling values for the given list of attributes
 188  * @dev: wprobe device structure
 189  * @addr: (optional) mac address of the link partner
 190  *
 191  * if addr is unset, global values are stored in the global attributes list
 192  * if addr is set, per-link values for the given address are stored in the link attributes list
 193  */
 194 extern int wprobe_request_data(struct wprobe_iface *dev, const unsigned char *addr);
 195
 196 /**
 197  * wprobe_server_init: send a wprobe server init message to a server's client socket
 198  * @socket: socket of the connection to the client
 199  */
 200 extern int wprobe_server_init(int socket);
 201
 202 /**
 203  * wprobe_server_handle: read a request from the client socket, process it, send the response
 204  * @socket: socket of the connection to the client
 205  */
 206 extern int wprobe_server_handle(int socket);
 207
 208 /**
 209  * wprobe_server_done: release memory allocated for the server connection
 210  */
 211 extern void wprobe_server_done(void);
 212
 213 #endif