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