[dragonfly.git] / lib / libevtr / evtr.h

/*
 * Copyright (c) 2009, 2010 Aggelos Economopoulos.  All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 * 3. Neither the name of The DragonFly Project nor the names of its
 *    contributors may be used to endorse or promote products derived
 *    from this software without specific, prior written permission.
 * 
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
 * COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
 * INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
 * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 */

#ifndef EVTR_H
#define EVTR_H

#include <stdint.h>
#include <stdio.h>
/* XXX: remove */
#include <sys/tree.h>

enum {
	EVTR_TYPE_PAD = 0x0,
	EVTR_TYPE_PROBE = 0x1,
	EVTR_TYPE_STR = 0x2,
	EVTR_TYPE_FMT = 0x3,
	EVTR_TYPE_SYSINFO = 0x4,
	EVTR_TYPE_CPUINFO = 0x5,
};

struct evtr_thread {
	RB_ENTRY(evtr_thread) rb_node;
	void *id;
	const char *comm;
	/* available for the user of the library, NULL if not set */
	void *userdata;
};

/*
 * This structure is used for interchange of data with
 * the user of the library
 */
typedef struct evtr_event {
	uint8_t type;
	union {
		/* timestamp. Must be nondecreasing */
		uint64_t ts;
		uint16_t ncpus;	/* EVTR_TYPE_SYSINFO */
		struct evtr_cpuinfo { /* EVTR_TYPE_CPUINFO */
			double freq;
		} cpuinfo;
	};
	/*
	 * Pointer to filename. NULL if n/a.
	 * For an event returned by the library,
	 * it is a pointer to storage allocated
	 * by the library that will be around
	 * until the call to evtr_close.
	 */
	const char *file;
	/* Same as above */ 
	const char *func;
	/* line number. 0 if n/a */
	uint16_t line;
	/*
	 * Format string, also used to identify
	 * the event. Ownership rules are the same
	 * as for file.
	 */
	const char *fmt;
	/*
	 * Data corresponding to the format string.
	 * For an event returned by the library,
	 * it is a pointer to an internal buffer
	 * that becomes invalid when the next record
	 * is returned. If the user wants to keep this
	 * data around, they must copy it.
	 */
	const void *fmtdata;
	/* Length of fmtdata */
	int fmtdatalen;
	/* Cpu on which the event occured */
	uint8_t cpu;
	/*
	 * Thread, which generated the event (if applicable). The
	 * storage pointed to belongs to the library and may (even
	 * though it's highly unlikely) point to a different thread
	 * in the future. The user needs to copy it if they want
	 * this data.
	 */
	struct evtr_thread *td;
} *evtr_event_t;

/*
 * Specifies which conditions to filter query results
 * with. It is modified by the library and should
 * not be touched after initialization.
 */
typedef struct evtr_filter {
	int flags;	/* must be initialized to 0 */
	/*
	 * Which cpu we are interested in. -1 means
	 * any cpu. XXX: use mask? (note we could just
	 * do that internally)
	 */
	int cpu;
	/*
	 * If the user sets fmt, only events with a format
	 * string identical to the one specified will be
	 * returned. This field is modified by the library.
	 */
	union {
		const char *fmt;
		int fmtid;
	};
} *evtr_filter_t;

struct evtr_query;
struct evtr;
typedef struct evtr *evtr_t;

int evtr_next_event(evtr_t, evtr_event_t);
evtr_t evtr_open_read(FILE *);
evtr_t evtr_open_write(FILE *);
void evtr_close(evtr_t);
int evtr_dump_event(evtr_t, evtr_event_t);
int evtr_error(evtr_t);
const char * evtr_errmsg(evtr_t);
void evtr_event_data(evtr_event_t, char *, size_t);
struct evtr_query * evtr_query_init(evtr_t, evtr_filter_t, int);
void evtr_query_destroy(struct evtr_query *);
int evtr_query_next(struct evtr_query *, evtr_event_t);
int evtr_last_event(evtr_t, evtr_event_t);
int evtr_rewind(evtr_t);

int evtr_ncpus(evtr_t);
int evtr_cpufreqs(evtr_t, double *);
void evtr_set_debug(int);


#endif	/* EVTR_H */
Commit	Line	Data
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
	40	enum {
	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,
956f9b36 AE	46	EVTR_TYPE_CPUINFO = 0x5,
e7c0dbba AE	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;
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	*/
	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);
956f9b36	155	int evtr_cpufreqs(evtr_t, double *);
e7c0dbba AE	156	void evtr_set_debug(int);
	157
	158
	159	#endif /* EVTR_H */