[babeltrace.git] / include / babeltrace / ctf-ir / trace.h

#ifndef BABELTRACE_CTF_IR_TRACE_H
#define BABELTRACE_CTF_IR_TRACE_H

/*
 * BabelTrace - CTF IR: Trace
 *
 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 *
 * The Common Trace Format (CTF) Specification is available at
 * http://www.efficios.com/ctf
 */

#include <babeltrace/ctf-ir/event-types.h>

#ifdef __cplusplus
extern "C" {
#endif

struct bt_ctf_trace;
struct bt_ctf_stream;
struct bt_ctf_stream_class;
struct bt_ctf_clock;

enum bt_environment_field_type {
	BT_ENVIRONMENT_FIELD_TYPE_UNKNOWN = -1,
	BT_ENVIRONMENT_FIELD_TYPE_STRING = 0,
	BT_ENVIRONMENT_FIELD_TYPE_INTEGER = 1,
};

/*
 * bt_ctf_trace_create: create a trace instance.
 *
 * Allocate a new trace.
 *
 * A trace's default packet header is a structure initialized with the following
 * fields:
 *	- uint32_t magic
 *	- uint8_t  uuid[16]
 *	- uint32_t stream_id
 *
 * Returns a new trace on success, NULL on error.
 */
extern struct bt_ctf_trace *bt_ctf_trace_create(void);

/*
 * bt_ctf_trace_create_stream: create a stream instance.
 *
 * Allocate a new stream instance and register it to the trace. The creation of
 * a stream sets its reference count to 1.
 *
 * @param trace Trace instance.
 * @param stream_class Stream class to instantiate.
 *
 * Returns a new stream on success, NULL on error.
 */
extern struct bt_ctf_stream *bt_ctf_trace_create_stream(
		struct bt_ctf_trace *trace,
		struct bt_ctf_stream_class *stream_class);

/*
 * bt_ctf_trace_add_environment_field: add a string environment field to the
 *	trace.
 *
 * Add a string environment field to the trace. The name and value parameters
 * are copied.
 *
 * @param trace Trace instance.
 * @param name Name of the environment field (will be copied).
 * @param value Value of the environment field (will be copied).
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace,
		const char *name,
		const char *value);

/*
 * bt_ctf_trace_add_environment_field_integer: add an integer environment
 *	field to the trace.
 *
 * Add an integer environment field to the trace. The name parameter is
 * copied.
 *
 * @param trace Trace instance.
 * @param name Name of the environment field (will be copied).
 * @param value Value of the environment field.
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_add_environment_field_integer(
		struct bt_ctf_trace *trace, const char *name,
		int64_t value);

/*
 * bt_ctf_trace_add_clock: add a clock to the trace.
 *
 * Add a clock to the trace. Clocks assigned to stream classes must be
 * added to the trace beforehand.
 *
 * @param trace Trace instance.
 * @param clock Clock to add to the trace.
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace,
		struct bt_ctf_clock *clock);

/*
 * bt_ctf_trace_get_clock_count: get the number of clocks
 *	associated to the trace.
 *
 * @param trace Trace instance.
 *
 * Returns the clock count on success, a negative value on error.
 */
extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace);

/*
 * bt_ctf_trace_get_clock: get a trace's clock at index.
 *
 * @param trace Trace instance.
 * @param index Index of the clock in the given trace.
 *
 * Return a clock instance on success, NULL on error.
 */
extern struct bt_ctf_clock *bt_ctf_trace_get_clock(
		struct bt_ctf_trace *trace, int index);

/*
 * bt_ctf_trace_get_metadata_string: get metadata string.
 *
 * Get the trace's TSDL metadata. The caller assumes the ownership of the
 * returned string.
 *
 * @param trace Trace instance.
 *
 * Returns the metadata string on success, NULL on error.
 */
extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace *trace);

/*
 * bt_ctf_trace_set_byte_order: set a field type's byte order.
 *
 * Set the trace's byte order. Defaults to the current host's endianness.
 *
 * @param trace Trace instance.
 * @param byte_order Trace's byte order.
 *
 * Returns 0 on success, a negative value on error.
 *
 * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
 * to the CTF specification, is defined as "the byte order described in the
 * trace description".
 */
extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace,
		enum bt_ctf_byte_order byte_order);

/*
 * bt_ctf_trace_get_packet_header_type: get a trace's packet header type.
 *
 * Get the trace's packet header type.
 *
 * @param trace Trace instance.
 *
 * Returns the trace's packet header type (a structure) on success, NULL on
 * 	error.
 */
extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type(
		struct bt_ctf_trace *trace);

