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/field-types.h>
34 #include <babeltrace/values.h>
43 struct bt_ctf_stream_class
;
47 * Notification handling function type.
49 * A reference must be taken on the notification if the handler has to
50 * keep ownership of the notification beyond the invocation of the callback.
52 * @param notification Notification to handle
53 * @param data Handler private data
55 typedef void (*bt_ctf_notification_cb
)(
56 struct bt_notification
*notification
, void *data
);
59 * bt_ctf_trace_create: create a trace instance.
61 * Allocate a new trace.
63 * A trace's default packet header is a structure initialized with the following
67 * - uint32_t stream_id
69 * Returns a new trace on success, NULL on error.
71 extern struct bt_ctf_trace
*bt_ctf_trace_create(void);
74 * bt_ctf_trace_set_environment_field: sets an environment field to the
77 * Sets an environment field to the trace. The name parameter is
78 * copied, whereas the value parameter's reference count is incremented
79 * (if the function succeeds).
81 * If a value exists in the environment for the specified name, it is
82 * replaced by the new value.
84 * The value parameter _must_ be either an integer value object or a
85 * string value object. Other object types are not supported.
87 * @param trace Trace instance.
88 * @param name Name of the environment field (will be copied).
89 * @param value Value of the environment field.
91 * Returns 0 on success, a negative value on error.
93 extern int bt_ctf_trace_set_environment_field(
94 struct bt_ctf_trace
*trace
, const char *name
,
95 struct bt_value
*value
);
98 * bt_ctf_trace_set_environment_field_string: sets a string environment
101 * Sets a string environment field to the trace. This is a helper
102 * function which corresponds to calling
103 * bt_ctf_trace_set_environment_field() with a string object.
105 * @param trace Trace instance.
106 * @param name Name of the environment field (will be copied).
107 * @param value Value of the environment field (will be copied).
109 * Returns 0 on success, a negative value on error.
111 extern int bt_ctf_trace_set_environment_field_string(
112 struct bt_ctf_trace
*trace
, const char *name
,
116 * bt_ctf_trace_set_environment_field_integer: sets an integer environment
117 * field to the trace.
119 * Sets an integer environment field to the trace. This is a helper
120 * function which corresponds to calling
121 * bt_ctf_trace_set_environment_field() with an integer object.
123 * @param trace Trace instance.
124 * @param name Name of the environment field (will be copied).
125 * @param value Value of the environment field.
127 * Returns 0 on success, a negative value on error.
129 extern int bt_ctf_trace_set_environment_field_integer(
130 struct bt_ctf_trace
*trace
, const char *name
,
134 * bt_ctf_trace_get_environment_field_count: get environment field count.
136 * Get the trace's environment field count.
138 * @param trace Trace instance.
140 * Returns the environment field count, a negative value on error.
142 extern int bt_ctf_trace_get_environment_field_count(
143 struct bt_ctf_trace
*trace
);
146 * bt_ctf_trace_get_environment_field_name: get environment field name.
148 * Get an environment field's name. The string's ownership is not
149 * transferred to the caller. The string data is valid as long as
150 * this trace's environment is not modified.
152 * @param trace Trace instance.
153 * @param index Index of the environment field.
155 * Returns the environment field's name, NULL on error.
158 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace
*trace
,
162 * bt_ctf_trace_get_environment_field_value: get environment
163 * field value (an object).
165 * Get an environment field's value (an object). The returned object's
166 * reference count is incremented. When done with the object, the caller
167 * must call bt_value_put() on it.
169 * @param trace Trace instance.
170 * @param index Index of the environment field.
172 * Returns the environment field's object value, NULL on error.
174 extern struct bt_value
*
175 bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace
*trace
,
179 * bt_ctf_trace_get_environment_field_value_by_name: get environment
180 * field value (an object) by name.
182 * Get an environment field's value (an object) by its field name. The
183 * returned object's reference count is incremented. When done with the
184 * object, the caller must call bt_value_put() on it.
186 * @param trace Trace instance.
187 * @param name Environment field's name
189 * Returns the environment field's object value, NULL on error.
191 extern struct bt_value
*
192 bt_ctf_trace_get_environment_field_value_by_name(struct bt_ctf_trace
*trace
,
196 * bt_ctf_trace_add_clock: add a clock to the trace.
198 * Add a clock to the trace. Clocks assigned to stream classes must be
199 * added to the trace beforehand.
201 * @param trace Trace instance.
202 * @param clock Clock to add to the trace.
204 * Returns 0 on success, a negative value on error.
206 extern int bt_ctf_trace_add_clock(struct bt_ctf_trace
*trace
,
207 struct bt_ctf_clock
*clock
);
210 * bt_ctf_trace_get_clock_count: get the number of clocks
211 * associated with the trace.
213 * @param trace Trace instance.
215 * Returns the clock count on success, a negative value on error.
217 extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace
*trace
);
220 * bt_ctf_trace_get_clock: get a trace's clock at index.
222 * @param trace Trace instance.
223 * @param index Index of the clock in the given trace.
225 * Return a clock instance on success, NULL on error.
227 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock(
228 struct bt_ctf_trace
*trace
, int index
);
231 * bt_ctf_trace_add_stream_class: add a stream_class to the trace.
233 * Add a stream class to the trace.
235 * @param trace Trace instance.
236 * @param stream_class Stream class to add to the trace.
238 * Returns 0 on success, a negative value on error.
240 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace
*trace
,
241 struct bt_ctf_stream_class
*stream_class
);
244 * bt_ctf_trace_get_stream_class_count: get the number of stream classes
245 * associated with the trace.
247 * @param trace Trace instance.
249 * Returns the stream class count on success, a negative value on error.
251 extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace
*trace
);
254 * bt_ctf_trace_get_stream_class: get a trace's stream class at index.
256 * @param trace Trace instance.
257 * @param index Index of the stream class in the given trace.
259 * Return a stream class on success, NULL on error.
261 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class(
262 struct bt_ctf_trace
*trace
, int index
);
265 * bt_ctf_trace_get_stream_class_by_id: get a trace's stream class by ID.
267 * @param trace Trace instance.
268 * @param index ID of the stream class in the given trace.
270 * Return a stream class on success, NULL on error.
272 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_id(
273 struct bt_ctf_trace
*trace
, uint32_t id
);
276 * bt_ctf_trace_get_clock_by_name: get a trace's clock by name
278 * @param trace Trace instance.
279 * @param name Name of the clock in the given trace.
281 * Return a clock instance on success, NULL on error.
283 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock_by_name(
284 struct bt_ctf_trace
*trace
, const char *name
);
287 * bt_ctf_trace_get_metadata_string: get metadata string.
289 * Get the trace's TSDL metadata. The caller assumes the ownership of the
292 * @param trace Trace instance.
294 * Returns the metadata string on success, NULL on error.
296 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace
*trace
);
299 * bt_ctf_trace_get_byte_order: get a trace's byte order.
301 * Get the trace's byte order.
303 * @param trace Trace instance.
305 * Returns the trace's endianness, BT_CTF_BYTE_ORDER_UNKNOWN on error.
307 extern enum bt_ctf_byte_order
bt_ctf_trace_get_byte_order(
308 struct bt_ctf_trace
*trace
);
311 * bt_ctf_trace_set_byte_order: set a trace's byte order.
313 * Set the trace's byte order. Defaults to the current host's endianness.
315 * @param trace Trace instance.
316 * @param byte_order Trace's byte order.
318 * Returns 0 on success, a negative value on error.
320 * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
321 * to the CTF specification, is defined as "the byte order described in the
322 * trace description".
324 extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace
*trace
,
325 enum bt_ctf_byte_order byte_order
);
328 * bt_ctf_trace_get_packet_header_type: get a trace's packet header type.
330 * Get the trace's packet header type.
332 * @param trace Trace instance.
334 * Returns the trace's packet header type (a structure) on success, NULL on
337 extern struct bt_ctf_field_type
*bt_ctf_trace_get_packet_header_type(
338 struct bt_ctf_trace
*trace
);
341 * bt_ctf_trace_set_packet_header_type: set a trace's packet header type.
343 * Set the trace's packet header type.
345 * @param trace Trace instance.
346 * @param packet_header_type Packet header field type (must be a structure).
348 * Returns 0 on success, a negative value on error.
350 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace
*trace
,
351 struct bt_ctf_field_type
*packet_header_type
);
354 * bt_ctf_trace_add_notification_handler_cb: set a notification callback
355 * which will be invoked whenever a trace's schema is modified.
357 * Register a notification handler to a trace.
359 * @param trace Trace instance.
360 * @param handler Notification handler to invoke on trace xmodification.
361 * @param handler_data Private data passed to the notification handler.
363 * Returns 0 on success, a negative value on error.
365 * Note: the notification handler will be used to serialize the trace's current
366 * state on registration. It will then be invoked on any change occuring within
367 * the trace's hierarchy.
369 extern int bt_ctf_trace_add_notification_handler_cb(struct bt_ctf_trace
*trace
,
370 bt_ctf_notification_cb handler
, void *handler_data
);
376 #endif /* BABELTRACE_CTF_IR_TRACE_H */