X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=include%2Fbabeltrace%2Fctf-ir%2Ffield-types.h;h=61dc291ae560b1555a27d06d80987b1247103c27;hb=d41cff384b157063354895e81f85baf98775f64e;hp=b7e305456dabe993b27fad7b011471d112b37ae4;hpb=c3c35de4da25b506dd423e74706ee302cc0d7e39;p=babeltrace.git diff --git a/include/babeltrace/ctf-ir/field-types.h b/include/babeltrace/ctf-ir/field-types.h index b7e30545..61dc291a 100644 --- a/include/babeltrace/ctf-ir/field-types.h +++ b/include/babeltrace/ctf-ir/field-types.h @@ -30,6 +30,7 @@ * http://www.efficios.com/ctf */ +#include #include #include @@ -97,49 +98,49 @@ The standard CTF field types are: CTF IR field which you can create from this field type - #BT_CTF_TYPE_ID_INTEGER + #BT_CTF_FIELD_TYPE_ID_INTEGER \ref ctfirintfieldtype \ref ctfirintfield - #BT_CTF_TYPE_ID_FLOAT + #BT_CTF_FIELD_TYPE_ID_FLOAT \ref ctfirfloatfieldtype \ref ctfirfloatfield - #BT_CTF_TYPE_ID_ENUM + #BT_CTF_FIELD_TYPE_ID_ENUM \ref ctfirenumfieldtype \ref ctfirenumfield - #BT_CTF_TYPE_ID_STRING + #BT_CTF_FIELD_TYPE_ID_STRING \ref ctfirstringfieldtype \ref ctfirstringfield - #BT_CTF_TYPE_ID_STRUCT + #BT_CTF_FIELD_TYPE_ID_STRUCT \ref ctfirstructfieldtype \ref ctfirstructfield - #BT_CTF_TYPE_ID_ARRAY + #BT_CTF_FIELD_TYPE_ID_ARRAY \ref ctfirarrayfieldtype \ref ctfirarrayfield - #BT_CTF_TYPE_ID_SEQUENCE + #BT_CTF_FIELD_TYPE_ID_SEQUENCE \ref ctfirseqfieldtype \ref ctfirseqfield - #BT_CTF_TYPE_ID_VARIANT + #BT_CTF_FIELD_TYPE_ID_VARIANT \ref ctfirvarfieldtype \ref ctfirvarfield Each field type has its own type ID (see -#bt_ctf_type_id). You get the type ID of a field type object +#bt_ctf_field_type_id). You get the type ID of a field type object with bt_ctf_field_type_get_type_id(). You can get a deep copy of a field type with bt_ctf_field_type_copy(). @@ -206,21 +207,21 @@ struct bt_ctf_field_type_enumeration_mapping_iterator; /* * Babeltrace 1.x enumerations that were also used in CTF writer's API. * They are left here for backward compatibility reasons, but - * enum bt_ctf_type_id and enum bt_ctf_string_encoding should be used + * enum bt_ctf_field_type_id and enum bt_ctf_string_encoding should be used * in new code. Both new enumerations are compatible with their legacy * counterpart. */ enum ctf_type_id { - CTF_TYPE_UNKNOWN = 0, - CTF_TYPE_INTEGER, - CTF_TYPE_FLOAT, - CTF_TYPE_ENUM, - CTF_TYPE_STRING, - CTF_TYPE_STRUCT, - CTF_TYPE_UNTAGGED_VARIANT, - CTF_TYPE_VARIANT, - CTF_TYPE_ARRAY, - CTF_TYPE_SEQUENCE, + CTF_TYPE_UNKNOWN = -1, + CTF_TYPE_INTEGER = 0, + CTF_TYPE_FLOAT = 1, + CTF_TYPE_ENUM = 2, + CTF_TYPE_STRING = 3, + CTF_TYPE_STRUCT = 4, + CTF_TYPE_UNTAGGED_VARIANT = 5, + CTF_TYPE_VARIANT = 5, + CTF_TYPE_ARRAY = 6, + CTF_TYPE_SEQUENCE = 7, NR_CTF_TYPES, }; @@ -275,37 +276,33 @@ enum bt_ctf_scope { /** @brief Type ID of a @ft. */ -enum bt_ctf_type_id { +enum bt_ctf_field_type_id { /// Unknown, used for errors. - BT_CTF_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, + BT_CTF_FIELD_TYPE_ID_UNKNOWN = CTF_TYPE_UNKNOWN, /// \ref ctfirintfieldtype - BT_CTF_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, + BT_CTF_FIELD_TYPE_ID_INTEGER = CTF_TYPE_INTEGER, /// \ref ctfirfloatfieldtype - BT_CTF_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, + BT_CTF_FIELD_TYPE_ID_FLOAT = CTF_TYPE_FLOAT, /// \ref ctfirenumfieldtype - BT_CTF_TYPE_ID_ENUM = CTF_TYPE_ENUM, + BT_CTF_FIELD_TYPE_ID_ENUM = CTF_TYPE_ENUM, /// \ref ctfirstringfieldtype - BT_CTF_TYPE_ID_STRING = CTF_TYPE_STRING, + BT_CTF_FIELD_TYPE_ID_STRING = CTF_TYPE_STRING, /// \ref ctfirstructfieldtype - BT_CTF_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, - - /// @cond DOCUMENT - BT_CTF_TYPE_ID_UNTAGGED_VARIANT = CTF_TYPE_UNTAGGED_VARIANT, - /// @endcond + BT_CTF_FIELD_TYPE_ID_STRUCT = CTF_TYPE_STRUCT, /// \ref ctfirarrayfieldtype - BT_CTF_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, + BT_CTF_FIELD_TYPE_ID_ARRAY = CTF_TYPE_ARRAY, /// \ref ctfirseqfieldtype - BT_CTF_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, + BT_CTF_FIELD_TYPE_ID_SEQUENCE = CTF_TYPE_SEQUENCE, /// \ref ctfirvarfieldtype - BT_CTF_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, + BT_CTF_FIELD_TYPE_ID_VARIANT = CTF_TYPE_VARIANT, /// Number of enumeration entries. BT_CTF_NR_TYPE_IDS = NR_CTF_TYPES, @@ -316,12 +313,12 @@ enum bt_ctf_type_id { @param[in] field_type Field type of which to get the type ID. @returns Type ID of \p field_type, - or #BT_CTF_TYPE_ID_UNKNOWN on error. + or #BT_CTF_FIELD_TYPE_ID_UNKNOWN on error. @prenotnull{field_type} @postrefcountsame{field_type} -@sa #bt_ctf_type_id: CTF IR field type ID. +@sa #bt_ctf_field_type_id: CTF IR field type ID. @sa bt_ctf_field_type_is_integer(): Returns whether or not a given field type is a @intft. @sa bt_ctf_field_type_is_floating_point(): Returns whether or not a @@ -339,15 +336,15 @@ enum bt_ctf_type_id { @sa bt_ctf_field_type_is_variant(): Returns whether or not a given field type is a @varft. */ -extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id( +extern enum bt_ctf_field_type_id bt_ctf_field_type_get_type_id( struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @intft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is an integer field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is an integer field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @prenotnull{field_type} @@ -356,14 +353,15 @@ extern enum bt_ctf_type_id bt_ctf_field_type_get_type_id( @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_integer( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @floatft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a floating point - number field type, +@returns #BT_TRUE if \p field_type is a floating point + #BT_FALSE field type, or 0 otherwise (including if \p field_type is \c NULL). @@ -372,14 +370,15 @@ extern int bt_ctf_field_type_is_integer(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_floating_point( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @enumft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is an enumeration field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is an enumeration field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -387,14 +386,15 @@ extern int bt_ctf_field_type_is_floating_point(struct bt_ctf_field_type *field_t @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_enumeration( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @stringft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a string field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a string field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -402,14 +402,15 @@ extern int bt_ctf_field_type_is_enumeration(struct bt_ctf_field_type *field_type @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_string( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @structft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a structure field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a structure field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -417,14 +418,15 @@ extern int bt_ctf_field_type_is_string(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_structure( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @arrayft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is an array field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is an array field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -432,14 +434,15 @@ extern int bt_ctf_field_type_is_structure(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_array( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @seqft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a sequence field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a sequence field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -447,14 +450,15 @@ extern int bt_ctf_field_type_is_array(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_sequence( + struct bt_ctf_field_type *field_type); /** @brief Returns whether or not the @ft \p field_type is a @varft. @param[in] field_type Field type to check (can be \c NULL). -@returns 1 if \p field_type is a variant field type, - or 0 otherwise (including if \p field_type is +@returns #BT_TRUE if \p field_type is a variant field type, + or #BT_FALSE otherwise (including if \p field_type is \c NULL). @postrefcountsame{field_type} @@ -462,7 +466,8 @@ extern int bt_ctf_field_type_is_sequence(struct bt_ctf_field_type *field_type); @sa bt_ctf_field_type_get_type_id(): Returns the type ID of a given field type. */ -extern int bt_ctf_field_type_is_variant(struct bt_ctf_field_type *field_type); +extern bt_bool bt_ctf_field_type_is_variant( + struct bt_ctf_field_type *field_type); /** @} */ @@ -487,6 +492,12 @@ enum bt_ctf_byte_order { /// Native (default) byte order. BT_CTF_BYTE_ORDER_NATIVE = 0, + /** + No byte order; the initial native byte order of a + \link ctfirtraceclass CTF IR trace class\endlink. + */ + BT_CTF_BYTE_ORDER_NONE, + /// Little-endian. BT_CTF_BYTE_ORDER_LITTLE_ENDIAN, @@ -708,8 +719,8 @@ An integer field type has the following properties: Signedness of the described integer fields Unsigned - bt_ctf_field_type_integer_get_signed() - bt_ctf_field_type_integer_set_signed() + bt_ctf_field_type_integer_is_signed() + bt_ctf_field_type_integer_set_is_signed() Preferred display base of the described @@ -829,21 +840,27 @@ extern int bt_ctf_field_type_integer_set_size( @param[in] int_field_type Integer field type which describes the integer fields of which to get the signedness. -@returns 1 if the integer fields described by - \p int_field_type are signed, 0 if they - are unsigned, or a negative value on - error. +@returns #BT_TRUE if the integer fields described by + \p int_field_type are signed, #BT_FALSE if they + are unsigned. @prenotnull{int_field_type} @preisintft{int_field_type} @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_set_signed(): Sets the signedness of the +@sa bt_ctf_field_type_integer_set_is_signed(): Sets the signedness of the integer fields described by a given integer field type. */ +extern bt_bool bt_ctf_field_type_integer_is_signed( + struct bt_ctf_field_type *int_field_type); + +/** @cond DOCUMENT */ + extern int bt_ctf_field_type_integer_get_signed( struct bt_ctf_field_type *int_field_type); +/** @endcond */ + /** @brief Sets whether or not the @intfields described by the @intft \p int_field_type are signed. @@ -852,21 +869,23 @@ extern int bt_ctf_field_type_integer_get_signed( integer fields of which to set the signedness. @param[in] is_signed Signedness of the integer fields - described by \p int_field_type; 0 means - \em unsigned, 1 means \em signed. + described by \p int_field_type; #BT_FALSE means + \em unsigned, #BT_TRUE means \em signed. @returns 0 on success, or a negative value on error. @prenotnull{int_field_type} @preisintft{int_field_type} @prehot{int_field_type} -@pre \p is_signed is 0 or 1. @postrefcountsame{int_field_type} -@sa bt_ctf_field_type_integer_get_signed(): Returns the signedness of +@sa bt_ctf_field_type_integer_is_signed(): Returns the signedness of the integer fields described by a given integer field type. */ -extern int bt_ctf_field_type_integer_set_signed( - struct bt_ctf_field_type *int_field_type, int is_signed); +extern int bt_ctf_field_type_integer_set_is_signed( + struct bt_ctf_field_type *int_field_type, bt_bool is_signed); + +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_integer_set_signed bt_ctf_field_type_integer_set_is_signed /** @brief Returns the preferred display base (radix) of the @intfields @@ -1233,7 +1252,7 @@ An enumeration mapping has: value, both included in the range. You can add a mapping to an enumeration field type with -bt_ctf_field_type_enumeration_add_mapping() or +bt_ctf_field_type_enumeration_add_mapping_signed() or bt_ctf_field_type_enumeration_add_mapping_unsigned(), depending on the signedness of the wrapped @intft. @@ -1330,7 +1349,7 @@ struct bt_ctf_field_type *bt_ctf_field_type_enumeration_get_container_type( @preisenumft{enum_field_type} @postrefcountsame{enum_field_type} */ -extern int bt_ctf_field_type_enumeration_get_mapping_count( +extern int64_t bt_ctf_field_type_enumeration_get_mapping_count( struct bt_ctf_field_type *enum_field_type); /** @@ -1372,7 +1391,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_signed( - struct bt_ctf_field_type *enum_field_type, int index, + struct bt_ctf_field_type *enum_field_type, uint64_t index, const char **name, int64_t *range_begin, int64_t *range_end); /** @@ -1414,7 +1433,7 @@ On success, \p enum_field_type remains the sole owner of \p *name. at a given index. */ extern int bt_ctf_field_type_enumeration_get_mapping_unsigned( - struct bt_ctf_field_type *enum_field_type, int index, + struct bt_ctf_field_type *enum_field_type, uint64_t index, const char **name, uint64_t *range_begin, uint64_t *range_end); @@ -1551,6 +1570,7 @@ A mapping in \p enum_field_type can exist with the name \p name. @prenotnull{enum_field_type} @prenotnull{name} +@prehot{enum_field_type} @preisenumft{enum_field_type} @pre The wrapped @intft of \p enum_field_type is signed. @pre \p range_end is greater than or equal to \p range_begin. @@ -1559,10 +1579,13 @@ A mapping in \p enum_field_type can exist with the name \p name. @sa bt_ctf_field_type_enumeration_add_mapping_unsigned(): Adds an unsigned mapping to a given enumeration field type. */ -extern int bt_ctf_field_type_enumeration_add_mapping( +extern int bt_ctf_field_type_enumeration_add_mapping_signed( struct bt_ctf_field_type *enum_field_type, const char *name, int64_t range_begin, int64_t range_end); +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_enumeration_add_mapping bt_ctf_field_type_enumeration_add_mapping_signed + /** @brief Adds a mapping to the @enumft \p enum_field_type which maps the name \p name to the unsigned @@ -1589,12 +1612,13 @@ A mapping in \p enum_field_type can exist with the name \p name. @prenotnull{enum_field_type} @prenotnull{name} +@prehot{enum_field_type} @preisenumft{enum_field_type} @pre The wrapped @intft of \p enum_field_type is unsigned. @pre \p range_end is greater than or equal to \p range_begin. @postrefcountsame{enum_field_type} -@sa bt_ctf_field_type_enumeration_add_mapping(): Adds a signed +@sa bt_ctf_field_type_enumeration_add_mapping_signed(): Adds a signed mapping to a given enumeration field type. */ extern int bt_ctf_field_type_enumeration_add_mapping_unsigned( @@ -1913,7 +1937,7 @@ extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void); @preisstructft{struct_field_type} @postrefcountsame{struct_field_type} */ -extern int bt_ctf_field_type_structure_get_field_count( +extern int64_t bt_ctf_field_type_structure_get_field_count( struct bt_ctf_field_type *struct_field_type); /** @@ -1947,10 +1971,13 @@ On success, the field's type is placed in \p *field_type if @sa bt_ctf_field_type_structure_get_field_type_by_name(): Finds a structure field type's field by name. */ -extern int bt_ctf_field_type_structure_get_field( +extern int bt_ctf_field_type_structure_get_field_by_index( struct bt_ctf_field_type *struct_field_type, const char **field_name, struct bt_ctf_field_type **field_type, - int index); + uint64_t index); + +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_structure_get_field bt_ctf_field_type_structure_get_field_by_index /** @brief Returns the type of the field named \p field_name found in @@ -1969,7 +1996,7 @@ extern int bt_ctf_field_type_structure_get_field( @postrefcountsame{struct_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_structure_get_field(): Finds a +@sa bt_ctf_field_type_structure_get_field_by_index(): Finds a structure field type's field by index. */ extern @@ -2392,7 +2419,7 @@ extern struct bt_ctf_field_path *bt_ctf_field_type_variant_get_tag_field_path( @preisvarft{variant_field_type} @postrefcountsame{variant_field_type} */ -extern int bt_ctf_field_type_variant_get_field_count( +extern int64_t bt_ctf_field_type_variant_get_field_count( struct bt_ctf_field_type *variant_field_type); /** @@ -2428,10 +2455,13 @@ On success, the field's type is placed in \p *field_type if @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant field type's field by current tag value. */ -extern int bt_ctf_field_type_variant_get_field( +extern int bt_ctf_field_type_variant_get_field_by_index( struct bt_ctf_field_type *variant_field_type, const char **field_name, - struct bt_ctf_field_type **field_type, int index); + struct bt_ctf_field_type **field_type, uint64_t index); + +/* Pre-2.0 CTF writer compatibility */ +#define bt_ctf_field_type_variant_get_field bt_ctf_field_type_variant_get_field_by_index /** @brief Returns the type of the field (choice) named \p field_name @@ -2450,7 +2480,7 @@ extern int bt_ctf_field_type_variant_get_field( @postrefcountsame{variant_field_type} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's +@sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's field by index. @sa bt_ctf_field_type_variant_get_field_type_from_tag(): Finds a variant field type's field by current tag value. @@ -2486,7 +2516,7 @@ bt_ctf_field_type_variant_get_tag_type() for \p variant_field_type. @postrefcountsame{tag_field} @postsuccessrefcountretinc -@sa bt_ctf_field_type_variant_get_field(): Finds a variant field type's +@sa bt_ctf_field_type_variant_get_field_by_index(): Finds a variant field type's field by index. @sa bt_ctf_field_type_variant_get_field_type_by_name(): Finds a variant field type's field by name.