/*
 * bt_ctf_trace_set_packet_header_type: set a trace's packet header type.
 *
 * Set the trace's packet header type.
 *
 * @param trace Trace instance.
 * @param packet_header_type Packet header field type (must be a structure).
 *
 * Returns 0 on success, a negative value on error.
 */
extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace,
		struct bt_ctf_field_type *packet_header_type);

/*
 * bt_ctf_trace_get and bt_ctf_trace_put: increment and decrement the
 * trace's reference count.
 *
 * These functions ensure that the trace won't be destroyed while it
 * is in use. The same number of get and put (plus one extra put to
 * release the initial reference done at creation) have to be done to
 * destroy a trace.
 *
 * When the trace's reference count is decremented to 0 by a
 * bt_ctf_trace_put, the trace is freed.
 *
 * @param trace Trace instance.
 */
extern void bt_ctf_trace_get(struct bt_ctf_trace *trace);
extern void bt_ctf_trace_put(struct bt_ctf_trace *trace);

#ifdef __cplusplus
}
#endif

#endif /* BABELTRACE_CTF_IR_TRACE_H */
Commit	Line	Data
bc37ae52 JG	1	#ifndef BABELTRACE_CTF_IR_TRACE_H
	2	#define BABELTRACE_CTF_IR_TRACE_H
	3
	4	/*
	5	* BabelTrace - CTF IR: Trace
	6	*
	7	* Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	8	*
	9	* Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
	10	*
	11	* Permission is hereby granted, free of charge, to any person obtaining a copy
	12	* of this software and associated documentation files (the "Software"), to deal
	13	* in the Software without restriction, including without limitation the rights
	14	* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
	15	* copies of the Software, and to permit persons to whom the Software is
	16	* furnished to do so, subject to the following conditions:
	17	*
	18	* The above copyright notice and this permission notice shall be included in
	19	* all copies or substantial portions of the Software.
	20	*
	21	* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
	22	* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
	23	* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
	24	* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
	25	* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
	26	* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
	27	* SOFTWARE.
	28	*
	29	* The Common Trace Format (CTF) Specification is available at
	30	* http://www.efficios.com/ctf
	31	*/
	32
	33	#include <babeltrace/ctf-ir/event-types.h>
	34
	35	#ifdef __cplusplus
	36	extern "C" {
	37	#endif
	38
	39	struct bt_ctf_trace;
	40	struct bt_ctf_stream;
	41	struct bt_ctf_stream_class;
	42	struct bt_ctf_clock;
	43
3487c9f3 JG	44	enum bt_environment_field_type {
	45	BT_ENVIRONMENT_FIELD_TYPE_UNKNOWN = -1,
	46	BT_ENVIRONMENT_FIELD_TYPE_STRING = 0,
	47	BT_ENVIRONMENT_FIELD_TYPE_INTEGER = 1,
	48	};
	49
bc37ae52 JG	50	/*
	51	* bt_ctf_trace_create: create a trace instance.
	52	*
d246b111 JG	53	* Allocate a new trace.
	54	*
	55	* A trace's default packet header is a structure initialized with the following
	56	* fields:
	57	* - uint32_t magic
	58	* - uint8_t uuid[16]
	59	* - uint32_t stream_id
bc37ae52 JG	60	*
	61	* Returns a new trace on success, NULL on error.
	62	*/
	63	extern struct bt_ctf_trace *bt_ctf_trace_create(void);
	64
	65	/*
	66	* bt_ctf_trace_create_stream: create a stream instance.
	67	*
	68	* Allocate a new stream instance and register it to the trace. The creation of
	69	* a stream sets its reference count to 1.
	70	*
	71	* @param trace Trace instance.
	72	* @param stream_class Stream class to instantiate.
	73	*
	74	* Returns a new stream on success, NULL on error.
	75	*/
	76	extern struct bt_ctf_stream *bt_ctf_trace_create_stream(
	77	struct bt_ctf_trace *trace,
	78	struct bt_ctf_stream_class *stream_class);
	79
	80	/*
3487c9f3 JG	81	* bt_ctf_trace_add_environment_field: add a string environment field to the
3487c9f3 JG	82	* trace.
bc37ae52	83	*
3487c9f3 JG	84	* Add a string environment field to the trace. The name and value parameters
3487c9f3 JG	85	* are copied.
bc37ae52 JG	86	*
	87	* @param trace Trace instance.
	88	* @param name Name of the environment field (will be copied).
	89	* @param value Value of the environment field (will be copied).
	90	*
	91	* Returns 0 on success, a negative value on error.
	92	*/
	93	extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace *trace,
	94	const char *name,
	95	const char *value);
	96
