include/babeltrace/types.h

   1 #ifndef _BABELTRACE_TYPES_H
   2 #define _BABELTRACE_TYPES_H
   3
   4 /*
   5  * BabelTrace
   6  *
   7  * Type Header
   8  *
   9  * Copyright 2010, 2011 - Mathieu Desnoyers <mathieu.desnoyers@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
  22 #include <babeltrace/align.h>
  23 #include <babeltrace/list.h>
  24 #include <stdbool.h>
  25 #include <stdint.h>
  26 #include <limits.h>
  27 #include <string.h>
  28 #include <glib.h>
  29 #include <assert.h>
  30
  31 /* Preallocate this many fields for structures */
  32 #define DEFAULT_NR_STRUCT_FIELDS 8
  33
  34 struct stream_pos;
  35 struct format;
  36 struct definition;
  37
  38 /* type scope */
  39 struct declaration_scope {
  40         /* Hash table mapping type name GQuark to "struct declaration" */
  41         /* Used for both typedef and typealias. */
  42         GHashTable *typedef_declarations;
  43         /* Hash table mapping struct name GQuark to "struct declaration_struct" */
  44         GHashTable *struct_declarations;
  45         /* Hash table mapping variant name GQuark to "struct declaration_variant" */
  46         GHashTable *variant_declarations;
  47         /* Hash table mapping enum name GQuark to "struct type_enum" */
  48         GHashTable *enum_declarations;
  49         struct declaration_scope *parent_scope;
  50 };
  51
  52 /* definition scope */
  53 struct definition_scope {
  54         /* Hash table mapping field name GQuark to "struct definition" */
  55         GHashTable *definitions;
  56         struct definition_scope *parent_scope;
  57         /*
  58          * Complete "path" leading to this definition scope.
  59          * Includes dynamic scope name '.' field name '.' field name '.' ....
  60          * Array of GQuark elements (which are each separated by dots).
  61          * The dynamic scope name can contain dots, and is encoded into
  62          * a single GQuark. Thus, scope_path[0] returns the GQuark
  63          * identifying the dynamic scope.
  64          */
  65         GArray *scope_path;     /* array of GQuark */
  66 };
  67
  68 enum ctf_type_id {
  69         CTF_TYPE_UNKNOWN = 0,
  70         CTF_TYPE_INTEGER,
  71         CTF_TYPE_FLOAT,
  72         CTF_TYPE_ENUM,
  73         CTF_TYPE_STRING,
  74         CTF_TYPE_STRUCT,
  75         CTF_TYPE_UNTAGGED_VARIANT,
  76         CTF_TYPE_VARIANT,
  77         CTF_TYPE_ARRAY,
  78         CTF_TYPE_SEQUENCE,
  79         NR_CTF_TYPES,
  80 };
  81
  82 struct declaration {
  83         enum ctf_type_id id;
  84         size_t alignment;       /* type alignment, in bits */
  85         int ref;                /* number of references to the type */
  86         /*
  87          * declaration_free called with declaration ref is decremented to 0.
  88          */
  89         void (*declaration_free)(struct declaration *declaration);
  90         struct definition *
  91                 (*definition_new)(struct declaration *declaration,
  92                                   struct definition_scope *parent_scope,
  93                                   GQuark field_name, int index);
  94         /*
  95          * definition_free called with definition ref is decremented to 0.
  96          */
  97         void (*definition_free)(struct definition *definition);
  98 };
  99
 100 struct definition {
 101         struct declaration *declaration;
 102         int index;              /* Position of the definition in its container */
 103         GQuark name;            /* Field name in its container (or 0 if unset) */
 104         int ref;                /* number of references to the definition */
 105 };
 106
 107 typedef int (*rw_dispatch)(struct stream_pos *pos,
 108                            struct definition *definition);
 109
 110 /* Parent of per-plugin positions */
 111 struct stream_pos {
 112         /* read/write dispatch table. Specific to plugin used for stream. */
 113         rw_dispatch *rw_table;  /* rw dispatch table */
 114 };
 115
 116 static inline
 117 int generic_rw(struct stream_pos *pos, struct definition *definition)
 118 {
 119         enum ctf_type_id dispatch_id = definition->declaration->id;
 120         rw_dispatch call;
 121
 122         assert(pos->rw_table[dispatch_id] != NULL);
 123         call = pos->rw_table[dispatch_id];
 124         return call(pos, definition);
 125 }
 126
 127 /*
 128  * Because we address in bits, bitfields end up being exactly the same as
 129  * integers, except that their read/write functions must be able to deal with
 130  * read/write non aligned on CHAR_BIT.
 131  */
 132 struct declaration_integer {
 133         struct declaration p;
 134         size_t len;             /* length, in bits. */
 135         int byte_order;         /* byte order */
 136         int signedness;
 137 };
 138
 139 struct definition_integer {
 140         struct definition p;
 141         struct declaration_integer *declaration;
 142         /* Last values read */
 143         union {
 144                 uint64_t _unsigned;
 145                 int64_t _signed;
 146         } value;
 147 };
 148
 149 struct declaration_float {
 150         struct declaration p;
 151         struct declaration_integer *sign;
 152         struct declaration_integer *mantissa;
 153         struct declaration_integer *exp;
 154         int byte_order;
 155         /* TODO: we might want to express more info about NaN, +inf and -inf */
 156 };
 157
 158 struct definition_float {
 159         struct definition p;
 160         struct declaration_float *declaration;
 161         struct definition_integer *sign;
 162         struct definition_integer *mantissa;
 163         struct definition_integer *exp;
 164         /* Last values read */
 165         long double value;
 166 };
 167
 168 /*
 169  * enum_val_equal assumes that signed and unsigned memory layout overlap.
 170  */
 171 struct enum_range {
 172         union {
 173                 int64_t _signed;
 174                 uint64_t _unsigned;
 175         } start;        /* lowest range value */
 176         union {
 177                 int64_t _signed;
 178                 uint64_t _unsigned;
 179         } end;          /* highest range value */
 180 };
 181
 182 struct enum_range_to_quark {
 183         struct cds_list_head node;
 184         struct enum_range range;
 185         GQuark quark;
 186 };
 187
 188 /*
 189  * We optimize the common case (range of size 1: single value) by creating a
 190  * hash table mapping values to quark sets. We then lookup the ranges to
 191  * complete the quark set.
 192  *
 193  * TODO: The proper structure to hold the range to quark set mapping would be an
 194  * interval tree, with O(n) size, O(n*log(n)) build time and O(log(n)) query
 195  * time. Using a simple O(n) list search for now for implementation speed and
 196  * given that we can expect to have a _relatively_ small number of enumeration
 197  * ranges. This might become untrue if we are fed with symbol tables often
 198  * required to lookup function names from instruction pointer value.
 199  */
 200 struct enum_table {
 201         GHashTable *value_to_quark_set;         /* (value, GQuark GArray) */
 202         struct cds_list_head range_to_quark;    /* (range, GQuark) */
 203         GHashTable *quark_to_range_set;         /* (GQuark, range GArray) */
 204 };
 205
 206 struct declaration_enum {
 207         struct declaration p;
 208         struct declaration_integer *integer_declaration;
 209         struct enum_table table;
 210 };
 211
 212 struct definition_enum {
 213         struct definition p;
 214         struct definition_integer *integer;
 215         struct declaration_enum *declaration;
 216         /* Last GQuark values read. Keeping a reference on the GQuark array. */
 217         GArray *value;
 218 };
 219
 220 enum ctf_string_encoding {
 221         CTF_STRING_UTF8 = 0,
 222         CTF_STRING_ASCII,
 223         CTF_STRING_UNKNOWN,
 224 };
 225
 226 struct declaration_string {
 227         struct declaration p;
 228         enum ctf_string_encoding encoding;
 229 };
 230
 231 struct definition_string {
 232         struct definition p;
 233         struct declaration_string *declaration;
 234         char *value;    /* freed at definition_string teardown */
 235         size_t len, alloc_len;
 236 };
 237
 238 struct declaration_field {
 239         GQuark name;
 240         struct declaration *declaration;
 241 };
 242
 243 struct declaration_struct {
 244         struct declaration p;
 245         GHashTable *fields_by_name;     /* Tuples (field name, field index) */
 246         struct declaration_scope *scope;
 247         GArray *fields;                 /* Array of declaration_field */
 248 };
 249
 250 struct definition_struct {
 251         struct definition p;
 252         struct declaration_struct *declaration;
 253         struct definition_scope *scope;
 254         GPtrArray *fields;              /* Array of pointers to struct definition */
 255 };
 256
 257 struct declaration_untagged_variant {
 258         struct declaration p;
 259         GHashTable *fields_by_tag;      /* Tuples (field tag, field index) */
 260         struct declaration_scope *scope;
 261         GArray *fields;                 /* Array of declaration_field */
 262 };
 263
 264 struct declaration_variant {
 265         struct declaration p;
 266         struct declaration_untagged_variant *untagged_variant;
 267         GArray *tag_name;               /* Array of GQuark */
 268 };
 269
 270 /* A variant needs to be tagged to be defined. */
 271 struct definition_variant {
 272         struct definition p;
 273         struct declaration_variant *declaration;
 274         struct definition_scope *scope;
 275         struct definition *enum_tag;
 276         GPtrArray *fields;              /* Array of pointers to struct definition */
 277         struct definition *current_field;       /* Last field read */
 278 };
 279
 280 struct declaration_array {
 281         struct declaration p;
 282         size_t len;
 283         struct declaration *elem;
 284         struct declaration_scope *scope;
 285 };
 286
 287 struct definition_array {
 288         struct definition p;
 289         struct declaration_array *declaration;
 290         struct definition_scope *scope;
 291         GPtrArray *elems;               /* Array of pointers to struct definition */
 292 };
 293
 294 struct declaration_sequence {
 295         struct declaration p;
 296         struct declaration_integer *len_declaration;
 297         struct declaration *elem;
 298         struct declaration_scope *scope;
 299 };
 300
 301 struct definition_sequence {
 302         struct definition p;
 303         struct declaration_sequence *declaration;
 304         struct definition_scope *scope;
 305         struct definition_integer *len;
 306         GPtrArray *elems;               /* Array of pointers to struct definition */
 307 };
 308
 309 int register_declaration(GQuark declaration_name,
 310                          struct declaration *declaration,
 311                          struct declaration_scope *scope);
 312 struct declaration *lookup_declaration(GQuark declaration_name,
 313                                 struct declaration_scope *scope);
 314
 315 /*
 316  * Type scopes also contain a separate registry for struct, variant and
 317  * enum types. Those register types rather than type definitions, so
 318  * that a named variant can be declared without specifying its target
 319  * "choice" tag field immediately.
 320  */
 321 int register_struct_declaration(GQuark struct_name,
 322                                 struct declaration_struct *struct_declaration,
 323                                 struct declaration_scope *scope);
 324 struct declaration_struct *
 325         lookup_struct_declaration(GQuark struct_name,
 326                                   struct declaration_scope *scope);
 327 int register_variant_declaration(GQuark variant_name,
 328                           struct declaration_untagged_variant *untagged_variant_declaration,
 329                           struct declaration_scope *scope);
 330 struct declaration_untagged_variant *lookup_variant_declaration(GQuark variant_name,
 331                                          struct declaration_scope *scope);
 332 int register_enum_declaration(GQuark enum_name,
 333                               struct declaration_enum *enum_declaration,
 334                               struct declaration_scope *scope);
 335 struct declaration_enum *
 336         lookup_enum_declaration(GQuark enum_name,
 337                                 struct declaration_scope *scope);
 338
 339 struct declaration_scope *
 340         new_declaration_scope(struct declaration_scope *parent_scope);
 341 void free_declaration_scope(struct declaration_scope *scope);
 342
 343 /*
 344  * field_definition is for field definitions. They are registered into
 345  * definition scopes.
 346  */
 347 struct definition *
 348         lookup_definition(GArray *cur_path,     /* array of GQuark */
 349                           GArray *lookup_path,  /* array of GQuark */
 350                           struct definition_scope *scope);
 351 int register_field_definition(GQuark field_name,
 352                               struct definition *definition,
 353                               struct definition_scope *scope);
 354 struct definition_scope *
 355         new_definition_scope(struct definition_scope *parent_scope,
 356                              GQuark field_name);
 357 void set_dynamic_definition_scope(struct definition *definition,
 358                                   struct definition_scope *scope,
 359                                   const char *root_name);
 360 void free_definition_scope(struct definition_scope *scope);
 361
 362 void declaration_ref(struct declaration *declaration);
 363 void declaration_unref(struct declaration *declaration);
 364
 365 void definition_ref(struct definition *definition);
 366 void definition_unref(struct definition *definition);
 367
 368 struct declaration_integer *integer_declaration_new(size_t len, int byte_order,
 369                                       int signedness, size_t alignment);
 370
 371 /*
 372  * mantissa_len is the length of the number of bytes represented by the mantissa
 373  * (e.g. result of DBL_MANT_DIG). It includes the leading 1.
 374  */
 375 struct declaration_float *float_declaration_new(size_t mantissa_len,
 376                                   size_t exp_len, int byte_order,
 377                                   size_t alignment);
 378
 379 /*
 380  * A GQuark can be translated to/from strings with g_quark_from_string() and
 381  * g_quark_to_string().
 382  */
 383
 384 /*
 385  * Returns a GArray of GQuark or NULL.
 386  * Caller must release the GArray with g_array_unref().
 387  */
 388 GArray *enum_uint_to_quark_set(const struct declaration_enum *enum_declaration,
 389                                uint64_t v);
 390
 391 /*
 392  * Returns a GArray of GQuark or NULL.
 393  * Caller must release the GArray with g_array_unref().
 394  */
 395 GArray *enum_int_to_quark_set(const struct declaration_enum *enum_declaration,
 396                               uint64_t v);
 397
 398 /*
 399  * Returns a GArray of struct enum_range or NULL.
 400  * Callers do _not_ own the returned GArray (and therefore _don't_ need to
 401  * release it).
 402  */
 403 GArray *enum_quark_to_range_set(const struct declaration_enum *enum_declaration,
 404                                 GQuark q);
 405 void enum_signed_insert(struct declaration_enum *enum_declaration,
 406                         int64_t start, int64_t end, GQuark q);
 407 void enum_unsigned_insert(struct declaration_enum *enum_declaration,
 408                           uint64_t start, uint64_t end, GQuark q);
 409 size_t enum_get_nr_enumerators(struct declaration_enum *enum_declaration);
 410
 411 struct declaration_enum *
 412         enum_declaration_new(struct declaration_integer *integer_declaration);
 413
 414 struct declaration_string *
 415         string_declaration_new(enum ctf_string_encoding encoding);
 416
 417 struct declaration_struct *
 418         struct_declaration_new(struct declaration_scope *parent_scope);
 419 void struct_declaration_add_field(struct declaration_struct *struct_declaration,
 420                                   const char *field_name,
 421                                   struct declaration *field_declaration);
 422 /*
 423  * Returns the index of a field within a structure.
 424  */
 425 int struct_declaration_lookup_field_index(struct declaration_struct *struct_declaration,
 426                                                     GQuark field_name);
 427 /*
 428  * field returned only valid as long as the field structure is not appended to.
 429  */
 430 struct declaration_field *
 431 struct_declaration_get_field_from_index(struct declaration_struct *struct_declaration,
 432                                         int index);
 433 struct definition *
 434 struct_definition_get_field_from_index(struct definition_struct *struct_definition,
 435                                        int index);
 436 int struct_rw(struct stream_pos *pos, struct definition *definition);
 437
 438 /*
 439  * The tag enumeration is validated to ensure that it contains only mappings
 440  * from numeric values to a single tag. Overlapping tag value ranges are
 441  * therefore forbidden.
 442  */
 443 struct declaration_untagged_variant *untagged_variant_declaration_new(
 444                 struct declaration_scope *parent_scope);
 445 struct declaration_variant *variant_declaration_new(struct declaration_untagged_variant *untagged_variant,
 446                 const char *tag);
 447
 448 void untagged_variant_declaration_add_field(struct declaration_untagged_variant *untagged_variant_declaration,
 449                 const char *field_name,
 450                 struct declaration *field_declaration);
 451 struct declaration_field *
 452         untagged_variant_declaration_get_field_from_tag(struct declaration_untagged_variant *untagged_variant_declaration,
 453                 GQuark tag);
 454 /*
 455  * Returns 0 on success, -EPERM on error.
 456  */
 457 int variant_definition_set_tag(struct definition_variant *variant,
 458                                struct definition *enum_tag);
 459 /*
 460  * Returns the field selected by the current tag value.
 461  * field returned only valid as long as the variant structure is not appended
 462  * to.
 463  */
 464 struct definition *variant_get_current_field(struct definition_variant *variant);
 465 int variant_rw(struct stream_pos *pos, struct definition *definition);
 466
 467 /*
 468  * elem_declaration passed as parameter now belongs to the array. No
 469  * need to free it explicitly. "len" is the number of elements in the
 470  * array.
 471  */
 472 struct declaration_array *
 473         array_declaration_new(size_t len, struct declaration *elem_declaration,
 474                 struct declaration_scope *parent_scope);
 475 uint64_t array_len(struct definition_array *array);
 476 struct definition *array_index(struct definition_array *array, uint64_t i);
 477 int array_rw(struct stream_pos *pos, struct definition *definition);
 478
 479 /*
 480  * int_declaration and elem_declaration passed as parameter now belong
 481  * to the sequence. No need to free them explicitly.
 482  */
 483 struct declaration_sequence *
 484         sequence_declaration_new(struct declaration_integer *len_declaration,
 485                 struct declaration *elem_declaration,
 486                 struct declaration_scope *parent_scope);
 487 uint64_t sequence_len(struct definition_sequence *sequence);
 488 struct definition *sequence_index(struct definition_sequence *sequence, uint64_t i);
 489 int sequence_rw(struct stream_pos *pos, struct definition *definition);
 490
 491 /*
 492  * in: path (dot separated), out: q (GArray of GQuark)
 493  */
 494 void append_scope_path(const char *path, GArray *q);
 495
 496 #endif /* _BABELTRACE_declarationS_H */