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>
44 @defgroup ctfirtraceclass CTF IR trace class
46 @brief CTF IR trace class.
48 A CTF IR <strong><em>trace class</em></strong> is a descriptor of
51 You can obtain a trace class in two different modes:
53 - <strong>Normal mode</strong>: use bt_ctf_trace_create() to create a
54 default, empty trace class.
55 - <strong>CTF IR writer mode</strong>: use bt_ctf_writer_get_trace() to
56 get the trace class created by a given CTF IR writer object.
58 A trace class has the following properties:
61 - A <strong>default byte order</strong>: all the
62 \link ctfirfieldtype field types\endlink eventually part of the trace
63 class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this
65 - An \b environment, which is a custom key-value mapping. Keys are
66 strings and values can be strings or integers.
68 In the Babeltrace CTF IR system, a trace class contains zero or more
69 \link ctfirstreamclass stream classes\endlink, and a stream class
70 contains zero or more \link ctfireventclass event classes\endlink. You
71 can add an event class to a stream class with
72 bt_ctf_stream_class_add_event_class(). You can add a stream class to a
73 trace class with bt_ctf_trace_add_stream_class().
75 A trace class owns the <strong>trace packet header</strong>
76 \link ctfirfieldtypes field type\endlink, which represents the
77 \c trace.packet.header CTF scope. This field type describes the
78 trace packet header fields of the traces that this trace class
81 The trace packet header field type \em must be a structure field type as
82 of Babeltrace \btversion.
84 As per the CTF specification, the trace packet header field type \em
85 must contain a field named \c stream_id if the trace class contains more
86 than one stream class.
88 As a reminder, here's the structure of a CTF packet:
92 A trace class also contains zero or more
93 \link ctfirclockclass clock classes\endlink.
96 Elaborate about clock classes irt clock values.
98 As with any Babeltrace object, CTF IR trace class objects have
99 <a href="https://en.wikipedia.org/wiki/Reference_counting">reference
100 counts</a>. See \ref refs to learn more about the reference counting
101 management of Babeltrace objects.
103 The following functions \em freeze their trace class parameter on
106 - bt_ctf_trace_add_stream_class()
107 - bt_ctf_writer_create_stream()
108 (\link ctfirwriter CTF IR writer\endlink mode only)
110 You cannot modify a frozen trace class: it is considered immutable,
113 - Adding a stream class to it with
114 bt_ctf_trace_add_stream_class().
115 - Adding a clock class to it with bt_ctf_trace_add_clock().
116 - \link refs Reference counting\endlink.
118 You can add a custom listener with bt_ctf_trace_add_listener() to get
119 notified if anything changes in a trace class, that is, if an event
120 class is added to one of its stream class, if a stream class is added,
121 or if a clock class is added.
128 @brief CTF IR trace class type and functions.
131 @addtogroup ctfirtraceclass
137 @brief A CTF IR trace class.
141 struct bt_ctf_stream
;
142 struct bt_ctf_stream_class
;
146 @name Creation function
151 @brief Creates a default CTF IR trace class.
153 On success, the trace packet header field type of the created trace
154 class has the following fields:
156 - <code>magic</code>: a 32-bit unsigned integer field type.
157 - <code>uuid</code>: an array field type of 16 8-bit unsigned integer
159 - <code>stream_id</code>: a 32-bit unsigned integer field type.
161 You can modify this default trace packet header field type after the
162 trace class is created with bt_ctf_trace_set_packet_header_type().
164 The created trace class has the following initial properties:
166 - <strong>Name</strong>: none. You can set a name
167 with bt_ctf_trace_set_name().
168 - <strong>Default byte order</strong>: #BT_CTF_BYTE_ORDER_NATIVE. You
169 can set a default byte order with bt_ctf_trace_set_byte_order().
171 Note that you \em must set the default byte order if any field type
172 contained in the created trace class, in its stream classes, or in
173 its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE.
174 - <strong>Environment</strong>: empty. You can add environment entries
175 with bt_ctf_trace_set_environment_field(),
176 bt_ctf_trace_set_environment_field_integer(), and
177 bt_ctf_trace_set_environment_field_string().
179 @returns Created trace class, or \c NULL on error.
181 @postsuccessrefcountret1
183 extern struct bt_ctf_trace
*bt_ctf_trace_create(void);
188 @name Properties functions
193 @brief Returns the name of the CTF IR trace class \p trace_class.
195 On success, \p trace_class remains the sole owner of the returned
196 string. The returned string is valid as long as \p trace_class exists
199 @param[in] trace_class Trace class of which to get the name.
200 @returns Name of trace class \p trace_class, or
201 \c NULL if \p trace_class is unnamed or
204 @prenotnull{trace_class}
205 @postrefcountsame{trace_class}
207 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
209 extern const char *bt_ctf_trace_get_name(struct bt_ctf_trace
*trace_class
);
212 @brief Sets the name of the CTF IR trace class \p trace_class
215 @param[in] trace_class Trace class of which to set the name.
216 @param[in] name Name of the trace class (copied on success).
217 @returns 0 on success, or a negative value on error.
219 @prenotnull{trace_class}
222 @postrefcountsame{trace_class}
224 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
226 extern int bt_ctf_trace_set_name(struct bt_ctf_trace
*trace_class
,
230 @brief Returns the default byte order of the CTF IR trace class
233 @param[in] trace_class Trace class of which to get the default byte
235 @returns Default byte order of trace class
236 \p trace_class, or #BT_CTF_BYTE_ORDER_UNKNOWN
239 @prenotnull{trace_class}
240 @postrefcountsame{trace_class}
242 @sa bt_ctf_trace_set_name(): Sets the name of a given trace class.
244 extern enum bt_ctf_byte_order
bt_ctf_trace_get_byte_order(
245 struct bt_ctf_trace
*trace_class
);
248 @brief Sets the default byte order of the CTF IR trace class
249 \p trace_class to \p name.
251 \p byte_order \em must be one of:
253 - #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN
254 - #BT_CTF_BYTE_ORDER_BIG_ENDIAN
255 - #BT_CTF_BYTE_ORDER_NETWORK
257 @param[in] trace_class Trace class of which to set the default byte
259 @param[in] byte_order Default byte order of the trace class.
260 @returns 0 on success, or a negative value on error.
262 @prenotnull{trace_class}
265 @pre \p byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
266 #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or
267 #BT_CTF_BYTE_ORDER_NETWORK.
268 @postrefcountsame{trace_class}
270 @sa bt_ctf_trace_get_name(): Returns the name of a given trace class.
272 extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace
*trace_class
,
273 enum bt_ctf_byte_order byte_order
);
276 @brief Returns the number of entries contained in the environment of
277 the CTF IR trace class \p trace_class.
279 @param[in] trace_class Trace class of which to get the number
280 of environment entries.
281 @returns Number of environment entries
282 contained in \p trace_class, or
283 a negative value on error.
285 @prenotnull{trace_class}
286 @postrefcountsame{trace_class}
288 extern int bt_ctf_trace_get_environment_field_count(
289 struct bt_ctf_trace
*trace_class
);
292 @brief Returns the field name of the environment entry at index
293 \p index in the CTF IR trace class \p trace_class.
295 On success, the returned string is valid as long as this trace class
296 exists and is \em not modified. \p trace_class remains the sole owner of
299 @param[in] trace_class Trace class of which to get the name of the
300 environment entry at index \p index.
301 @param[in] index Index of environment entry to find.
302 @returns Name of the environment entry at index \p index
303 in \p trace_class, or \c NULL on error.
305 @prenotnull{trace_class}
306 @pre \p index is lesser than the number of environment entries in
307 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
308 @postrefcountsame{trace_class}
310 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
311 environment entry by index.
312 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
313 class's environment entry by name.
314 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
315 class's environment entry.
318 bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace
*trace_class
,
322 @brief Returns the value of the environment entry at index
323 \p index in the CTF IR trace class \p trace_class.
325 @param[in] trace_class Trace class of which to get the value of the
326 environment entry at index \p index.
327 @param[in] index Index of the environment entry to find.
328 @returns Value of the environment entry at index \p index
329 in \p trace_class, or \c NULL on error.
331 @prenotnull{trace_class}
332 @pre \p index is lesser than the number of environment entries in
333 \p trace_class (see bt_ctf_trace_get_environment_field_count()).
334 @postrefcountsame{trace_class}
335 @postsuccessrefcountretinc
337 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
338 class's environment entry by name.
339 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
340 class's environment entry.
342 extern struct bt_value
*
343 bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace
*trace_class
,
347 @brief Returns the value of the environment entry named \p name
348 in the CTF IR trace class \p trace_class.
350 @param[in] trace_class Trace class of which to get the value of the
351 environment entry named \p name.
352 @param[in] name Name of the environment entry to find.
353 @returns Value of the environment entry named \p name
354 in \p trace_class, or \c NULL if there's no such
357 @prenotnull{trace_class}
359 @postrefcountsame{trace_class}
360 @postsuccessrefcountretinc
362 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
363 environment entry by index.
364 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
365 class's environment entry.
367 extern struct bt_value
*
368 bt_ctf_trace_get_environment_field_value_by_name(
369 struct bt_ctf_trace
*trace_class
, const char *name
);
372 @brief Sets the environment entry named \p name in the
373 CTF IR trace class \p trace_class to \p value.
375 If an environment entry named \p name exists in \p trace_class, its
376 value is first put, and then replaced by \p value.
378 @param[in] trace_class Trace class of which to set the environment
380 @param[in] name Name of the environment entry to set (copied
382 @param[in] value Value of the environment entry named \p name.
383 @returns 0 on success, or a negative value on error.
385 @prenotnull{trace_class}
390 \link bt_value_integer_create() integer value object\endlink
392 \link bt_value_string_create() string value object\endlink.
393 @postrefcountsame{trace_class}
394 @postsuccessrefcountinc{value}
396 @sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's
397 environment entry by index.
398 @sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace
399 class's environment entry by name.
401 extern int bt_ctf_trace_set_environment_field(
402 struct bt_ctf_trace
*trace_class
, const char *name
,
403 struct bt_value
*value
);
406 @brief Sets the environment entry named \p name in the
407 CTF IR trace class \p trace_class to \p value.
409 If an environment entry named \p name exists in \p trace_class, its
410 value is first put, and then replaced by a new
411 \link bt_value_integer_create() integer value object\endlink
414 @param[in] trace_class Trace class of which to set the environment
416 @param[in] name Name of the environment entry to set (copied
418 @param[in] value Value of the environment entry named \p name.
419 @returns 0 on success, or a negative value on error.
421 @prenotnull{trace_class}
424 @postrefcountsame{trace_class}
426 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
427 class's environment entry.
429 extern int bt_ctf_trace_set_environment_field_integer(
430 struct bt_ctf_trace
*trace_class
, const char *name
,
434 @brief Sets the environment entry named \p name in the
435 CTF IR trace class \p trace_class to \p value.
437 If an environment entry named \p name exists in \p trace_class, its
438 value is first put, and then replaced by a new
439 \link bt_value_string_create() string value object\endlink
442 @param[in] trace_class Trace class of which to set the environment
444 @param[in] name Name of the environment entry to set (copied
446 @param[in] value Value of the environment entry named \p name
448 @returns 0 on success, or a negative value on error.
450 @prenotnull{trace_class}
454 @postrefcountsame{trace_class}
456 @sa bt_ctf_trace_set_environment_field(): Sets the value of a trace
457 class's environment entry.
459 extern int bt_ctf_trace_set_environment_field_string(
460 struct bt_ctf_trace
*trace_class
, const char *name
,
466 @name Contained field types functions
471 @brief Returns the packet header field type of the CTF IR trace class
474 @param[in] trace_class Trace class of which to get the packet
476 @returns Packet header field type of \p trace_class,
479 @prenotnull{trace_class}
480 @postsuccessrefcountretinc
482 @sa bt_ctf_trace_set_packet_header_type(): Sets the packet
483 header field type of a given trace class.
485 extern struct bt_ctf_field_type
*bt_ctf_trace_get_packet_header_type(
486 struct bt_ctf_trace
*trace_class
);
489 @brief Sets the packet header field type of the CTF IR trace class
490 \p trace_class to \p packet_context_type.
492 As of Babeltrace \btversion, \p packet_context_type \em must be a
493 CTF IR structure field type object.
495 @param[in] trace_class Trace class of which to set the packet
497 @param[in] packet_header_type Packet header field type.
498 @returns 0 on success, or a negative value on error.
500 @prenotnull{trace_class}
501 @prenotnull{packet_header_type}
503 @preisstructft{packet_header_type}
504 @postrefcountsame{trace_class}
505 @postsuccessrefcountinc{packet_header_type}
507 @sa bt_ctf_trace_get_packet_header_type(): Returns the packet
508 header field type of a given trace class.
510 extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace
*trace_class
,
511 struct bt_ctf_field_type
*packet_header_type
);
516 @name Clock class children functions
521 @brief Returns the number of clock classes contained in the
522 CTF IR trace class \p trace_class.
524 @param[in] trace_class Trace class of which to get the number
525 of children clock classes.
526 @returns Number of children clock classes
527 contained in \p trace_class, or a negative
530 @prenotnull{trace_class}
531 @postrefcountsame{trace_class}
533 extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace
*trace_class
);
536 @brief Returns the clock class at index \p index in the CTF IR trace
537 class \p trace_class.
539 @param[in] trace_class Trace class of which to get the clock class.
540 @param[in] index Index of the clock class to find.
541 @returns Clock class at index \p index, or \c NULL
544 @prenotnull{trace_class}
545 @pre \p index is lesser than the number of clock classes contained in
546 the trace class \p trace_class (see
547 bt_ctf_trace_get_clock_count()).
548 @postrefcountsame{trace_class}
549 @postsuccessrefcountretinc
551 @sa bt_ctf_trace_get_clock_by_name(): Finds a clock class by name.
552 @sa bt_ctf_trace_add_clock(): Adds a clock class to a trace class.
554 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock(
555 struct bt_ctf_trace
*trace_class
, int index
);
558 @brief Returns the clock class named \c name found in the CTF IR trace
559 class \p trace_class.
561 @param[in] trace_class Trace class of which to get the clock class.
562 @param[in] name Name of the clock class to find.
563 @returns Clock class named \p name, or \c NULL
566 @prenotnull{trace_class}
568 @postrefcountsame{trace_class}
569 @postsuccessrefcountretinc
571 @sa bt_ctf_trace_get_clock(): Returns the clock class contained in a
572 given trace class at a given index.
573 @sa bt_ctf_trace_add_clock(): Adds a clock class to a trace class.
575 extern struct bt_ctf_clock
*bt_ctf_trace_get_clock_by_name(
576 struct bt_ctf_trace
*trace_class
, const char *name
);
579 @brief Adds the CTF IR clock class \p clock_class to the CTF IR
580 trace class \p trace_class.
582 On success, \p clock_class becomes the child of \p trace_class.
584 You can call this function even if \p trace_class is frozen.
586 @param[in] trace_class Trace class to which to add \p clock_class.
587 @param[in] clock_class Clock class to add to \p trace_class.
588 @returns 0 on success, or a negative value on error.
590 @prenotnull{trace_class}
591 @prenotnull{clock_class}
592 @postrefcountsame{trace_class}
593 @postsuccessrefcountinc{clock_class}
594 @post <strong>On success, if \p trace_class is frozen<strong>,
595 \p clock_class is frozen.
597 @sa bt_ctf_trace_get_clock(): Returns the clock class contained in a
598 given trace class at a given index.
599 @sa bt_ctf_trace_get_clock_by_name(): Finds a clock class by name.
601 extern int bt_ctf_trace_add_clock(struct bt_ctf_trace
*trace_class
,
602 struct bt_ctf_clock
*clock_class
);
607 @name Stream class children functions
612 @brief Returns the number of stream classes contained in the
613 CTF IR trace class \p trace_class.
615 @param[in] trace_class Trace class of which to get the number
616 of children stream classes.
617 @returns Number of children stream classes
618 contained in \p trace_class, or a negative
621 @prenotnull{trace_class}
622 @postrefcountsame{trace_class}
624 extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace
*trace_class
);
627 @brief Returns the stream class at index \p index in the CTF IR trace
628 class \p trace_class.
630 @param[in] trace_class Trace class of which to get the stream class.
631 @param[in] index Index of the stream class to find.
632 @returns Stream class at index \p index, or \c NULL
635 @prenotnull{trace_class}
636 @pre \p index is lesser than the number of stream classes contained in
637 the trace class \p trace_class (see
638 bt_ctf_trace_get_stream_class_count()).
639 @postrefcountsame{trace_class}
640 @postsuccessrefcountretinc
642 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
643 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
645 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class(
646 struct bt_ctf_trace
*trace_class
, int index
);
649 @brief Returns the stream class with ID \c id found in the CTF IR
650 trace class \p trace_class.
652 @param[in] trace_class Trace class of which to get the stream class.
653 @param[in] id ID of the stream class to find.
654 @returns Stream class with ID \p id, or \c NULL
657 @prenotnull{trace_class}
658 @postrefcountsame{trace_class}
659 @postsuccessrefcountretinc
661 @sa bt_ctf_trace_get_clock(): Returns the stream class contained in a
662 given trace class at a given index.
663 @sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class.
665 extern struct bt_ctf_stream_class
*bt_ctf_trace_get_stream_class_by_id(
666 struct bt_ctf_trace
*trace_class
, uint32_t id
);
669 @brief Adds the CTF IR stream class \p stream_class to the
670 CTF IR trace class \p trace_class.
672 On success, \p stream_class becomes the child of \p trace_class.
674 You can only add a given stream class to one trace class.
676 You can call this function even if \p trace_class is frozen.
678 @param[in] trace_class Trace class to which to add \p stream_class.
679 @param[in] stream_class Stream class to add to \p trace_class.
680 @returns 0 on success, or a negative value on error.
682 @prenotnull{trace_class}
683 @prenotnull{stream_class}
684 @postrefcountsame{trace_class}
685 @postsuccessrefcountinc{stream_class}
686 @postsuccessfrozen{stream_class}
688 @sa bt_ctf_trace_get_clock(): Returns the stream class contained in a
689 given trace class at a given index.
690 @sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID.
692 extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace
*trace_class
,
693 struct bt_ctf_stream_class
*stream_class
);
698 @name Misc. functions
703 @brief User function type to use with bt_ctf_trace_add_listener().
705 @param[in] obj New CTF IR object which is part of the trace
707 @param[in] data User data.
711 typedef void (*bt_ctf_listener_cb
)(struct bt_ctf_object
*obj
, void *data
);
714 @brief Adds the trace class modification listener \p listener to
715 the CTF IR trace class \p trace_class.
717 Once you add \p listener to \p trace_class, whenever \p trace_class
718 is modified, \p listener is called with the new element and with
721 @param[in] trace_class Trace class to which to add \p listener.
722 @param[in] listener Modification listener function.
723 @param[in] data User data.
724 @returns 0 on success, or a negative value on error.
726 @prenotnull{trace_class}
727 @prenotnull{listener}
729 extern int bt_ctf_trace_add_listener(struct bt_ctf_trace
*trace_class
,
730 bt_ctf_listener_cb listener
, void *data
);
733 @brief Accepts the visitor \p visitor to visit the hierarchy of the
734 CTF IR trace class \p trace_class.
736 This function traverses the hierarchy of \p trace_class in pre-order
737 and calls \p visitor on each element.
739 The trace class itself is visited first, then, for each children stream
740 class, the stream class itself, and all its children event classes.
742 @param[in] trace_class Trace class to visit.
743 @param[in] visitor Visiting function.
744 @param[in] data User data.
745 @returns 0 on success, or a negative value on error.
747 @prenotnull{trace_class}
750 extern int bt_ctf_trace_visit(struct bt_ctf_trace
*trace_class
,
751 bt_ctf_visitor visitor
, void *data
);
756 * bt_ctf_trace_get_metadata_string: get metadata string.
758 * Get the trace's TSDL metadata. The caller assumes the ownership of the
761 * @param trace Trace instance.
763 * Returns the metadata string on success, NULL on error.
765 extern char *bt_ctf_trace_get_metadata_string(struct bt_ctf_trace
*trace
);
771 #endif /* BABELTRACE_CTF_IR_TRACE_H */