X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ftrace.h;h=84b9b7a92258027db94db571b2891a5aab0d9bb5;hb=56e18c4ce186892c36d7f2cb5078087425e60134;hp=b2cda19bcf711e505c30edcec253ef7764764059;hpb=063003164359e469b2d60cfe1c5d885e37678aff;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/trace.h b/include/babeltrace/ctf-ir/trace.h index b2cda19b..84b9b7a9 100644 --- a/include/babeltrace/ctf-ir/trace.h +++ b/include/babeltrace/ctf-ir/trace.h @@ -1,769 +1,2 @@ -#ifndef BABELTRACE_CTF_IR_TRACE_H -#define BABELTRACE_CTF_IR_TRACE_H - -/* - * BabelTrace - CTF IR: Trace - * - * Copyright 2014 Jérémie Galarneau - * - * Author: Jérémie Galarneau - * - * 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 -#include -#include -#include -#include - -#ifdef __cplusplus -extern "C" { -#endif - -/** -@defgroup ctfirtraceclass CTF IR trace class -@ingroup ctfir -@brief CTF IR trace class. - -A CTF IR trace class is a descriptor of -traces. - -You can obtain a trace class in two different modes: - -- Normal mode: use bt_ctf_trace_create() to create a - default, empty trace class. -- CTF writer mode: use bt_ctf_writer_get_trace() to - get the trace class created by a given CTF writer object. - -A trace class has the following properties: - -- A \b name. -- A default byte order: all the - \link ctfirfieldtype field types\endlink eventually part of the trace - class with a byte order set to #BT_CTF_BYTE_ORDER_NATIVE have this - "real" byte order. -- An \b environment, which is a custom key-value mapping. Keys are - strings and values can be strings or integers. - -In the Babeltrace CTF IR system, a trace class contains zero or more -\link ctfirstreamclass stream classes\endlink, and a stream class -contains zero or more \link ctfireventclass event classes\endlink. You -can add an event class to a stream class with -bt_ctf_stream_class_add_event_class(). You can add a stream class to a -trace class with bt_ctf_trace_add_stream_class(). - -A trace class owns the trace packet header -\link ctfirfieldtypes field type\endlink, which represents the -\c trace.packet.header CTF scope. This field type describes the -trace packet header fields of the traces that this trace class -describes. - -The trace packet header field type \em must be a structure field type as -of Babeltrace \btversion. - -As per the CTF specification, the trace packet header field type \em -must contain a field named \c stream_id if the trace class contains more -than one stream class. - -As a reminder, here's the structure of a CTF packet: - -@imgpacketstructure - -A trace class also contains zero or more -\link ctfirclockclass clock classes\endlink. - -@todo -Elaborate about clock classes irt clock values. - -As with any Babeltrace object, CTF IR stream class objects have -reference -counts. See \ref refs to learn more about the reference counting -management of Babeltrace objects. - -The following functions \em freeze their trace class parameter on -success: - -- bt_ctf_trace_add_stream_class() -- bt_ctf_writer_create_stream() - (\link ctfirwriter CTF writer\endlink mode only) - -You cannot modify a frozen trace class: it is considered immutable, -except for: - -- Adding a stream class to it with - bt_ctf_trace_add_stream_class(). -- Adding a clock class to it with bt_ctf_trace_add_clock(). -- \link refs Reference counting\endlink. - -You can add a custom listener with bt_ctf_trace_add_listener() to get -notified if anything changes in a trace class, that is, if an event -class is added to one of its stream class, if a stream class is added, -or if a clock class is added. - -@sa ctfirstreamclass -@sa ctfireventclass -@sa ctfirclockclass - -@file -@brief CTF IR trace class type and functions. -@sa ctfirtraceclass - -@addtogroup ctfirtraceclass -@{ -*/ - -/** -@struct bt_ctf_trace -@brief A CTF IR trace class. -@sa ctfirtraceclass -*/ -struct bt_ctf_trace; -struct bt_ctf_stream; -struct bt_ctf_stream_class; -struct bt_ctf_clock; - -/** -@name Creation function -@{ -*/ - -/** -@brief Creates a default CTF IR trace class. - -On success, the trace packet header field type of the created trace -class has the following fields: - -- magic: a 32-bit unsigned integer field type. -- uuid: an array field type of 16 8-bit unsigned integer - field types. -- stream_id: a 32-bit unsigned integer field type. - -You can modify this default trace packet header field type after the -trace class is created with bt_ctf_trace_set_packet_header_type(). - -The created trace class has the following initial properties: - -- Name: none. You can set a name - with bt_ctf_trace_set_name(). -- Default byte order: #BT_CTF_BYTE_ORDER_NATIVE. You - can set a default byte order with bt_ctf_trace_set_byte_order(). - - Note that you \em must set the default byte order if any field type - contained in the created trace class, in its stream classes, or in - its event classes, has a byte order set to #BT_CTF_BYTE_ORDER_NATIVE. -- Environment: empty. You can add environment entries - with bt_ctf_trace_set_environment_field(), - bt_ctf_trace_set_environment_field_integer(), and - bt_ctf_trace_set_environment_field_string(). - -@returns Created trace class, or \c NULL on error. - -@postsuccessrefcountret1 -*/ -extern struct bt_ctf_trace *bt_ctf_trace_create(void); - -/** @} */ - -/** -@name Properties functions -@{ -*/ - -/** -@brief Returns the name of the CTF IR trace class \p trace_class. - -On success, \p trace_class remains the sole owner of the returned -string. The returned string is valid as long as \p trace_class exists -and is not modified. - -@param[in] trace_class Trace class of which to get the name. -@returns Name of trace class \p trace_class, or - \c NULL if \p trace_class is unnamed or - on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_set_name(): Sets the name of a given trace class. -*/ -extern const char *bt_ctf_trace_get_name(struct bt_ctf_trace *trace_class); - -/** -@brief Sets the name of the CTF IR trace class \p trace_class - to \p name. - -@param[in] trace_class Trace class of which to set the name. -@param[in] name Name of the trace class (copied on success). -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prehot{trace_class} -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_get_name(): Returns the name of a given trace class. -*/ -extern int bt_ctf_trace_set_name(struct bt_ctf_trace *trace_class, - const char *name); - -/** -@brief Returns the default byte order of the CTF IR trace class - \p trace_class. - -@param[in] trace_class Trace class of which to get the default byte - order. -@returns Default byte order of trace class - \p trace_class, or #BT_CTF_BYTE_ORDER_UNKNOWN - on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_set_name(): Sets the name of a given trace class. -*/ -extern enum bt_ctf_byte_order bt_ctf_trace_get_byte_order( - struct bt_ctf_trace *trace_class); - -/** -@brief Sets the default byte order of the CTF IR trace class - \p trace_class to \p name. - -\p byte_order \em must be one of: - -- #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN -- #BT_CTF_BYTE_ORDER_BIG_ENDIAN -- #BT_CTF_BYTE_ORDER_NETWORK - -@param[in] trace_class Trace class of which to set the default byte - order. -@param[in] byte_order Default byte order of the trace class. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prehot{trace_class} -@pre \p byte_order is either #BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, - #BT_CTF_BYTE_ORDER_BIG_ENDIAN, or - #BT_CTF_BYTE_ORDER_NETWORK. -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_get_name(): Returns the name of a given trace class. -*/ -extern int bt_ctf_trace_set_byte_order(struct bt_ctf_trace *trace_class, - enum bt_ctf_byte_order byte_order); - -/** -@brief Returns the number of entries contained in the environment of - the CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of environment entries. -@returns Number of environment entries - contained in \p trace_class, or - a negative value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int bt_ctf_trace_get_environment_field_count( - struct bt_ctf_trace *trace_class); - -/** -@brief Returns the field name of the environment entry at index - \p index in the CTF IR trace class \p trace_class. - -On success, the returned string is valid as long as this trace class -exists and is \em not modified. \p trace_class remains the sole owner of -the returned string. - -@param[in] trace_class Trace class of which to get the name of the - environment entry at index \p index. -@param[in] index Index of environment entry to find. -@returns Name of the environment entry at index \p index - in \p trace_class, or \c NULL on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of environment entries in - \p trace_class (see bt_ctf_trace_get_environment_field_count()). -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's - environment entry by index. -@sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace - class's environment entry by name. -@sa bt_ctf_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern const char * -bt_ctf_trace_get_environment_field_name(struct bt_ctf_trace *trace_class, - int index); - -/** -@brief Returns the value of the environment entry at index - \p index in the CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the value of the - environment entry at index \p index. -@param[in] index Index of the environment entry to find. -@returns Value of the environment entry at index \p index - in \p trace_class, or \c NULL on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of environment entries in - \p trace_class (see bt_ctf_trace_get_environment_field_count()). -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace - class's environment entry by name. -@sa bt_ctf_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern struct bt_value * -bt_ctf_trace_get_environment_field_value(struct bt_ctf_trace *trace_class, - int index); - -/** -@brief Returns the value of the environment entry named \p name - in the CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the value of the - environment entry named \p name. -@param[in] name Name of the environment entry to find. -@returns Value of the environment entry named \p name - in \p trace_class, or \c NULL if there's no such - entry or on error. - -@prenotnull{trace_class} -@prenotnull{name} -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's - environment entry by index. -@sa bt_ctf_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern struct bt_value * -bt_ctf_trace_get_environment_field_value_by_name( - struct bt_ctf_trace *trace_class, const char *name); - -/** -@brief Sets the environment entry named \p name in the - CTF IR trace class \p trace_class to \p value. - -If an environment entry named \p name exists in \p trace_class, its -value is first put, and then replaced by \p value. - -@param[in] trace_class Trace class of which to set the environment - entry. -@param[in] name Name of the environment entry to set (copied - on success). -@param[in] value Value of the environment entry named \p name. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prenotnull{value} -@prehot{trace_class} -@pre \p value is an - \link bt_value_integer_create() integer value object\endlink - or a - \link bt_value_string_create() string value object\endlink. -@postrefcountsame{trace_class} -@postsuccessrefcountinc{value} - -@sa bt_ctf_trace_get_environment_field_value(): Finds a trace class's - environment entry by index. -@sa bt_ctf_trace_get_environment_field_value_by_name(): Finds a trace - class's environment entry by name. -*/ -extern int bt_ctf_trace_set_environment_field( - struct bt_ctf_trace *trace_class, const char *name, - struct bt_value *value); - -/** -@brief Sets the environment entry named \p name in the - CTF IR trace class \p trace_class to \p value. - -If an environment entry named \p name exists in \p trace_class, its -value is first put, and then replaced by a new -\link bt_value_integer_create() integer value object\endlink -containing \p value. - -@param[in] trace_class Trace class of which to set the environment - entry. -@param[in] name Name of the environment entry to set (copied - on success). -@param[in] value Value of the environment entry named \p name. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prehot{trace_class} -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern int bt_ctf_trace_set_environment_field_integer( - struct bt_ctf_trace *trace_class, const char *name, - int64_t value); - -/** -@brief Sets the environment entry named \p name in the - CTF IR trace class \p trace_class to \p value. - -If an environment entry named \p name exists in \p trace_class, its -value is first put, and then replaced by a new -\link bt_value_string_create() string value object\endlink -containing \p value. - -@param[in] trace_class Trace class of which to set the environment - entry. -@param[in] name Name of the environment entry to set (copied - on success). -@param[in] value Value of the environment entry named \p name - (copied on success). -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{name} -@prenotnull{value} -@prehot{trace_class} -@postrefcountsame{trace_class} - -@sa bt_ctf_trace_set_environment_field(): Sets the value of a trace - class's environment entry. -*/ -extern int bt_ctf_trace_set_environment_field_string( - struct bt_ctf_trace *trace_class, const char *name, - const char *value); - -/** @} */ - -/** -@name Contained field types functions -@{ -*/ - -/** -@brief Returns the packet header field type of the CTF IR trace class - \p trace_class. - -@param[in] trace_class Trace class of which to get the packet - header field type. -@returns Packet header field type of \p trace_class, - or \c NULL on error. - -@prenotnull{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_set_packet_header_type(): Sets the packet - header field type of a given trace class. -*/ -extern struct bt_ctf_field_type *bt_ctf_trace_get_packet_header_type( - struct bt_ctf_trace *trace_class); - -/** -@brief Sets the packet header field type of the CTF IR trace class - \p trace_class to \p packet_context_type. - -As of Babeltrace \btversion, \p packet_context_type \em must be a -CTF IR structure field type object. - -@param[in] trace_class Trace class of which to set the packet - header field type. -@param[in] packet_header_type Packet header field type. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{packet_header_type} -@prehot{trace_class} -@preisstructft{packet_header_type} -@postrefcountsame{trace_class} -@postsuccessrefcountinc{packet_header_type} - -@sa bt_ctf_trace_get_packet_header_type(): Returns the packet - header field type of a given trace class. -*/ -extern int bt_ctf_trace_set_packet_header_type(struct bt_ctf_trace *trace_class, - struct bt_ctf_field_type *packet_header_type); - -/** @} */ - -/** -@name Clock class children functions -@{ -*/ - -/** -@brief Returns the number of clock classes contained in the - CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of children clock classes. -@returns Number of children clock classes - contained in \p trace_class, or a negative - value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int bt_ctf_trace_get_clock_count(struct bt_ctf_trace *trace_class); - -/** -@brief Returns the clock class at index \p index in the CTF IR trace - class \p trace_class. - -@param[in] trace_class Trace class of which to get the clock class. -@param[in] index Index of the clock class to find. -@returns Clock class at index \p index, or \c NULL - on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of clock classes contained in - the trace class \p trace_class (see - bt_ctf_trace_get_clock_count()). -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_get_clock_by_name(): Finds a clock class by name. -@sa bt_ctf_trace_add_clock(): Adds a clock class to a trace class. -*/ -extern struct bt_ctf_clock *bt_ctf_trace_get_clock( - struct bt_ctf_trace *trace_class, int index); - -/** -@brief Returns the clock class named \c name found in the CTF IR trace - class \p trace_class. - -@param[in] trace_class Trace class of which to get the clock class. -@param[in] name Name of the clock class to find. -@returns Clock class named \p name, or \c NULL - on error. - -@prenotnull{trace_class} -@prenotnull{name} -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_get_clock(): Returns the clock class contained in a - given trace class at a given index. -@sa bt_ctf_trace_add_clock(): Adds a clock class to a trace class. -*/ -extern struct bt_ctf_clock *bt_ctf_trace_get_clock_by_name( - struct bt_ctf_trace *trace_class, const char *name); - -/** -@brief Adds the CTF IR clock class \p clock_class to the CTF IR - trace class \p trace_class. - -On success, \p clock_class becomes the child of \p trace_class. - -You can call this function even if \p trace_class is frozen. - -@param[in] trace_class Trace class to which to add \p clock_class. -@param[in] clock_class Clock class to add to \p trace_class. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{clock_class} -@postrefcountsame{trace_class} -@postsuccessrefcountinc{clock_class} - -@sa bt_ctf_trace_get_clock(): Returns the clock class contained in a - given trace class at a given index. -@sa bt_ctf_trace_get_clock_by_name(): Finds a clock class by name. -*/ -extern int bt_ctf_trace_add_clock(struct bt_ctf_trace *trace_class, - struct bt_ctf_clock *clock_class); - -/** @} */ - -/** -@name Stream class children functions -@{ -*/ - -/** -@brief Returns the number of stream classes contained in the - CTF IR trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the number - of children stream classes. -@returns Number of children stream classes - contained in \p trace_class, or a negative - value on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -*/ -extern int bt_ctf_trace_get_stream_class_count(struct bt_ctf_trace *trace_class); - -/** -@brief Returns the stream class at index \p index in the CTF IR trace - class \p trace_class. - -@param[in] trace_class Trace class of which to get the stream class. -@param[in] index Index of the stream class to find. -@returns Stream class at index \p index, or \c NULL - on error. - -@prenotnull{trace_class} -@pre \p index is lesser than the number of stream classes contained in - the trace class \p trace_class (see - bt_ctf_trace_get_stream_class_count()). -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID. -@sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class. -*/ -extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class( - struct bt_ctf_trace *trace_class, int index); - -/** -@brief Returns the stream class with ID \c id found in the CTF IR - trace class \p trace_class. - -@param[in] trace_class Trace class of which to get the stream class. -@param[in] id ID of the stream class to find. -@returns Stream class with ID \p id, or \c NULL - on error. - -@prenotnull{trace_class} -@postrefcountsame{trace_class} -@postsuccessrefcountretinc - -@sa bt_ctf_trace_get_clock(): Returns the stream class contained in a - given trace class at a given index. -@sa bt_ctf_trace_add_stream_class(): Adds a stream class to a trace class. -*/ -extern struct bt_ctf_stream_class *bt_ctf_trace_get_stream_class_by_id( - struct bt_ctf_trace *trace_class, uint32_t id); - -/** -@brief Adds the CTF IR stream class \p stream_class to the - CTF IR trace class \p trace_class. - -On success, \p stream_class becomes the child of \p trace_class. - -You can only add a given stream class to one trace class. - -You can call this function even if \p trace_class is frozen. - -@param[in] trace_class Trace class to which to add \p stream_class. -@param[in] stream_class Stream class to add to \p trace_class. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{stream_class} -@postrefcountsame{trace_class} -@postsuccessrefcountinc{stream_class} - -@sa bt_ctf_trace_get_clock(): Returns the stream class contained in a - given trace class at a given index. -@sa bt_ctf_trace_get_stream_class_by_id(): Finds a stream class by ID. -*/ -extern int bt_ctf_trace_add_stream_class(struct bt_ctf_trace *trace_class, - struct bt_ctf_stream_class *stream_class); - -/** @} */ - -/** -@name Misc. functions -@{ -*/ - -/** -@brief User function type to use with bt_ctf_trace_add_listener(). - -@param[in] element New element which is part of the trace class - hierarchy. -@param[in] data User data. - -@prenotnull{element} -*/ -typedef void (*bt_ctf_listener_cb)( - struct bt_ctf_ir_element *element, void *data); - -/** -@brief Adds the trace class modification listener \p listener to - the CTF IR trace class \p trace_class. - -Once you add \p listener to \p trace_class, whenever \p trace_class -is modified, \p listener is called with the new element and with -\p data (user data). - -@param[in] trace_class Trace class to which to add \p listener. -@param[in] listener Modification listener function. -@param[in] data User data. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{listener} -*/ -extern int bt_ctf_trace_add_listener(struct bt_ctf_trace *trace_class, - bt_ctf_listener_cb listener, void *data); - -/** -@brief Accepts the visitor \p visitor to visit the hierarchy of the - CTF IR trace class \p trace_class. - -This function traverses the hierarchy of \p trace_class in pre-order -and calls \p visitor on each element. - -The trace class itself is visited first, then, for each children stream -class, the stream class itself, and all its children event classes. - -@param[in] trace_class Trace class to visit. -@param[in] visitor Visiting function. -@param[in] data User data. -@returns 0 on success, or a negative value on error. - -@prenotnull{trace_class} -@prenotnull{visitor} -*/ -extern int bt_ctf_trace_visit(struct bt_ctf_trace *trace_class, - bt_ctf_ir_visitor visitor, void *data); - -/** @} */ - -/* - * 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); - -#ifdef __cplusplus -} -#endif - -#endif /* BABELTRACE_CTF_IR_TRACE_H */ +/* Pre-2.0 CTF writer backward compatibility */ +#include