lib/libevtr/evtr.h

   1 /*
   2  * Copyright (c) 2009, 2010 Aggelos Economopoulos.  All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in
  12  *    the documentation and/or other materials provided with the
  13  *    distribution.
  14  * 3. Neither the name of The DragonFly Project nor the names of its
  15  *    contributors may be used to endorse or promote products derived
  16  *    from this software without specific, prior written permission.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19  * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21  * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22  * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23  * INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24  * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29  * SUCH DAMAGE.
  30  */
  31
  32 #ifndef EVTR_H
  33 #define EVTR_H
  34
  35 #include <stdint.h>
  36 #include <stdio.h>
  37 #include <sys/queue.h>
  38 /* XXX: remove */
  39 #include <sys/tree.h>
  40
  41 enum {
  42         EVTR_TYPE_PAD = 0x0,
  43         EVTR_TYPE_PROBE = 0x1,
  44         EVTR_TYPE_STR = 0x2,
  45         EVTR_TYPE_FMT = 0x3,
  46         EVTR_TYPE_SYSINFO = 0x4,
  47         EVTR_TYPE_CPUINFO = 0x5,
  48         EVTR_TYPE_STMT = 0x6,
  49 };
  50
  51 struct hashtab;
  52 typedef struct evtr_variable_value {
  53         enum evtr_value_type {
  54                 EVTR_VAL_NIL,
  55                 EVTR_VAL_INT,
  56                 EVTR_VAL_STR,
  57                 EVTR_VAL_HASH,
  58                 EVTR_VAL_CTOR,
  59         } type;
  60         union {
  61                 uintmax_t num;
  62                 const char *str;
  63                 struct hashtab *hashtab;
  64                 const struct symtab *symtab;
  65                 struct {
  66                         const char *name;
  67                         TAILQ_HEAD(, evtr_variable_value) args;
  68                 } ctor;
  69         };
  70         TAILQ_ENTRY(evtr_variable_value) link;
  71 } *evtr_variable_value_t;
  72
  73 typedef struct evtr_variable {
  74         const char *name;
  75         struct evtr_variable_value val;
  76 } *evtr_var_t;
  77
  78 struct evtr_thread {
  79         RB_ENTRY(evtr_thread) rb_node;
  80         void *id;
  81         const char *comm;
  82         /* available for the user of the library, NULL if not set */
  83         void *userdata;
  84 };
  85
  86 /*
  87  * This structure is used for interchange of data with
  88  * the user of the library
  89  */
  90 typedef struct evtr_event {
  91         uint8_t type;   /* EVTR_TYPE_* */
  92         uint64_t ts;    /* timestamp. Must be nondecreasing */
  93         union {
  94                 uint16_t ncpus; /* EVTR_TYPE_SYSINFO */
  95                 struct evtr_cpuinfo { /* EVTR_TYPE_CPUINFO */
  96                         double freq;
  97                 } cpuinfo;
  98                 struct evtr_stmt {
  99                         const struct evtr_variable *var;
 100                         enum evtr_op {
 101                                 EVTR_OP_SET,
 102                         } op;
 103                         struct evtr_variable_value *val;
 104                 } stmt;
 105         };
 106         /*
 107          * Pointer to filename. NULL if n/a.
 108          * For an event returned by the library,
 109          * it is a pointer to storage allocated
 110          * by the library that will be around
 111          * until the call to evtr_close.
 112          */
 113         const char *file;
 114         /* Same as above */
 115         const char *func;
 116         /* line number. 0 if n/a */
 117         uint16_t line;
 118         /*
 119          * Format string, also used to identify
 120          * the event. Ownership rules are the same
 121          * as for file.
 122          */
 123         const char *fmt;
 124         /*
 125          * Data corresponding to the format string.
 126          * For an event returned by the library,
 127          * it is a pointer to an internal buffer
 128          * that becomes invalid when the next record
 129          * is returned. If the user wants to keep this
 130          * data around, they must copy it.
 131          */
 132         const void *fmtdata;
 133         /* Length of fmtdata */
 134         int fmtdatalen;
 135         /* Cpu on which the event occured */
 136         uint8_t cpu;
 137         /*
 138          * Thread, which generated the event (if applicable). The
 139          * storage pointed to belongs to the library and may (even
 140          * though it's highly unlikely) point to a different thread
 141          * in the future. The user needs to copy it if they want
 142          * this data.
 143          */
 144         struct evtr_thread *td;
 145 } *evtr_event_t;
 146
 147 /*
 148  * Specifies which conditions to filter query results
 149  * with. It is modified by the library and should
 150  * not be touched after initialization.
 151  */
 152 typedef struct evtr_filter {
 153         int flags;      /* must be initialized to 0 */
 154         /*
 155          * Which cpu we are interested in. -1 means
 156          * any cpu. XXX: use mask? (note we could just
 157          * do that internally)
 158          */
 159         int cpu;
 160         /* what event type we're interested in */
 161         int ev_type;
 162         /*
 163          * If the user sets fmt, only events with a format
 164          * string identical to the one specified will be
 165          * returned. This field is modified by the library.
 166          */
 167         union {
 168                 const char *fmt;
 169                 int fmtid;
 170                 const char *var;
 171         };
 172 } *evtr_filter_t;
 173
 174 struct evtr_query;
 175 struct evtr;
 176 typedef struct evtr *evtr_t;
 177 typedef struct evtr_query *evtr_query_t;
 178
 179 evtr_t evtr_open_read(FILE *);
 180 evtr_t evtr_open_write(FILE *);
 181 void evtr_close(evtr_t);
 182 int evtr_dump_event(evtr_t, evtr_event_t);
 183 int evtr_error(evtr_t);
 184 const char * evtr_errmsg(evtr_t);
 185 int evtr_query_error(evtr_query_t);
 186 const char * evtr_query_errmsg(evtr_query_t);
 187 void evtr_event_data(evtr_event_t, char *, size_t);
 188 struct evtr_query * evtr_query_init(evtr_t, evtr_filter_t, int);
 189 void evtr_query_destroy(struct evtr_query *);
 190 int evtr_query_next(struct evtr_query *, evtr_event_t);
 191 int evtr_last_event(evtr_t, evtr_event_t);
 192 int evtr_rewind(evtr_t);
 193
 194 int evtr_ncpus(evtr_t);
 195 int evtr_cpufreqs(evtr_t, double *);
 196 void evtr_set_debug(const char *);
 197
 198
 199 #endif  /* EVTR_H */