3487c9f3 JG	97	/*
	98	* bt_ctf_trace_add_environment_field_integer: add an integer environment
	99	* field to the trace.
	100	*
	101	* Add an integer environment field to the trace. The name parameter is
	102	* copied.
	103	*
	104	* @param trace Trace instance.
	105	* @param name Name of the environment field (will be copied).
	106	* @param value Value of the environment field.
	107	*
	108	* Returns 0 on success, a negative value on error.
	109	*/
	110	extern int bt_ctf_trace_add_environment_field_integer(
	111	struct bt_ctf_trace trace, const char name,
	112	int64_t value);
	113
bc37ae52 JG	114	/*
	115	* bt_ctf_trace_add_clock: add a clock to the trace.
	116	*
	117	* Add a clock to the trace. Clocks assigned to stream classes must be
	118	* added to the trace beforehand.
	119	*
	120	* @param trace Trace instance.
	121	* @param clock Clock to add to the trace.
	122	*
	123	* Returns 0 on success, a negative value on error.
	124	*/
	125	extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace,
	126	struct bt_ctf_clock *clock);
	127
884cd6c3 JG	128	/*
	129	* bt_ctf_trace_get_clock_count: get the number of clocks
	130	* associated to the trace.
	131	*
	132	* @param trace Trace instance.
	133	*
	134	* Returns the clock count on success, a negative value on error.
	135	*/
	136	extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace);
	137
	138	/*
	139	* bt_ctf_trace_get_clock: get a trace's clock at index.
	140	*
	141	* @param trace Trace instance.
	142	* @param index Index of the clock in the given trace.
	143	*
	144	* Return a clock instance on success, NULL on error.
	145	*/
	146	extern struct bt_ctf_clock *bt_ctf_trace_get_clock(
	147	struct bt_ctf_trace *trace, int index);
	148
bc37ae52 JG	149	/*
	150	* bt_ctf_trace_get_metadata_string: get metadata string.
	151	*
	152	* Get the trace's TSDL metadata. The caller assumes the ownership of the
	153	* returned string.
	154	*
	155	* @param trace Trace instance.
	156	*
	157	* Returns the metadata string on success, NULL on error.
	158	*/
	159	extern char bt_ctf_trace_get_metadata_string(struct bt_ctf_trace trace);
	160
	161	/*
	162	* bt_ctf_trace_set_byte_order: set a field type's byte order.
	163	*
c35a1669	164	* Set the trace's byte order. Defaults to the current host's endianness.
bc37ae52 JG	165	*
	166	* @param trace Trace instance.
	167	* @param byte_order Trace's byte order.
	168	*
	169	* Returns 0 on success, a negative value on error.
c35a1669 JG	170	*
	171	* Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
	172	* to the CTF specification, is defined as "the byte order described in the
	173	* trace description".
bc37ae52 JG	174	*/
	175	extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace,
	176	enum bt_ctf_byte_order byte_order);
	177
d246b111 JG	178	/*
	179	* bt_ctf_trace_get_packet_header_type: get a trace's packet header type.
	180	*
	181	* Get the trace's packet header type.
	182	*
	183	* @param trace Trace instance.
	184	*
	185	* Returns the trace's packet header type (a structure) on success, NULL on
	186	* error.
	187	*/
	188	extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type(
	189	struct bt_ctf_trace *trace);
	190
	191	/*
	192	* bt_ctf_trace_set_packet_header_type: set a trace's packet header type.
	193	*
	194	* Set the trace's packet header type.
	195	*
	196	* @param trace Trace instance.
	197	* @param packet_header_type Packet header field type (must be a structure).
	198	*
	199	* Returns 0 on success, a negative value on error.
	200	*/
	201	extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace,
	202	struct bt_ctf_field_type *packet_header_type);
	203
bc37ae52 JG	204	/*
	205	* bt_ctf_trace_get and bt_ctf_trace_put: increment and decrement the
	206	* trace's reference count.
	207	*
	208	* These functions ensure that the trace won't be destroyed while it
	209	* is in use. The same number of get and put (plus one extra put to
	210	* release the initial reference done at creation) have to be done to
	211	* destroy a trace.
	212	*
	213	* When the trace's reference count is decremented to 0 by a
	214	* bt_ctf_trace_put, the trace is freed.
	215	*
	216	* @param trace Trace instance.
	217	*/
	218	extern void bt_ctf_trace_get(struct bt_ctf_trace *trace);
	219	extern void bt_ctf_trace_put(struct bt_ctf_trace *trace);
	220
	221	#ifdef __cplusplus
	222	}
	223	#endif
	224
	225	#endif /* BABELTRACE_CTF_IR_TRACE_H */