From: Jérémie Galarneau Date: Wed, 16 Oct 2013 18:35:00 +0000 (-0400) Subject: Add public CTF Writer API headers X-Git-Tag: v1.2.0-rc1~39^2~31 X-Git-Url: http://git.efficios.com/?p=babeltrace.git;a=commitdiff_plain;h=46bd0f2b6f3056aa85ac827a85fd8c878f261313 Add public CTF Writer API headers Signed-off-by: Jérémie Galarneau Reviewed-by: Christian Babeux Reviewed-by: Mathieu Desnoyers Signed-off-by: Mathieu Desnoyers --- diff --git a/include/Makefile.am b/include/Makefile.am index 2d05ef94..e3681731 100644 --- a/include/Makefile.am +++ b/include/Makefile.am @@ -10,7 +10,13 @@ babeltraceinclude_HEADERS = \ babeltracectfinclude_HEADERS = \ babeltrace/ctf/events.h \ babeltrace/ctf/callbacks.h \ - babeltrace/ctf/iterator.h + babeltrace/ctf/iterator.h \ + babeltrace/ctf-writer/clock.h \ + babeltrace/ctf-writer/writer.h \ + babeltrace/ctf-writer/event-fields.h \ + babeltrace/ctf-writer/event-types.h \ + babeltrace/ctf-writer/event.h \ + babeltrace/ctf-writer/stream.h noinst_HEADERS = \ babeltrace/align.h \ diff --git a/include/babeltrace/ctf-writer/clock.h b/include/babeltrace/ctf-writer/clock.h new file mode 100644 index 00000000..7cfc073f --- /dev/null +++ b/include/babeltrace/ctf-writer/clock.h @@ -0,0 +1,166 @@ +#ifndef BABELTRACE_CTF_WRITER_CLOCK_H +#define BABELTRACE_CTF_WRITER_CLOCK_H + +/* + * BabelTrace - CTF Writer: Clock + * + * Copyright 2013 EfficiOS Inc. + * + * 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 + +#ifdef __cplusplus +extern "C" { +#endif + +struct bt_ctf_clock; + +/* + * bt_ctf_clock_create: create a clock. + * + * Allocate a new clock setting its reference count to 1. + * + * @param name Name of the clock (will be copied). + * + * Returns an allocated clock on success, NULL on error. + */ +extern struct bt_ctf_clock *bt_ctf_clock_create(const char *name); + +/* + * bt_ctf_clock_set_description: set a clock's description. + * + * Set the clock's description. The description appears in the clock's TSDL + * meta-data. + * + * @param clock Clock instance. + * @param desc Description of the clock. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_description(struct bt_ctf_clock *clock, + const char *desc); + +/* + * bt_ctf_clock_set_frequency: set a clock's frequency. + * + * Set the clock's frequency (Hz). + * + * @param clock Clock instance. + * @param freq Clock's frequency in Hz, defaults to 1 000 000 000 Hz (1ns). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_frequency(struct bt_ctf_clock *clock, + uint64_t freq); + +/* + * bt_ctf_clock_set_precision: set a clock's precision. + * + * Set the clock's precision. + * + * @param clock Clock instance. + * @param precision Clock's precision in clock ticks, defaults to 1. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_precision(struct bt_ctf_clock *clock, + uint64_t precision); + +/* + * bt_ctf_clock_set_offset_s: set a clock's offset in seconds. + * + * Set the clock's offset in seconds from POSIX.1 Epoch, 1970-01-01, + * defaults to 0. + * + * @param clock Clock instance. + * @param offset_s Clock's offset in seconds, defaults to 0. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_offset_s(struct bt_ctf_clock *clock, + uint64_t offset_s); + + +/* + * bt_ctf_clock_set_offset: set a clock's offset in ticks. + * + * Set the clock's offset in ticks from Epoch + offset_s. + * + * @param clock Clock instance. + * @param offset Clock's offset in ticks from Epoch + offset_s, defaults to 0. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_offset(struct bt_ctf_clock *clock, + uint64_t offset); + +/* + * bt_ctf_clock_set_is_absolute: set a clock's absolute attribute. + * + * A clock is absolute if the clock is a global reference across the trace's + * other clocks. + * + * @param clock Clock instance. + * @param is_absolute Clock's absolute attribute, defaults to FALSE. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_is_absolute(struct bt_ctf_clock *clock, + int is_absolute); + +/* + * bt_ctf_clock_set_time: set a clock's current time value. + * + * Set the current time in nanoseconds since the clock's origin (offset and + * offset_s attributes). The clock's value will be sampled as events are + * appended to a stream. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_clock_set_time(struct bt_ctf_clock *clock, uint64_t time); + +/* + * bt_ctf_clock_get and bt_ctf_clock_put: increment and decrement the + * refcount of the clock + * + * These functions ensure that the clock won't be destroyed when it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) has to be done to + * destroy a clock. + * + * When the clock refcount is decremented to 0 by a bt_ctf_clock_put, + * the clock is freed. + * + * @param clock Clock instance. + */ +extern void bt_ctf_clock_get(struct bt_ctf_clock *clock); +extern void bt_ctf_clock_put(struct bt_ctf_clock *clock); + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE_CTF_WRITER_CLOCK_H */ diff --git a/include/babeltrace/ctf-writer/event-fields.h b/include/babeltrace/ctf-writer/event-fields.h new file mode 100644 index 00000000..8d3190b4 --- /dev/null +++ b/include/babeltrace/ctf-writer/event-fields.h @@ -0,0 +1,218 @@ +#ifndef BABELTRACE_CTF_WRITER_EVENT_FIELDS_H +#define BABELTRACE_CTF_WRITER_EVENT_FIELDS_H + +/* + * BabelTrace - CTF Writer: Event Fields + * + * Copyright 2013 EfficiOS Inc. + * + * 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 + +#ifdef __cplusplus +extern "C" { +#endif + +struct bt_ctf_event_class; +struct bt_ctf_event; +struct bt_ctf_field; +struct bt_ctf_field_type; + +/* + * bt_ctf_field_create: create an instance of a field. + * + * Allocate a new field of the type described by the bt_ctf_field_type + * structure.The creation of a field sets its reference count to 1. + * + * @param type Field type to be instanciated. + * + * Returns an allocated field on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_field_create( + struct bt_ctf_field_type *type); + +/* + * bt_ctf_field_structure_get_field: get a structure's field. + * + * Get the structure's field corresponding to the provided field name. + * bt_ctf_field_put() must be called on the returned value. + * + * @param structure Structure field instance. + * @param name Name of the field in the provided structure. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_field_structure_get_field( + struct bt_ctf_field *structure, const char *name); + +/* + * bt_ctf_field_array_get_field: get an array's field at position "index". + * + * Return the array's field at position "index". bt_ctf_field_put() must be + * called on the returned value. + * + * @param array Array field instance. + * @param index Position of the array's desired element. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_field_array_get_field( + struct bt_ctf_field *array, uint64_t index); + +/* + * bt_ctf_field_sequence_set_length: set a sequence's length. + * + * Set the sequence's length field. + * + * @param sequence Sequence field instance. + * @param length_field Integer field instance indicating the sequence's length. + * + * Returns a field instance on success, NULL on error. + */ +extern int bt_ctf_field_sequence_set_length(struct bt_ctf_field *sequence, + struct bt_ctf_field *length_field); + +/* + * bt_ctf_field_sequence_get_field: get a sequence's field at position "index". + * + * Return the sequence's field at position "index". The sequence's length must + * have been set prior to calling this function using + * bt_ctf_field_sequence_set_length(). + * bt_ctf_field_put() must be called on the returned value. + * + * @param array Sequence field instance. + * @param index Position of the sequence's desired element. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_field_sequence_get_field( + struct bt_ctf_field *sequence, uint64_t index); + +/* + * bt_ctf_field_variant_get_field: get a variant's selected field. + * + * Return the variant's selected field. The "tag" field is the selector enum + * field. bt_ctf_field_put() must be called on the returned value. + * + * @param variant Variant field instance. + * @param tag Selector enumeration field. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_field_variant_get_field( + struct bt_ctf_field *variant, struct bt_ctf_field *tag); + +/* + * bt_ctf_field_enumeration_get_container: get an enumeration field's container. + * + * Return the enumeration's underlying container field (an integer). + * bt_ctf_field_put() must be called on the returned value. + * + * @param enumeration Enumeration field instance. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_field_enumeration_get_container( + struct bt_ctf_field *enumeration); + +/* + * bt_ctf_field_signed_integer_set_value: set a signed integer field's value + * + * Set a signed integer field's value. The value is checked to make sure it + * can be stored in the underlying field. + * + * @param integer Signed integer field instance. + * @param value Signed integer field value. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_signed_integer_set_value(struct bt_ctf_field *integer, + int64_t value); + +/* + * bt_ctf_field_unsigned_integer_set_value: set unsigned integer field's value + * + * Set an unsigned integer field's value. The value is checked to make sure it + * can be stored in the underlying field. + * + * @param integer Unsigned integer field instance. + * @param value Unsigned integer field value. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_unsigned_integer_set_value(struct bt_ctf_field *integer, + uint64_t value); + +/* + * bt_ctf_field_floating_point_set_value: set a floating point field's value + * + * Set a floating point field's value. The underlying type may not support the + * double's full precision. + * + * @param floating_point Floating point field instance. + * @param value Floating point field value. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_floating_point_set_value( + struct bt_ctf_field *floating_point, + double value); + +/* + * bt_ctf_field_string_set_value: set a string field's value + * + * Set a string field's value. + * + * @param string String field instance. + * @param value String field value (will be copied). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_string_set_value(struct bt_ctf_field *string, + const char *value); + +/* + * bt_ctf_field_get and bt_ctf_field_put: increment and decrement the + * field's reference count. + * + * These functions ensure that the field won't be destroyed when it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy a field. + * + * When the field's reference count is decremented to 0 by a bt_ctf_field_put, + * the field is freed. + * + * @param field Field instance. + */ +extern void bt_ctf_field_get(struct bt_ctf_field *field); +extern void bt_ctf_field_put(struct bt_ctf_field *field); + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE_CTF_WRITER_EVENT_FIELDS_H */ diff --git a/include/babeltrace/ctf-writer/event-types.h b/include/babeltrace/ctf-writer/event-types.h new file mode 100644 index 00000000..cf43ed61 --- /dev/null +++ b/include/babeltrace/ctf-writer/event-types.h @@ -0,0 +1,353 @@ +#ifndef BABELTRACE_CTF_WRITER_EVENT_TYPES_H +#define BABELTRACE_CTF_WRITER_EVENT_TYPES_H + +/* + * BabelTrace - CTF Writer: Event Types + * + * Copyright 2013 EfficiOS Inc. + * + * 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 + +#ifdef __cplusplus +extern "C" { +#endif + +struct bt_ctf_event_class; +struct bt_ctf_event; +struct bt_ctf_field_type; + +enum bt_ctf_integer_base { + BT_CTF_INTEGER_BASE_UNKNOWN = -1, + BT_CTF_INTEGER_BASE_BINARY = 2, + BT_CTF_INTEGER_BASE_OCTAL = 8, + BT_CTF_INTEGER_BASE_DECIMAL = 10, + BT_CTF_INTEGER_BASE_HEXADECIMAL = 16, +}; + +/* + * bt_ctf_field_type_integer_create: create an integer field type. + * + * Allocate a new integer field type of the given size. The creation of a field + * type sets its reference count to 1. + * + * @param size Integer field type size/length in bits. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create( + unsigned int size); + +/* + * bt_ctf_field_type_integer_set_signed: set an integer type's signedness. + * + * Set an integer type's signedness attribute. + * + * @param integer Integer type. + * @param is_signed Integer's signedness, defaults to FALSE. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_integer_set_signed( + struct bt_ctf_field_type *integer, int is_signed); + +/* + * bt_ctf_field_type_integer_set_base: set an integer type's base. + * + * Set an integer type's base used to pretty-print the resulting trace. + * + * @param integer Integer type. + * @param base Integer base, defaults to BT_CTF_INTEGER_BASE_DECIMAL. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_integer_set_base( + struct bt_ctf_field_type *integer, + enum bt_ctf_integer_base base); + +/* + * bt_ctf_field_type_integer_set_encoding: set an integer type's encoding. + * + * An integer encoding may be set to signal that the integer must be printed as + * a text character. + * + * @param integer Integer type. + * @param encoding Integer output encoding, defaults to CTF_STRING_ENCODING_NONE + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_integer_set_encoding( + struct bt_ctf_field_type *integer, + enum ctf_string_encoding encoding); + +/* + * bt_ctf_field_type_enumeration_create: create an enumeration field type. + * + * Allocate a new enumeration field type with the given underlying type. The + * creation of a field type sets its reference count to 1. + * The resulting enumeration will share the integer_container_type's ownership + * by increasing its reference count. + * + * @param integer_container_type Underlying integer type of the enumeration + * type. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create( + struct bt_ctf_field_type *integer_container_type); + +/* + * bt_ctf_field_type_enumeration_add_mapping: add an enumeration mapping. + * + * Add a mapping to the enumeration. The range's values are inclusive. + * + * @param enumeration Enumeration type. + * @param string Enumeration mapping name (will be copied). + * @param range_start Enumeration mapping range start. + * @param range_end Enumeration mapping range end. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_enumeration_add_mapping( + struct bt_ctf_field_type *enumeration, const char *string, + int64_t range_start, int64_t range_end); + +/* + * bt_ctf_field_type_floating_point_create: create a floating point field type. + * + * Allocate a new floating point field type. The creation of a field type sets + * its reference count to 1. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void); + +/* + * bt_ctf_field_type_floating_point_set_exponent_digits: set exponent digit + * count. + * + * Set the number of exponent digits to use to store the floating point field. + * The only values currently supported are FLT_EXP_DIG and DBL_EXP_DIG. + * + * @param floating_point Floating point type. + * @param exponent_digits Number of digits to allocate to the exponent (defaults + * to FLT_EXP_DIG). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_floating_point_set_exponent_digits( + struct bt_ctf_field_type *floating_point, + unsigned int exponent_digits); + +/* + * bt_ctf_field_type_floating_point_set_mantissa_digits: set mantissa digit + * count. + * + * Set the number of mantissa digits to use to store the floating point field. + * The only values currently supported are FLT_MANT_DIG and DBL_MANT_DIG. + * + * @param floating_point Floating point type. + * @param mantissa_digits Number of digits to allocate to the mantissa (defaults + * to FLT_MANT_DIG). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_floating_point_set_mantissa_digits( + struct bt_ctf_field_type *floating_point, + unsigned int mantissa_digits); + +/* + * bt_ctf_field_type_structure_create: create a structure field type. + * + * Allocate a new structure field type. The creation of a field type sets + * its reference count to 1. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void); + +/* + * bt_ctf_field_type_structure_add_field: add a field to a structure. + * + * Add a field of type "field_type" to the structure. The structure will share + * field_type's ownership by increasing its reference count. + * + * @param structure Structure type. + * @param field_type Type of the field to add to the structure type. + * @param field_name Name of the structure's new field (will be copied). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_structure_add_field( + struct bt_ctf_field_type *structure, + struct bt_ctf_field_type *field_type, + const char *field_name); + +/* + * bt_ctf_field_type_variant_create: create a variant field type. + * + * Allocate a new variant field type. The creation of a field type sets + * its reference count to 1. tag_name must be the name of an enumeration + * field declared in the same scope as this variant. + * + * @param enum_tag Type of the variant's tag/selector (must be an enumeration). + * @param tag_name Name of the variant's tag/selector field (will be copied). + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create( + struct bt_ctf_field_type *enum_tag, + const char *tag_name); + +/* + * bt_ctf_field_type_variant_add_field: add a field to a variant. + * + * Add a field of type "field_type" to the variant.The variant will share + * field_type's ownership by increasing its reference count. The "field_name" + * will be copied. field_name must match a mapping in the tag/selector + * enumeration. + * + * @param variant Variant type. + * @param field_type Type of the variant type's new field. + * @param field_name Name of the variant type's new field (will be copied). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_variant_add_field( + struct bt_ctf_field_type *variant, + struct bt_ctf_field_type *field_type, + const char *field_name); + +/* + * bt_ctf_field_type_array_create: create an array field type. + * + * Allocate a new array field type. The creation of a field type sets + * its reference count to 1. + * + * @param element_type Array's element type. + * @oaram length Array type's length. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_array_create( + struct bt_ctf_field_type *element_type, + unsigned int length); + +/* + * bt_ctf_field_type_sequence_create: create a sequence field type. + * + * Allocate a new sequence field type. The creation of a field type sets + * its reference count to 1. "length_field_name" must match an integer field + * declared in the same scope. + * + * @param element_type Sequence's element type. + * @param length_field_name Name of the sequence's length field (will be + * copied). + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create( + struct bt_ctf_field_type *element_type, + const char *length_field_name); + +/* + * bt_ctf_field_type_string_create: create a string field type. + * + * Allocate a new string field type. The creation of a field type sets + * its reference count to 1. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void); + +/* + * bt_ctf_field_type_string_set_encoding: set a string type's encoding. + * + * Set the string type's encoding. + * + * @param string String type. + * @param encoding String field encoding, default CTF_STRING_ENCODING_ASCII. + * Valid values are CTF_STRING_ENCODING_ASCII and CTF_STRING_ENCODING_UTF8. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_string_set_encoding( + struct bt_ctf_field_type *string, + enum ctf_string_encoding encoding); + +/* + * bt_ctf_field_type_set_alignment: set a field type's alignment. + * + * Set the field type's alignment. + * + * @param type Field type. + * @param alignment Type's alignment. Defaults to 1 (bit-aligned). However, + * some types, such as structures and string, may impose other alignment + * constraints. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *type, + unsigned int alignment); + +/* + * bt_ctf_field_type_set_byte_order: set a field type's byte order. + * + * Set the field type's byte order. + * + * @param type Field type. + * @param byte_order Field type's byte order. Defaults to + * BT_CTF_BYTE_ORDER_NATIVE, the host machine's endianness. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_field_type_set_byte_order(struct bt_ctf_field_type *type, + enum bt_ctf_byte_order byte_order); + +/* + * bt_ctf_field_type_get and bt_ctf_field_type_put: increment and decrement + * the field type's reference count. + * + * These functions ensure that the field type won't be destroyed while it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy a field type. + * + * When the field type's reference count is decremented to 0 by a + * bt_ctf_field_type_put, the field type is freed. + * + * @param type Field type. + */ +extern void bt_ctf_field_type_get(struct bt_ctf_field_type *type); +extern void bt_ctf_field_type_put(struct bt_ctf_field_type *type); + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE_CTF_WRITER_EVENT_TYPES_H */ diff --git a/include/babeltrace/ctf-writer/event.h b/include/babeltrace/ctf-writer/event.h new file mode 100644 index 00000000..d8ef9d92 --- /dev/null +++ b/include/babeltrace/ctf-writer/event.h @@ -0,0 +1,154 @@ +#ifndef BABELTRACE_CTF_WRITER_EVENT_H +#define BABELTRACE_CTF_WRITER_EVENT_H + +/* + * BabelTrace - CTF Writer: Event + * + * Copyright 2013 EfficiOS Inc. + * + * 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 + */ + +#ifdef __cplusplus +extern "C" { +#endif + +struct bt_ctf_event_class; +struct bt_ctf_event; +struct bt_ctf_field; +struct bt_ctf_field_type; + +/* + * bt_ctf_event_class_create: create an event class. + * + * Allocate a new event class of the given name. The creation of an event class + * sets its reference count to 1. + * + * @param name Event class name (will be copied). + * + * Returns an allocated event class on success, NULL on error. + */ +extern struct bt_ctf_event_class *bt_ctf_event_class_create(const char *name); + +/* + * bt_ctf_event_class_add_field: add a field to an event class. + * + * Add a field of type "type" to the event class. The event class will share + * type's ownership by increasing its reference count. The "name" will be + * copied. + * + * @param event_class Event class. + * @param type Field type to add to the event class. + * @param name Name of the new field. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_event_class_add_field(struct bt_ctf_event_class *event_class, + struct bt_ctf_field_type *type, + const char *name); + +/* + * bt_ctf_event_class__get and bt_ctf_event_class_put: increment and decrement + * the event class' reference count. + * + * These functions ensure that the event class won't be destroyed while it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy an event class. + * + * When the event class' reference count is decremented to 0 by a + * bt_ctf_event_class_put, the event class is freed. + * + * @param event_class Event class. + */ +extern void bt_ctf_event_class_get(struct bt_ctf_event_class *event_class); +extern void bt_ctf_event_class_put(struct bt_ctf_event_class *event_class); + +/* + * bt_ctf_event_create: instanciate an event. + * + * Allocate a new event of the given event class. The creation of an event + * sets its reference count to 1. Each instance shares the ownership of the + * event class using its reference count. + * + * @param event_class Event class. + * + * Returns an allocated field type on success, NULL on error. + */ +extern struct bt_ctf_event *bt_ctf_event_create( + struct bt_ctf_event_class *event_class); + +/* + * bt_ctf_event_set_payload: set an event's field. + * + * Set a manually allocated field as an event's payload. The event will share + * the field's ownership by using its reference count. + * bt_ctf_field_put() must be called on the returned value. + * + * @param event Event instance. + * @param name Event field name. + * @param value Instance of a field whose type corresponds to the event's field. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_event_set_payload(struct bt_ctf_event *event, + const char *name, + struct bt_ctf_field *value); + +/* + * bt_ctf_event_get_payload: get an event's field. + * + * Returns the field matching "name". bt_ctf_field_put() must be called on the + * returned value. + * + * @param event Event instance. + * @param name Event field name. + * + * Returns a field instance on success, NULL on error. + */ +extern struct bt_ctf_field *bt_ctf_event_get_payload(struct bt_ctf_event *event, + const char *name); + +/* + * bt_ctf_event_get and bt_ctf_event_put: increment and decrement + * the event's reference count. + * + * These functions ensure that the event won't be destroyed while it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy an event. + * + * When the event's reference count is decremented to 0 by a + * bt_ctf_event_put, the event is freed. + * + * @param event Event instance. + */ +extern void bt_ctf_event_get(struct bt_ctf_event *event); +extern void bt_ctf_event_put(struct bt_ctf_event *event); + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE_CTF_WRITER_EVENT_H */ diff --git a/include/babeltrace/ctf-writer/stream.h b/include/babeltrace/ctf-writer/stream.h new file mode 100644 index 00000000..9229f771 --- /dev/null +++ b/include/babeltrace/ctf-writer/stream.h @@ -0,0 +1,169 @@ +#ifndef BABELTRACE_CTF_WRITER_STREAM_H +#define BABELTRACE_CTF_WRITER_STREAM_H + +/* + * BabelTrace - CTF Writer: Stream + * + * Copyright 2013 EfficiOS Inc. + * + * 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 + */ + +#ifdef __cplusplus +extern "C" { +#endif + +struct bt_ctf_event; +struct bt_ctf_event_class; +struct bt_ctf_stream_class; +struct bt_ctf_stream; +struct bt_ctf_clock; + +/* + * bt_ctf_stream_class_create: create a stream class. + * + * Allocate a new stream class of the given name. The creation of an event class + * sets its reference count to 1. + * + * @param name Stream name. + * + * Returns an allocated stream class on success, NULL on error. + */ +extern struct bt_ctf_stream_class *bt_ctf_stream_class_create(const char *name); + +/* + * bt_ctf_stream_class_set_clock: assign a clock to a stream class. + * + * Assign a clock to a stream class. This clock will be sampled each time an + * event is appended to an instance of this stream class. + * + * @param stream_class Stream class. + * @param clock Clock to assign to the provided stream class. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_stream_class_set_clock( + struct bt_ctf_stream_class *stream_class, + struct bt_ctf_clock *clock); + +/* + * bt_ctf_stream_class_set_clock: assign a clock to a stream class. + * + * Add an event class to a stream class. New events can be added even after a + * stream has beem instanciated and events have been appended. However, a stream + * will not accept events of a class that has not been registered beforehand. + * The stream class will share the ownership of "event_class" by incrementing + * its reference count. + * + * @param stream_class Stream class. + * @param event_class Event class to add to the provided stream class. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_stream_class_add_event_class( + struct bt_ctf_stream_class *stream_class, + struct bt_ctf_event_class *event_class); + +/* + * bt_ctf_stream_class_get and bt_ctf_stream_class_put: increment and + * decrement the stream class' reference count. + * + * These functions ensure that the stream class won't be destroyed while it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy a stream class. + * + * When the stream class' reference count is decremented to 0 by a + * bt_ctf_stream_class_put, the stream class is freed. + * + * @param stream_class Stream class. + */ +extern void bt_ctf_stream_class_get(struct bt_ctf_stream_class *stream_class); +extern void bt_ctf_stream_class_put(struct bt_ctf_stream_class *stream_class); + +/* + * bt_ctf_stream_append_discarded_events: increment discarded events count. + * + * Increase the current packet's discarded event count. + * + * @param stream Stream instance. + * @param event_count Number of discarded events to add to the stream's current + * packet. + * + * Returns 0 on success, a negative value on error. + */ +extern void bt_ctf_stream_append_discarded_events(struct bt_ctf_stream *stream, + uint64_t event_count); + +/* + * bt_ctf_stream_append_event: append an event to the stream. + * + * Append "event" to the stream's current packet. The stream's associated clock + * will be sampled during this call. The event shall not be modified after + * being appended to a stream. The stream will share the event's ownership by + * incrementing its reference count. The current packet is not flushed to disk + * until the next call to bt_ctf_stream_flush. + * + * @param stream Stream instance. + * @param event Event instance to append to the stream's current packet. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_stream_append_event(struct bt_ctf_stream *stream, + struct bt_ctf_event *event); + +/* + * bt_ctf_stream_flush: flush a stream. + * + * The stream's current packet's events will be flushed to disk. Events + * subsequently appended to the stream will be added to a new packet. + * + * @param stream Stream instance. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_stream_flush(struct bt_ctf_stream *stream); + +/* + * bt_ctf_stream_get and bt_ctf_stream_put: increment and decrement the + * stream's reference count. + * + * These functions ensure that the stream won't be destroyed while it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy a stream. + * + * When the stream's reference count is decremented to 0 by a + * bt_ctf_stream_put, the stream is freed. + * + * @param stream Stream instance. + */ +extern void bt_ctf_stream_get(struct bt_ctf_stream *stream); +extern void bt_ctf_stream_put(struct bt_ctf_stream *stream); + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE_CTF_WRITER_STREAM_H */ diff --git a/include/babeltrace/ctf-writer/writer.h b/include/babeltrace/ctf-writer/writer.h new file mode 100644 index 00000000..68031ac3 --- /dev/null +++ b/include/babeltrace/ctf-writer/writer.h @@ -0,0 +1,164 @@ +#ifndef BABELTRACE_CTF_WRITER_WRITER_H +#define BABELTRACE_CTF_WRITER_WRITER_H + +/* + * BabelTrace - CTF Writer: Writer + * + * Copyright 2013 EfficiOS Inc. + * + * 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 + */ + +#ifdef __cplusplus +extern "C" { +#endif + +struct bt_ctf_writer; +struct bt_ctf_stream; +struct bt_ctf_stream_class; +struct bt_ctf_clock; + +enum bt_ctf_byte_order { + BT_CTF_BYTE_ORDER_NATIVE = 0, + BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, + BT_CTF_BYTE_ORDER_BIG_ENDIAN, + BT_CTF_BYTE_ORDER_NETWORK, +}; + +/* + * bt_ctf_writer_create: create a writer instance. + * + * Allocate a new writer that will produce a trace in the given path. + * The creation of a writer sets its reference count to 1. + * + * @param path Path to the trace's containing folder (string is copied). + * + * Returns an allocated writer on success, NULL on error. + */ +extern struct bt_ctf_writer *bt_ctf_writer_create(const char *path); + +/* + * bt_ctf_writer_create_stream: create a stream instance. + * + * Allocate a new stream instance and register it to the writer. The creation of + * a stream sets its reference count to 1. + * + * @param writer Writer instance. + * @param stream_class Stream class to instantiate. + * + * Returns an allocated writer on success, NULL on error. + */ +extern struct bt_ctf_stream *bt_ctf_writer_create_stream( + struct bt_ctf_writer *writer, + struct bt_ctf_stream_class *stream_class); + +/* + * bt_ctf_writer_add_environment_field: add an environment field to the trace. + * + * Add an environment field to the trace. The name and value parameters are + * copied. + * + * @param writer Writer instance. + * @param name Name of the environment field (will be copied). + * @param value Value of the environment field (will be copied). + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_writer_add_environment_field(struct bt_ctf_writer *writer, + const char *name, + const char *value); + +/* + * bt_ctf_writer_add_clock: add a clock to the trace. + * + * Add a clock to the trace. Clocks assigned to stream classes must be + * registered to the writer. + * + * @param writer Writer instance. + * @param clock Clock to add to the trace. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_writer_add_clock(struct bt_ctf_writer *writer, + struct bt_ctf_clock *clock); + +/* + * bt_ctf_writer_get_metadata_string: get meta-data string. + * + * Get the trace's TSDL meta-data. The caller assumes the ownership of the + * returned string. + * + * @param writer Writer instance. + * + * Returns the metadata string on success, NULL on error. + */ +extern char *bt_ctf_writer_get_metadata_string(struct bt_ctf_writer *writer); + +/* + * bt_ctf_writer_flush_metadata: flush the trace's metadata to disk. + * + * Flush the trace's metadata to the metadata file. Note that the metadata will + * be flushed automatically when the Writer instance is released (last call to + * bt_ctf_writer_put). + * + * @param writer Writer instance. + */ +extern void bt_ctf_writer_flush_metadata(struct bt_ctf_writer *writer); + +/* + * bt_ctf_writer_set_byte_order: set a field type's byte order. + * + * Set the trace's byte order. Defaults to BT_CTF_BYTE_ORDER_NATIVE, + * the host machine's endianness. + * + * @param writer Writer instance. + * @param byte_order Trace's byte order. + * + * Returns 0 on success, a negative value on error. + */ +extern int bt_ctf_writer_set_byte_order(struct bt_ctf_writer *writer, + enum bt_ctf_byte_order byte_order); + +/* + * bt_ctf_writer_get and bt_ctf_writer_put: increment and decrement the + * writer's reference count. + * + * These functions ensure that the writer won't be destroyed while it + * is in use. The same number of get and put (plus one extra put to + * release the initial reference done at creation) have to be done to + * destroy a writer. + * + * When the writer's reference count is decremented to 0 by a + * bt_ctf_writer_put, the writer is freed. + * + * @param writer Writer instance. + */ +extern void bt_ctf_writer_get(struct bt_ctf_writer *writer); +extern void bt_ctf_writer_put(struct bt_ctf_writer *writer); + +#ifdef __cplusplus +} +#endif + +#endif /* BABELTRACE_CTF_WRITER_WRITER_H */