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/ctf-ir/visitor.h>
35 #include <babeltrace/values.h>
36 #include <babeltrace/plugin/notification/notification.h>
45 struct bt_ctf_stream_class
;
49 * Notification handling function type.
51 * A reference must be taken on the notification if the handler has to
52 * keep ownership of the notification beyond the invocation of the callback.
54 * @param notification Notification to handle
55 * @param data Handler private data
57 typedef void (*bt_ctf_notification_cb
)(
58 struct bt_notification
*notification
, void *data
);
61 * bt_ctf_trace_create: create a trace instance.
63 * Allocate a new trace.
65 * A trace's default packet header is a structure initialized with the following
69 * - uint32_t stream_id
71 * Returns a new trace on success, NULL on error.
73 extern struct bt_ctf_trace
*bt_ctf_trace_create(void);
76 * bt_ctf_trace_set_environment_field: sets an environment field to the
79 * Sets an environment field to the trace. The name parameter is
80 * copied, whereas the value parameter's reference count is incremented
81 * (if the function succeeds).
83 * If a value exists in the environment for the specified name, it is
84 * replaced by the new value.
86 * The value parameter _must_ be either an integer value object or a
87 * string value object. Other object types are not supported.
89 * @param trace Trace instance.
90 * @param name Name of the environment field (will be copied).
91 * @param value Value of the environment field.
93 * Returns 0 on success, a negative value on error.
95 extern int bt_ctf_trace_set_environment_field(
96 struct bt_ctf_trace
*trace
, const char *name
,
97 struct bt_value
*value
);
100 * bt_ctf_trace_set_environment_field_string: sets a string environment
101 * field to the trace.
103 * Sets a string environment field to the trace. This is a helper
104 * function which corresponds to calling
105 * bt_ctf_trace_set_environment_field() with a string object.
107 * @param trace Trace instance.
108 * @param name Name of the environment field (will be copied).
109 * @param value Value of the environment field (will be copied).
111 * Returns 0 on success, a negative value on error.
113 extern int bt_ctf_trace_set_environment_field_string(
114 struct bt_ctf_trace
*trace
, const char *name
,
118 * bt_ctf_trace_set_environment_field_integer: sets an integer environment
119 * field to the trace.
121 * Sets an integer environment field to the trace. This is a helper
122 * function which corresponds to calling
123 * bt_ctf_trace_set_environment_field() with an integer object.
125 * @param trace Trace instance.
126 * @param name Name of the environment field (will be copied).
127 * @param value Value of the environment field.
129 * Returns 0 on success, a negative value on error.
131 extern int bt_ctf_trace_set_environment_field_integer(
132 struct bt_ctf_trace
*trace
, const char *name
,
136 * bt_ctf_trace_get_environment_field_count: get environment field count.
138 * Get the trace's environment field count.
140 * @param trace Trace instance.
142 * Returns the environment field count, a negative value on error.
144 extern int bt_ctf_trace_get_environment_field_count(
145 struct bt_ctf_trace
*trace
);
148 * bt_ctf_trace_get_environment_field_name: get environment field name.
150 * Get an environment field's name. The string's ownership is not
151 * transferred to the caller. The string data is valid as long as
152 * this trace's environment is not modified.
154 * @param trace Trace instance.
155 * @param index Index of the environment field.
157 * Returns the environment field's name, NULL on error.
160 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace
*trace
,
164 * bt_ctf_trace_get_environment_field_value: get environment
165 * field value (an object).
167 * Get an environment field's value (an object). The returned object's
168 * reference count is incremented. When done with the object, the caller
169 * must call bt_value_put() on it.
171 * @param trace Trace instance.
172 * @param index Index of the environment field.
174 * Returns the environment field's object value, NULL on error.
176 extern struct bt_value
*
177 bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace
*trace
,
181 * bt_ctf_trace_get_environment_field_value_by_name: get environment
182 * field value (an object) by name.
184 * Get an environment field's value (an object) by its field name. The
185 * returned object's reference count is incremented. When done with the
186 * object, the caller must call bt_value_put() on it.
188 * @param trace Trace instance.
189 * @param name Environment field's name
191 * Returns the environment field's object value, NULL on error.
193 extern struct bt_value
*
194 bt_ctf_trace_get_environment_field_value_by_name(struct bt_ctf_trace
*trace
,
198 * bt_ctf_trace_add_clock: add a clock to the trace.
200 * Add a clock to the trace. Clocks assigned to stream classes must be
201 * added to the trace beforehand.
203 * @param trace Trace instance.
204 * @param clock Clock to add to the trace.
206 * Returns 0 on success, a negative value on error.
208 extern int bt_ctf_trace_add_clock(struct bt_ctf_trace
*trace
,
209 struct bt_ctf_clock
*clock
);
212 * bt_ctf_trace_get_clock_count: get the number of clocks
213 * associated with the trace.
215 * @param trace Trace instance.
217 * Returns the clock count on success, a negative value on error.
219 extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace
*trace
);
222 * bt_ctf_trace_get_clock: get a trace's clock at index.
224 * @param trace Trace instance.
225 * @param index Index of the clock in the given trace.
227 * Return a clock instance on success, NULL on error.
229 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock(
230 struct bt_ctf_trace
*trace
, int index
);
233 * bt_ctf_trace_add_stream_class: add a stream_class to the trace.
235 * Add a stream class to the trace.
237 * @param trace Trace instance.
238 * @param stream_class Stream class to add to the trace.
240 * Returns 0 on success, a negative value on error.
242 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace
*trace
,
243 struct bt_ctf_stream_class
*stream_class
);
246 * bt_ctf_trace_get_stream_class_count: get the number of stream classes
247 * associated with the trace.
249 * @param trace Trace instance.
251 * Returns the stream class count on success, a negative value on error.
253 extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace
*trace
);
256 * bt_ctf_trace_get_stream_class: get a trace's stream class at index.
258 * @param trace Trace instance.
259 * @param index Index of the stream class in the given trace.
261 * Return a stream class on success, NULL on error.
263 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class(
264 struct bt_ctf_trace
*trace
, int index
);
267 * bt_ctf_trace_get_stream_class_by_id: get a trace's stream class by ID.
269 * @param trace Trace instance.
270 * @param index ID of the stream class in the given trace.
272 * Return a stream class on success, NULL on error.
274 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_id(
275 struct bt_ctf_trace
*trace
, uint32_t id
);
278 * bt_ctf_trace_get_clock_by_name: get a trace's clock by name
280 * @param trace Trace instance.
281 * @param name Name of the clock in the given trace.
283 * Return a clock instance on success, NULL on error.
285 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock_by_name(
286 struct bt_ctf_trace
*trace
, const char *name
);
289 * bt_ctf_trace_get_metadata_string: get metadata string.
291 * Get the trace's TSDL metadata. The caller assumes the ownership of the
294 * @param trace Trace instance.
296 * Returns the metadata string on success, NULL on error.
298 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace
*trace
);
301 * bt_ctf_trace_get_byte_order: get a trace's byte order.
303 * Get the trace's byte order.
305 * @param trace Trace instance.
307 * Returns the trace's endianness, BT_CTF_BYTE_ORDER_UNKNOWN on error.
309 extern enum bt_ctf_byte_order
bt_ctf_trace_get_byte_order(
310 struct bt_ctf_trace
*trace
);
313 * bt_ctf_trace_set_byte_order: set a trace's byte order.
315 * Set the trace's byte order. Defaults to the current host's endianness.
317 * @param trace Trace instance.
318 * @param byte_order Trace's byte order.
320 * Returns 0 on success, a negative value on error.
322 * Note: byte_order must not be BT_CTF_BYTE_ORDER_NATIVE since, according
323 * to the CTF specification, is defined as "the byte order described in the
324 * trace description".
326 extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace
*trace
,
327 enum bt_ctf_byte_order byte_order
);
330 * bt_ctf_trace_get_packet_header_type: get a trace's packet header type.
332 * Get the trace's packet header type.
334 * @param trace Trace instance.
336 * Returns the trace's packet header type (a structure) on success, NULL on
339 extern struct bt_ctf_field_type
*bt_ctf_trace_get_packet_header_type(
340 struct bt_ctf_trace
*trace
);
343 * bt_ctf_trace_set_packet_header_type: set a trace's packet header type.
345 * Set the trace's packet header type.
347 * @param trace Trace instance.
348 * @param packet_header_type Packet header field type (must be a structure).
350 * Returns 0 on success, a negative value on error.
352 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace
*trace
,
353 struct bt_ctf_field_type
*packet_header_type
);
356 * bt_ctf_trace_visit: visit a trace's hierarchy.
358 * Recursively walk a trace's hierarchy and call visitor on each of its
361 * @param trace Trace instance.
362 * @param visitor visitor function to invoke for each element.
363 * @param data user data passed to the visitor.
365 * Returns 0 on success, a negative value on error.
367 extern int bt_ctf_trace_visit(struct bt_ctf_trace
*trace
,
368 bt_ctf_ir_visitor visitor
, void *data
);
371 * bt_ctf_trace_add_notification_handler_cb: set a notification callback
372 * which will be invoked whenever a trace's schema is modified.
374 * Register a notification handler to a trace.
376 * @param trace Trace instance.
377 * @param handler Notification handler to invoke on trace xmodification.
378 * @param handler_data Private data passed to the notification handler.
380 * Returns 0 on success, a negative value on error.
382 * Note: the notification handler will be used to serialize the trace's current
383 * state on registration. It will then be invoked on any change occuring within
384 * the trace's hierarchy.
386 extern int bt_ctf_trace_add_notification_handler_cb(struct bt_ctf_trace
*trace
,
387 bt_ctf_notification_cb handler
, void *handler_data
);
393 #endif /* BABELTRACE_CTF_IR_TRACE_H */