cefa9c23fef1eb377793f70099ad9007b65f2ee0
[dragonfly.git] / 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 */