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 /* XXX: remove */
  38 #include <sys/tree.h>
  39
  40 enum {
  41         EVTR_TYPE_PAD = 0x0,
  42         EVTR_TYPE_PROBE = 0x1,
  43         EVTR_TYPE_STR = 0x2,
  44         EVTR_TYPE_FMT = 0x3,
  45         EVTR_TYPE_SYSINFO = 0x4,
  46         EVTR_TYPE_CPUINFO = 0x5,
  47 };
  48
  49 struct evtr_thread {
  50         RB_ENTRY(evtr_thread) rb_node;
  51         void *id;
  52         const char *comm;
  53         /* available for the user of the library, NULL if not set */
  54         void *userdata;
  55 };
  56
  57 /*
  58  * This structure is used for interchange of data with
  59  * the user of the library
  60  */
  61 typedef struct evtr_event {
  62         uint8_t type;
  63         union {
  64                 /* timestamp. Must be nondecreasing */
  65                 uint64_t ts;
  66                 uint16_t ncpus; /* EVTR_TYPE_SYSINFO */
  67                 struct evtr_cpuinfo { /* EVTR_TYPE_CPUINFO */
  68                         double freq;
  69                 } cpuinfo;
  70         };
  71         /*
  72          * Pointer to filename. NULL if n/a.
  73          * For an event returned by the library,
  74          * it is a pointer to storage allocated
  75          * by the library that will be around
  76          * until the call to evtr_close.
  77          */
  78         const char *file;
  79         /* Same as above */
  80         const char *func;
  81         /* line number. 0 if n/a */
  82         uint16_t line;
  83         /*
  84          * Format string, also used to identify
  85          * the event. Ownership rules are the same
  86          * as for file.
  87          */
  88         const char *fmt;
  89         /*
  90          * Data corresponding to the format string.
  91          * For an event returned by the library,
  92          * it is a pointer to an internal buffer
  93          * that becomes invalid when the next record
  94          * is returned. If the user wants to keep this
  95          * data around, they must copy it.
  96          */
  97         const void *fmtdata;
  98         /* Length of fmtdata */
  99         int fmtdatalen;
 100         /* Cpu on which the event occured */
 101         uint8_t cpu;
 102         /*
 103          * Thread, which generated the event (if applicable). The
 104          * storage pointed to belongs to the library and may (even
 105          * though it's highly unlikely) point to a different thread
 106          * in the future. The user needs to copy it if they want
 107          * this data.
 108          */
 109         struct evtr_thread *td;
 110 } *evtr_event_t;
 111
 112 /*
 113  * Specifies which conditions to filter query results
 114  * with. It is modified by the library and should
 115  * not be touched after initialization.
 116  */
 117 typedef struct evtr_filter {
 118         int flags;      /* must be initialized to 0 */
 119         /*
 120          * Which cpu we are interested in. -1 means
 121          * any cpu. XXX: use mask? (note we could just
 122          * do that internally)
 123          */
 124         int cpu;
 125         /*
 126          * If the user sets fmt, only events with a format
 127          * string identical to the one specified will be
 128          * returned. This field is modified by the library.
 129          */
 130         union {
 131                 const char *fmt;
 132                 int fmtid;
 133         };
 134 } *evtr_filter_t;
 135
 136 struct evtr_query;
 137 struct evtr;
 138 typedef struct evtr *evtr_t;
 139
 140 int evtr_next_event(evtr_t, evtr_event_t);
 141 evtr_t evtr_open_read(FILE *);
 142 evtr_t evtr_open_write(FILE *);
 143 void evtr_close(evtr_t);
 144 int evtr_dump_event(evtr_t, evtr_event_t);
 145 int evtr_error(evtr_t);
 146 const char * evtr_errmsg(evtr_t);
 147 void evtr_event_data(evtr_event_t, char *, size_t);
 148 struct evtr_query * evtr_query_init(evtr_t, evtr_filter_t, int);
 149 void evtr_query_destroy(struct evtr_query *);
 150 int evtr_query_next(struct evtr_query *, evtr_event_t);
 151 int evtr_last_event(evtr_t, evtr_event_t);
 152 int evtr_rewind(evtr_t);
 153
 154 int evtr_ncpus(evtr_t);
 155 int evtr_cpufreqs(evtr_t, double *);
 156 void evtr_set_debug(const char *);
 157
 158
 159 #endif  /* EVTR_H */