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