1 #ifndef BABELTRACE_CTF_IR_TRACE_H
2 #define BABELTRACE_CTF_IR_TRACE_H
5 * BabelTrace - CTF IR: Trace
7 * Copyright 2014 Jérémie Galarneau <jeremie.galarneau@efficios.com>
9 * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
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:
18 * The above copyright notice and this permission notice shall be included in
19 * all copies or substantial portions of the Software.
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
29 * The Common Trace Format (CTF) Specification is available at
30 * http://www.efficios.com/ctf
33 #include <babeltrace/ctf-ir/event-types.h>
42 struct bt_ctf_stream_class
;
45 enum bt_environment_field_type
{
46 BT_ENVIRONMENT_FIELD_TYPE_UNKNOWN
= -1,
47 BT_ENVIRONMENT_FIELD_TYPE_STRING
= 0,
48 BT_ENVIRONMENT_FIELD_TYPE_INTEGER
= 1,
52 * bt_ctf_trace_create: create a trace instance.
54 * Allocate a new trace.
56 * A trace's default packet header is a structure initialized with the following
60 * - uint32_t stream_id
62 * Returns a new trace on success, NULL on error.
64 extern struct bt_ctf_trace
*bt_ctf_trace_create(void);
67 * bt_ctf_trace_create_stream: create a stream instance.
69 * Allocate a new stream instance and register it to the trace. The creation of
70 * a stream sets its reference count to 1.
72 * @param trace Trace instance.
73 * @param stream_class Stream class to instantiate.
75 * Returns a new stream on success, NULL on error.
77 extern struct bt_ctf_stream
*bt_ctf_trace_create_stream(
78 struct bt_ctf_trace
*trace
,
79 struct bt_ctf_stream_class
*stream_class
);
82 * bt_ctf_trace_add_environment_field: add a string environment field to the
85 * Add a string environment field to the trace. The name and value parameters
88 * @param trace Trace instance.
89 * @param name Name of the environment field (will be copied).
90 * @param value Value of the environment field (will be copied).
92 * Returns 0 on success, a negative value on error.
94 extern int bt_ctf_trace_add_environment_field(struct bt_ctf_trace
*trace
,
99 * bt_ctf_trace_add_environment_field_integer: add an integer environment
100 * field to the trace.
102 * Add an integer environment field to the trace. The name parameter is
105 * @param trace Trace instance.
106 * @param name Name of the environment field (will be copied).
107 * @param value Value of the environment field.
109 * Returns 0 on success, a negative value on error.
111 extern int bt_ctf_trace_add_environment_field_integer(
112 struct bt_ctf_trace
*trace
, const char *name
,
116 * bt_ctf_trace_get_environment_field_count: get environment field count.
118 * Get the trace's environment field count.
120 * @param trace Trace instance.
122 * Returns the environment field count, a negative value on error.
124 extern int bt_ctf_trace_get_environment_field_count(
125 struct bt_ctf_trace
*trace
);
128 * bt_ctf_trace_get_environment_field_type: get environment field type.
130 * Get an environment field's type.
132 * @param trace Trace instance.
133 * @param index Index of the environment field.
135 * Returns the environment field count, a negative value on error.
137 extern enum bt_environment_field_type
138 bt_ctf_trace_get_environment_field_type(struct bt_ctf_trace
*trace
,
142 * bt_ctf_trace_get_environment_field_name: get environment field name.
144 * Get an environment field's name. The string's ownership is not
145 * transferred to the caller.
147 * @param trace Trace instance.
148 * @param index Index of the environment field.
150 * Returns the environment field's name, NULL on error.
153 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace
*trace
,
157 * bt_ctf_trace_get_environment_field_value_string: get environment field
160 * Get an environment field's string value. The string's ownership is not
161 * transferred to the caller.
163 * @param trace Trace instance.
164 * @param index Index of the environment field.
166 * Returns the environment field's string value, NULL on error.
169 bt_ctf_trace_get_environment_field_value_string(struct bt_ctf_trace
*trace
,
173 * bt_ctf_trace_get_environment_field_value_integer: get environment field
176 * Get an environment field's integer value.
178 * @param trace Trace instance.
179 * @param index Index of the environment field.
181 * Returns the environment field's integer value, a negative value on error.
184 bt_ctf_trace_get_environment_field_value_integer(struct bt_ctf_trace
*trace
,
185 int index
, int64_t *value
);
188 * bt_ctf_trace_add_clock: add a clock to the trace.
190 * Add a clock to the trace. Clocks assigned to stream classes must be
191 * added to the trace beforehand.
193 * @param trace Trace instance.
194 * @param clock Clock to add to the trace.
196 * Returns 0 on success, a negative value on error.
198 extern int bt_ctf_trace_add_clock(struct bt_ctf_trace
*trace
,
199 struct bt_ctf_clock
*clock
);
202 * bt_ctf_trace_get_clock_count: get the number of clocks
203 * associated with the trace.
205 * @param trace Trace instance.
207 * Returns the clock count on success, a negative value on error.
209 extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace
*trace
);
212 * bt_ctf_trace_get_clock: get a trace's clock at index.
214 * @param trace Trace instance.
215 * @param index Index of the clock in the given trace.
217 * Return a clock instance on success, NULL on error.
219 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock(
220 struct bt_ctf_trace
*trace
, int index
);
223 * bt_ctf_trace_add_stream_class: add a stream_class to the trace.
225 * Add a stream class to the trace.
227 * @param trace Trace instance.
228 * @param stream_class Stream class to add to the trace.
230 * Returns 0 on success, a negative value on error.
232 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace
*trace
,
233 struct bt_ctf_stream_class
*stream_class
);
236 * bt_ctf_trace_get_stream_class_count: get the number of stream classes
237 * associated with the trace.
239 * @param trace Trace instance.
241 * Returns the stream class count on success, a negative value on error.
243 extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace
*trace
);
246 * bt_ctf_trace_get_stream_class: get a trace's stream class at index.
248 * @param trace Trace instance.
249 * @param index Index of the stream class in the given trace.
251 * Return a stream class on success, NULL on error.
253 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class(
254 struct bt_ctf_trace
*trace
, int index
);
257 * bt_ctf_trace_get_clock_by_name: get a trace's clock by name
259 * @param trace Trace instance.
260 * @param name Name of the clock in the given trace.
262 * Return a clock instance on success, NULL on error.
264 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock_by_name(
265 struct bt_ctf_trace
*trace
, const char *name
);
268 * bt_ctf_trace_get_metadata_string: get metadata string.
270 * Get the trace's TSDL metadata. The caller assumes the ownership of the
273 * @param trace Trace instance.
275 * Returns the metadata string on success, NULL on error.
277 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace
*trace
);
280 * bt_ctf_trace_get_byte_order: get a trace's byte order.
282 * Get the trace's byte order.
284 * @param trace Trace instance.
286 * Returns the trace's endianness, BT_CTF_BYTE_ORDER_UNKNOWN on error.
288 extern enum bt_ctf_byte_order
bt_ctf_trace_get_byte_order(
289 struct bt_ctf_trace
*trace
);
292 * bt_ctf_trace_set_byte_order: set a trace's byte order.
294 * Set the trace's byte order. Defaults to the current host's endianness.
296 * @param trace Trace instance.
297 * @param byte_order Trace's byte order.
299 * Returns 0 on success, a negative value on error.
301 * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
302 * to the CTF specification, is defined as "the byte order described in the
303 * trace description".
305 extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace
*trace
,
306 enum bt_ctf_byte_order byte_order
);
309 * bt_ctf_trace_get_packet_header_type: get a trace's packet header type.
311 * Get the trace's packet header type.
313 * @param trace Trace instance.
315 * Returns the trace's packet header type (a structure) on success, NULL on
318 extern struct bt_ctf_field_type
*bt_ctf_trace_get_packet_header_type(
319 struct bt_ctf_trace
*trace
);
322 * bt_ctf_trace_set_packet_header_type: set a trace's packet header type.
324 * Set the trace's packet header type.
326 * @param trace Trace instance.
327 * @param packet_header_type Packet header field type (must be a structure).
329 * Returns 0 on success, a negative value on error.
331 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace
*trace
,
332 struct bt_ctf_field_type
*packet_header_type
);
335 * bt_ctf_trace_get and bt_ctf_trace_put: increment and decrement the
336 * trace's reference count.
338 * These functions ensure that the trace won't be destroyed while it
339 * is in use. The same number of get and put (plus one extra put to
340 * release the initial reference done at creation) have to be done to
343 * When the trace's reference count is decremented to 0 by a
344 * bt_ctf_trace_put, the trace is freed.
346 * @param trace Trace instance.
348 extern void bt_ctf_trace_get(struct bt_ctf_trace
*trace
);
349 extern void bt_ctf_trace_put(struct bt_ctf_trace
*trace
);
355 #endif /* BABELTRACE_CTF_IR_TRACE_H */