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

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