include/babeltrace/ctf-ir/event-types.h

   1 #ifndef BABELTRACE_CTF_IR_EVENT_TYPES_H
   2 #define BABELTRACE_CTF_IR_EVENT_TYPES_H
   3
   4 /*
   5  * BabelTrace - CTF IR: Event Types
   6  *
   7  * Copyright 2013 EfficiOS Inc.
   8  *
   9  * Author: Jérémie Galarneau <jeremie.galarneau@efficios.com>
  10  *
  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:
  17  *
  18  * The above copyright notice and this permission notice shall be included in
  19  * all copies or substantial portions of the Software.
  20  *
  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
  27  * SOFTWARE.
  28  *
  29  * The Common Trace Format (CTF) Specification is available at
  30  * http://www.efficios.com/ctf
  31  */
  32
  33 #include <babeltrace/ctf/events.h>
  34 #include <stdint.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 struct bt_ctf_event_class;
  41 struct bt_ctf_event;
  42 struct bt_ctf_field_type;
  43
  44 enum bt_ctf_integer_base {
  45         BT_CTF_INTEGER_BASE_UNKNOWN = -1,
  46         BT_CTF_INTEGER_BASE_BINARY = 2,
  47         BT_CTF_INTEGER_BASE_OCTAL = 8,
  48         BT_CTF_INTEGER_BASE_DECIMAL = 10,
  49         BT_CTF_INTEGER_BASE_HEXADECIMAL = 16,
  50 };
  51
  52 enum bt_ctf_byte_order {
  53         BT_CTF_BYTE_ORDER_NATIVE = 0,
  54         BT_CTF_BYTE_ORDER_LITTLE_ENDIAN,
  55         BT_CTF_BYTE_ORDER_BIG_ENDIAN,
  56         BT_CTF_BYTE_ORDER_NETWORK,
  57 };
  58
  59 /*
  60  * bt_ctf_field_type_integer_create: create an integer field type.
  61  *
  62  * Allocate a new integer field type of the given size. The creation of a field
  63  * type sets its reference count to 1.
  64  *
  65  * @param size Integer field type size/length in bits.
  66  *
  67  * Returns an allocated field type on success, NULL on error.
  68  */
  69 extern struct bt_ctf_field_type *bt_ctf_field_type_integer_create(
  70                 unsigned int size);
  71
  72 /*
  73  * bt_ctf_field_type_integer_set_signed: set an integer type's signedness.
  74  *
  75  * Set an integer type's signedness attribute.
  76  *
  77  * @param integer Integer type.
  78  * @param is_signed Integer's signedness, defaults to FALSE.
  79  *
  80  * Returns 0 on success, a negative value on error.
  81  */
  82 extern int bt_ctf_field_type_integer_set_signed(
  83                 struct bt_ctf_field_type *integer, int is_signed);
  84
  85 /*
  86  * bt_ctf_field_type_integer_set_base: set an integer type's base.
  87  *
  88  * Set an integer type's base used to pretty-print the resulting trace.
  89  *
  90  * @param integer Integer type.
  91  * @param base Integer base, defaults to BT_CTF_INTEGER_BASE_DECIMAL.
  92  *
  93  * Returns 0 on success, a negative value on error.
  94  */
  95 extern int bt_ctf_field_type_integer_set_base(
  96                 struct bt_ctf_field_type *integer,
  97                 enum bt_ctf_integer_base base);
  98
  99 /*
 100  * bt_ctf_field_type_integer_set_encoding: set an integer type's encoding.
 101  *
 102  * An integer encoding may be set to signal that the integer must be printed as
 103  * a text character.
 104  *
 105  * @param integer Integer type.
 106  * @param encoding Integer output encoding, defaults to CTF_STRING_ENCODING_NONE
 107  *
 108  * Returns 0 on success, a negative value on error.
 109  */
 110 extern int bt_ctf_field_type_integer_set_encoding(
 111                 struct bt_ctf_field_type *integer,
 112                 enum ctf_string_encoding encoding);
 113
 114 /*
 115  * bt_ctf_field_type_enumeration_create: create an enumeration field type.
 116  *
 117  * Allocate a new enumeration field type with the given underlying type. The
 118  * creation of a field type sets its reference count to 1.
 119  * The resulting enumeration will share the integer_container_type's ownership
 120  * by increasing its reference count.
 121  *
 122  * @param integer_container_type Underlying integer type of the enumeration
 123  *      type.
 124  *
 125  * Returns an allocated field type on success, NULL on error.
 126  */
 127 extern struct bt_ctf_field_type *bt_ctf_field_type_enumeration_create(
 128                 struct bt_ctf_field_type *integer_container_type);
 129
 130 /*
 131  * bt_ctf_field_type_enumeration_add_mapping: add an enumeration mapping.
 132  *
 133  * Add a mapping to the enumeration. The range's values are inclusive.
 134  *
 135  * @param enumeration Enumeration type.
 136  * @param string Enumeration mapping name (will be copied).
 137  * @param range_start Enumeration mapping range start.
 138  * @param range_end Enumeration mapping range end.
 139  *
 140  * Returns 0 on success, a negative value on error.
 141  */
 142 extern int bt_ctf_field_type_enumeration_add_mapping(
 143                 struct bt_ctf_field_type *enumeration, const char *string,
 144                 int64_t range_start, int64_t range_end);
 145
 146 /*
 147  * bt_ctf_field_type_floating_point_create: create a floating point field type.
 148  *
 149  * Allocate a new floating point field type. The creation of a field type sets
 150  * its reference count to 1.
 151  *
 152  * Returns an allocated field type on success, NULL on error.
 153  */
 154 extern struct bt_ctf_field_type *bt_ctf_field_type_floating_point_create(void);
 155
 156 /*
 157  * bt_ctf_field_type_floating_point_set_exponent_digits: set exponent digit
 158  * count.
 159  *
 160  * Set the number of exponent digits to use to store the floating point field.
 161  * The only values currently supported are FLT_EXP_DIG and DBL_EXP_DIG.
 162  *
 163  * @param floating_point Floating point type.
 164  * @param exponent_digits Number of digits to allocate to the exponent (defaults
 165  *      to FLT_EXP_DIG).
 166  *
 167  * Returns 0 on success, a negative value on error.
 168  */
 169 extern int bt_ctf_field_type_floating_point_set_exponent_digits(
 170                 struct bt_ctf_field_type *floating_point,
 171                 unsigned int exponent_digits);
 172
 173 /*
 174  * bt_ctf_field_type_floating_point_set_mantissa_digits: set mantissa digit
 175  * count.
 176  *
 177  * Set the number of mantissa digits to use to store the floating point field.
 178  * The only values currently supported are FLT_MANT_DIG and DBL_MANT_DIG.
 179  *
 180  * @param floating_point Floating point type.
 181  * @param mantissa_digits Number of digits to allocate to the mantissa (defaults
 182  *      to FLT_MANT_DIG).
 183  *
 184  * Returns 0 on success, a negative value on error.
 185  */
 186 extern int bt_ctf_field_type_floating_point_set_mantissa_digits(
 187                 struct bt_ctf_field_type *floating_point,
 188                 unsigned int mantissa_digits);
 189
 190 /*
 191  * bt_ctf_field_type_structure_create: create a structure field type.
 192  *
 193  * Allocate a new structure field type. The creation of a field type sets
 194  * its reference count to 1.
 195  *
 196  * Returns an allocated field type on success, NULL on error.
 197  */
 198 extern struct bt_ctf_field_type *bt_ctf_field_type_structure_create(void);
 199
 200 /*
 201  * bt_ctf_field_type_structure_add_field: add a field to a structure.
 202  *
 203  * Add a field of type "field_type" to the structure. The structure will share
 204  * field_type's ownership by increasing its reference count.
 205  *
 206  * @param structure Structure type.
 207  * @param field_type Type of the field to add to the structure type.
 208  * @param field_name Name of the structure's new field (will be copied).
 209  *
 210  * Returns 0 on success, a negative value on error.
 211  */
 212 extern int bt_ctf_field_type_structure_add_field(
 213                 struct bt_ctf_field_type *structure,
 214                 struct bt_ctf_field_type *field_type,
 215                 const char *field_name);
 216
 217 /*
 218  * bt_ctf_field_type_variant_create: create a variant field type.
 219  *
 220  * Allocate a new variant field type. The creation of a field type sets
 221  * its reference count to 1. tag_name must be the name of an enumeration
 222  * field declared in the same scope as this variant.
 223  *
 224  * @param enum_tag Type of the variant's tag/selector (must be an enumeration).
 225  * @param tag_name Name of the variant's tag/selector field (will be copied).
 226  *
 227  * Returns an allocated field type on success, NULL on error.
 228  */
 229 extern struct bt_ctf_field_type *bt_ctf_field_type_variant_create(
 230                 struct bt_ctf_field_type *enum_tag,
 231                 const char *tag_name);
 232
 233 /*
 234  * bt_ctf_field_type_variant_add_field: add a field to a variant.
 235  *
 236  * Add a field of type "field_type" to the variant.The variant will share
 237  * field_type's ownership by increasing its reference count. The "field_name"
 238  * will be copied. field_name must match a mapping in the tag/selector
 239  * enumeration.
 240  *
 241  * @param variant Variant type.
 242  * @param field_type Type of the variant type's new field.
 243  * @param field_name Name of the variant type's new field (will be copied).
 244  *
 245  * Returns 0 on success, a negative value on error.
 246  */
 247 extern int bt_ctf_field_type_variant_add_field(
 248                 struct bt_ctf_field_type *variant,
 249                 struct bt_ctf_field_type *field_type,
 250                 const char *field_name);
 251
 252 /*
 253  * bt_ctf_field_type_array_create: create an array field type.
 254  *
 255  * Allocate a new array field type. The creation of a field type sets
 256  * its reference count to 1.
 257  *
 258  * @param element_type Array's element type.
 259  * @oaram length Array type's length.
 260  *
 261  * Returns an allocated field type on success, NULL on error.
 262  */
 263 extern struct bt_ctf_field_type *bt_ctf_field_type_array_create(
 264                 struct bt_ctf_field_type *element_type,
 265                 unsigned int length);
 266
 267 /*
 268  * bt_ctf_field_type_sequence_create: create a sequence field type.
 269  *
 270  * Allocate a new sequence field type. The creation of a field type sets
 271  * its reference count to 1. "length_field_name" must match an integer field
 272  * declared in the same scope.
 273  *
 274  * @param element_type Sequence's element type.
 275  * @param length_field_name Name of the sequence's length field (will be
 276  *      copied).
 277  *
 278  * Returns an allocated field type on success, NULL on error.
 279  */
 280 extern struct bt_ctf_field_type *bt_ctf_field_type_sequence_create(
 281                 struct bt_ctf_field_type *element_type,
 282                 const char *length_field_name);
 283
 284 /*
 285  * bt_ctf_field_type_string_create: create a string field type.
 286  *
 287  * Allocate a new string field type. The creation of a field type sets
 288  * its reference count to 1.
 289  *
 290  * Returns an allocated field type on success, NULL on error.
 291  */
 292 extern struct bt_ctf_field_type *bt_ctf_field_type_string_create(void);
 293
 294 /*
 295  * bt_ctf_field_type_string_set_encoding: set a string type's encoding.
 296  *
 297  * Set the string type's encoding.
 298  *
 299  * @param string String type.
 300  * @param encoding String field encoding, default CTF_STRING_ENCODING_ASCII.
 301  *      Valid values are CTF_STRING_ENCODING_ASCII and CTF_STRING_ENCODING_UTF8.
 302  *
 303  * Returns 0 on success, a negative value on error.
 304  */
 305 extern int bt_ctf_field_type_string_set_encoding(
 306                 struct bt_ctf_field_type *string,
 307                 enum ctf_string_encoding encoding);
 308
 309 /*
 310  * bt_ctf_field_type_set_alignment: set a field type's alignment.
 311  *
 312  * Set the field type's alignment.
 313  *
 314  * @param type Field type.
 315  * @param alignment Type's alignment. Defaults to 1 (bit-aligned). However,
 316  *      some types, such as structures and string, may impose other alignment
 317  *      constraints.
 318  *
 319  * Returns 0 on success, a negative value on error.
 320  */
 321 extern int bt_ctf_field_type_set_alignment(struct bt_ctf_field_type *type,
 322                 unsigned int alignment);
 323
 324 /*
 325  * bt_ctf_field_type_set_byte_order: set a field type's byte order.
 326  *
 327  * Set the field type's byte order.
 328  *
 329  * @param type Field type.
 330  * @param byte_order Field type's byte order. Defaults to
 331  * BT_CTF_BYTE_ORDER_NATIVE, the host machine's endianness.
 332  *
 333  * Returns 0 on success, a negative value on error.
 334  */
 335 extern int bt_ctf_field_type_set_byte_order(struct bt_ctf_field_type *type,
 336                 enum bt_ctf_byte_order byte_order);
 337
 338 /*
 339  * bt_ctf_field_type_get and bt_ctf_field_type_put: increment and decrement
 340  * the field type's reference count.
 341  *
 342  * These functions ensure that the field type won't be destroyed while it
 343  * is in use. The same number of get and put (plus one extra put to
 344  * release the initial reference done at creation) have to be done to
 345  * destroy a field type.
 346  *
 347  * When the field type's reference count is decremented to 0 by a
 348  * bt_ctf_field_type_put, the field type is freed.
 349  *
 350  * @param type Field type.
 351  */
 352 extern void bt_ctf_field_type_get(struct bt_ctf_field_type *type);
 353 extern void bt_ctf_field_type_put(struct bt_ctf_field_type *type);
 354
 355 #ifdef __cplusplus
 356 }
 357 #endif
 358
 359 #endif /* BABELTRACE_CTF_IR_EVENT_TYPES_H */