evtr: dump core frequencies and use them to print timestamps in usecs
[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_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(int);
157
158
159 #endif  /* EVTR_H */