evtr: dump core frequencies and use them to print timestamps in usecs
[dragonfly.git] / lib / libevtr / evtr.h
CommitLineData
e7c0dbba
AE
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
40enum {
41 EVTR_TYPE_PAD = 0x0,
42 EVTR_TYPE_PROBE = 0x1,
43 EVTR_TYPE_STR = 0x2,
44 EVTR_TYPE_FMT = 0x3,
956f9b36
AE
45 EVTR_TYPE_SYSINFO = 0x4,
46 EVTR_TYPE_CPUINFO = 0x5,
e7c0dbba
AE
47};
48
49struct 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 */
61typedef struct evtr_event {
62 uint8_t type;
63 union {
64 /* timestamp. Must be nondecreasing */
65 uint64_t ts;
956f9b36
AE
66 uint16_t ncpus; /* EVTR_TYPE_SYSINFO */
67 struct evtr_cpuinfo { /* EVTR_TYPE_CPUINFO */
68 double freq;
69 } cpuinfo;
e7c0dbba
AE
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 */
117typedef 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
136struct evtr_query;
137struct evtr;
138typedef struct evtr *evtr_t;
139
140int evtr_next_event(evtr_t, evtr_event_t);
141evtr_t evtr_open_read(FILE *);
142evtr_t evtr_open_write(FILE *);
143void evtr_close(evtr_t);
144int evtr_dump_event(evtr_t, evtr_event_t);
145int evtr_error(evtr_t);
146const char * evtr_errmsg(evtr_t);
147void evtr_event_data(evtr_event_t, char *, size_t);
148struct evtr_query * evtr_query_init(evtr_t, evtr_filter_t, int);
149void evtr_query_destroy(struct evtr_query *);
150int evtr_query_next(struct evtr_query *, evtr_event_t);
151int evtr_last_event(evtr_t, evtr_event_t);
152int evtr_rewind(evtr_t);
153
154int evtr_ncpus(evtr_t);
956f9b36 155int evtr_cpufreqs(evtr_t, double *);
e7c0dbba
AE
156void evtr_set_debug(int);
157
158
159#endif /* EVTR_H */