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 /**
  91  * wprobe_init: initialize internal data structures and connect to the wprobe netlink api
  92  */
  93 extern int wprobe_init(void);
  94
  95 /**
  96  * wprobe_free: free all internally allocated data structures
  97  */
  98 extern void wprobe_free(void);
  99
 100 /**
 101  * wprobe_update_links: get a list of all link partners
 102  * @ifname: name of the wprobe interface
 103  * @list: linked list for storing link descriptions
 104  *
 105  * when wprobe_update_links is called multiple times, the linked list
 106  * is updated with new link partners, old entries are automatically expired
 107  */
 108 extern int wprobe_update_links(const char *ifname, struct list_head *list);
 109
 110 /**
 111  * wprobe_measure: start a measurement request for all global attributes
 112  * @ifname: name of the wprobe interface
 113  *
 114  * not all attributes are automatically filled with data, since for some
 115  * it may be desirable to control the sampling interval from user space
 116  * you can use this function to do that.
 117  */
 118 extern void wprobe_measure(const char *ifname);
 119
 120 /**
 121  * wprobe_dump_attributes: create a linked list of available attributes
 122  * @ifname: name of the wprobe interface
 123  * @link: false: get the list of global attributes; true: get the list of per-link attributes
 124  * @list: linked list to store the attributes in
 125  * @addr: buffer to store the interface's mac address in (optional)
 126  *
 127  * attributes must be freed by the caller
 128  */
 129 extern int wprobe_dump_attributes(const char *ifname, bool link, struct list_head *list, char *addr);
 130
 131 /**
 132  * wprobe_request_data: request new sampling values for the given list of attributes
 133  * @ifname: name of the wprobe interface
 134  * @attrs: attribute list
 135  * @addr: (optional) mac address of the link partner
 136  * @scale: scale down values by a factor (scale < 0: reset statistics entirely)
 137  *
 138  * if addr is unset, attrs must point to the list of global attributes,
 139  * if addr is set, attrs must point to the list of per-link attributes
 140  */
 141 extern int wprobe_request_data(const char *ifname, struct list_head *attrs, const unsigned char *addr, int scale);
 142
 143 #endif