438e79f3cff805fe535e564a78c52b5ab458a82f
[babeltrace.git] / 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 EfficiOS Inc. and Linux Foundation
10 *
11 * Author: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
12 *
13 * Permission is hereby granted, free of charge, to any person obtaining a copy
14 * of this software and associated documentation files (the "Software"), to deal
15 * in the Software without restriction, including without limitation the rights
16 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
17 * copies of the Software, and to permit persons to whom the Software is
18 * furnished to do so, subject to the following conditions:
19 *
20 * The above copyright notice and this permission notice shall be included in
21 * all copies or substantial portions of the Software.
22 *
23 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
24 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
25 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
26 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
27 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
28 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
29 * SOFTWARE.
30 */
31
32 #include <babeltrace/align.h>
33 #include <babeltrace/list.h>
34 #include <babeltrace/ctf/events.h>
35 #include <stdbool.h>
36 #include <stdint.h>
37 #include <limits.h>
38 #include <string.h>
39 #include <glib.h>
40 #include <assert.h>
41
42 /* Preallocate this many fields for structures */
43 #define DEFAULT_NR_STRUCT_FIELDS 8
44
45 struct ctf_stream_definition;
46 struct bt_stream_pos;
47 struct bt_format;
48 struct bt_definition;
49 struct ctf_clock;
50
51 /* type scope */
52 struct declaration_scope {
53 /* Hash table mapping type name GQuark to "struct declaration" */
54 /* Used for both typedef and typealias. */
55 GHashTable *typedef_declarations;
56 /* Hash table mapping struct name GQuark to "struct declaration_struct" */
57 GHashTable *struct_declarations;
58 /* Hash table mapping variant name GQuark to "struct declaration_variant" */
59 GHashTable *variant_declarations;
60 /* Hash table mapping enum name GQuark to "struct type_enum" */
61 GHashTable *enum_declarations;
62 struct declaration_scope *parent_scope;
63 };
64
65 /* definition scope */
66 struct definition_scope {
67 /* Hash table mapping field name GQuark to "struct definition" */
68 GHashTable *definitions;
69 struct definition_scope *parent_scope;
70 /*
71 * Complete "path" leading to this definition scope.
72 * Includes dynamic scope name '.' field name '.' field name '.' ....
73 * Array of GQuark elements (which are each separated by dots).
74 * The dynamic scope name can contain dots, and is encoded into
75 * a single GQuark. Thus, scope_path[0] returns the GQuark
76 * identifying the dynamic scope.
77 */
78 GArray *scope_path; /* array of GQuark */
79 };
80
81 struct bt_declaration {
82 enum ctf_type_id id;
83 size_t alignment; /* type alignment, in bits */
84 int ref; /* number of references to the type */
85 /*
86 * declaration_free called with declaration ref is decremented to 0.
87 */
88 void (*declaration_free)(struct bt_declaration *declaration);
89 struct bt_definition *
90 (*definition_new)(struct bt_declaration *declaration,
91 struct definition_scope *parent_scope,
92 GQuark field_name, int index,
93 const char *root_name);
94 /*
95 * definition_free called with definition ref is decremented to 0.
96 */
97 void (*definition_free)(struct bt_definition *definition);
98 };
99
100 struct bt_definition {
101 struct bt_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 GQuark path;
106 struct definition_scope *scope;
107 };
108
109 typedef int (*rw_dispatch)(struct bt_stream_pos *pos,
110 struct bt_definition *definition);
111
112 /* Parent of per-plugin positions */
113 struct bt_stream_pos {
114 /* read/write dispatch table. Specific to plugin used for stream. */
115 rw_dispatch *rw_table; /* rw dispatch table */
116 int (*event_cb)(struct bt_stream_pos *pos,
117 struct ctf_stream_definition *stream);
118 int (*pre_trace_cb)(struct bt_stream_pos *pos,
119 struct bt_trace_descriptor *trace);
120 int (*post_trace_cb)(struct bt_stream_pos *pos,
121 struct bt_trace_descriptor *trace);
122 struct bt_trace_descriptor *trace;
123 };
124
125 static inline
126 int generic_rw(struct bt_stream_pos *pos, struct bt_definition *definition)
127 {
128 enum ctf_type_id dispatch_id = definition->declaration->id;
129 rw_dispatch call;
130
131 assert(pos->rw_table[dispatch_id] != NULL);
132 call = pos->rw_table[dispatch_id];
133 return call(pos, definition);
134 }
135
136 /*
137 * Because we address in bits, bitfields end up being exactly the same as
138 * integers, except that their read/write functions must be able to deal with
139 * read/write non aligned on CHAR_BIT.
140 */
141 struct declaration_integer {
142 struct bt_declaration p;
143 size_t len; /* length, in bits. */
144 int byte_order; /* byte order */
145 int signedness;
146 int base; /* Base for pretty-printing: 2, 8, 10, 16 */
147 enum ctf_string_encoding encoding;
148 struct ctf_clock *clock;
149 };
150
151 struct definition_integer {
152 struct bt_definition p;
153 struct declaration_integer *declaration;
154 /* Last values read */
155 union {
156 uint64_t _unsigned;
157 int64_t _signed;
158 } value;
159 };
160
161 struct declaration_float {
162 struct bt_declaration p;
163 struct declaration_integer *sign;
164 struct declaration_integer *mantissa;
165 struct declaration_integer *exp;
166 int byte_order;
167 /* TODO: we might want to express more info about NaN, +inf and -inf */
168 };
169
170 struct definition_float {
171 struct bt_definition p;
172 struct declaration_float *declaration;
173 struct definition_integer *sign;
174 struct definition_integer *mantissa;
175 struct definition_integer *exp;
176 /* Last values read */
177 double value;
178 };
179
180 /*
181 * enum_val_equal assumes that signed and unsigned memory layout overlap.
182 */
183 struct enum_range {
184 union {
185 int64_t _signed;
186 uint64_t _unsigned;
187 } start; /* lowest range value */
188 union {
189 int64_t _signed;
190 uint64_t _unsigned;
191 } end; /* highest range value */
192 };
193
194 struct enum_range_to_quark {
195 struct bt_list_head node;
196 struct enum_range range;
197 GQuark quark;
198 };
199
200 /*
201 * We optimize the common case (range of size 1: single value) by creating a
202 * hash table mapping values to quark sets. We then lookup the ranges to
203 * complete the quark set.
204 *
205 * TODO: The proper structure to hold the range to quark set mapping would be an
206 * interval tree, with O(n) size, O(n*log(n)) build time and O(log(n)) query
207 * time. Using a simple O(n) list search for now for implementation speed and
208 * given that we can expect to have a _relatively_ small number of enumeration
209 * ranges. This might become untrue if we are fed with symbol tables often
210 * required to lookup function names from instruction pointer value.
211 */
212 struct enum_table {
213 GHashTable *value_to_quark_set; /* (value, GQuark GArray) */
214 struct bt_list_head range_to_quark; /* (range, GQuark) */
215 GHashTable *quark_to_range_set; /* (GQuark, range GArray) */
216 };
217
218 struct declaration_enum {
219 struct bt_declaration p;
220 struct declaration_integer *integer_declaration;
221 struct enum_table table;
222 };
223
224 struct definition_enum {
225 struct bt_definition p;
226 struct definition_integer *integer;
227 struct declaration_enum *declaration;
228 /* Last GQuark values read. Keeping a reference on the GQuark array. */
229 GArray *value;
230 };
231
232 struct declaration_string {
233 struct bt_declaration p;
234 enum ctf_string_encoding encoding;
235 };
236
237 struct definition_string {
238 struct bt_definition p;
239 struct declaration_string *declaration;
240 char *value; /* freed at definition_string teardown */
241 size_t len, alloc_len;
242 };
243
244 struct declaration_field {
245 GQuark name;
246 struct bt_declaration *declaration;
247 };
248
249 struct declaration_struct {
250 struct bt_declaration p;
251 GHashTable *fields_by_name; /* Tuples (field name, field index) */
252 struct declaration_scope *scope;
253 GArray *fields; /* Array of declaration_field */
254 };
255
256 struct definition_struct {
257 struct bt_definition p;
258 struct declaration_struct *declaration;
259 GPtrArray *fields; /* Array of pointers to struct bt_definition */
260 };
261
262 struct declaration_untagged_variant {
263 struct bt_declaration p;
264 GHashTable *fields_by_tag; /* Tuples (field tag, field index) */
265 struct declaration_scope *scope;
266 GArray *fields; /* Array of declaration_field */
267 };
268
269 struct declaration_variant {
270 struct bt_declaration p;
271 struct declaration_untagged_variant *untagged_variant;
272 GArray *tag_name; /* Array of GQuark */
273 };
274
275 /* A variant needs to be tagged to be defined. */
276 struct definition_variant {
277 struct bt_definition p;
278 struct declaration_variant *declaration;
279 struct bt_definition *enum_tag;
280 GPtrArray *fields; /* Array of pointers to struct bt_definition */
281 struct bt_definition *current_field; /* Last field read */
282 };
283
284 struct declaration_array {
285 struct bt_declaration p;
286 size_t len;
287 struct bt_declaration *elem;
288 struct declaration_scope *scope;
289 };
290
291 struct definition_array {
292 struct bt_definition p;
293 struct declaration_array *declaration;
294 GPtrArray *elems; /* Array of pointers to struct bt_definition */
295 GString *string; /* String for encoded integer children */
296 };
297
298 struct declaration_sequence {
299 struct bt_declaration p;
300 GArray *length_name; /* Array of GQuark */
301 struct bt_declaration *elem;
302 struct declaration_scope *scope;
303 };
304
305 struct definition_sequence {
306 struct bt_definition p;
307 struct declaration_sequence *declaration;
308 struct definition_integer *length;
309 GPtrArray *elems; /* Array of pointers to struct bt_definition */
310 GString *string; /* String for encoded integer children */
311 };
312
313 int bt_register_declaration(GQuark declaration_name,
314 struct bt_declaration *declaration,
315 struct declaration_scope *scope);
316 struct bt_declaration *bt_lookup_declaration(GQuark declaration_name,
317 struct declaration_scope *scope);
318
319 /*
320 * Type scopes also contain a separate registry for struct, variant and
321 * enum types. Those register types rather than type definitions, so
322 * that a named variant can be declared without specifying its target
323 * "choice" tag field immediately.
324 */
325 int bt_register_struct_declaration(GQuark struct_name,
326 struct declaration_struct *struct_declaration,
327 struct declaration_scope *scope);
328 struct declaration_struct *
329 bt_lookup_struct_declaration(GQuark struct_name,
330 struct declaration_scope *scope);
331 int bt_register_variant_declaration(GQuark variant_name,
332 struct declaration_untagged_variant *untagged_variant_declaration,
333 struct declaration_scope *scope);
334 struct declaration_untagged_variant *bt_lookup_variant_declaration(GQuark variant_name,
335 struct declaration_scope *scope);
336 int bt_register_enum_declaration(GQuark enum_name,
337 struct declaration_enum *enum_declaration,
338 struct declaration_scope *scope);
339 struct declaration_enum *
340 bt_lookup_enum_declaration(GQuark enum_name,
341 struct declaration_scope *scope);
342
343 struct declaration_scope *
344 bt_new_declaration_scope(struct declaration_scope *parent_scope);
345 void bt_free_declaration_scope(struct declaration_scope *scope);
346
347 /*
348 * field_definition is for field definitions. They are registered into
349 * definition scopes.
350 */
351 struct bt_definition *
352 bt_lookup_path_definition(GArray *cur_path, /* array of GQuark */
353 GArray *lookup_path, /* array of GQuark */
354 struct definition_scope *scope);
355 int bt_register_field_definition(GQuark field_name,
356 struct bt_definition *definition,
357 struct definition_scope *scope);
358 struct definition_scope *
359 bt_new_definition_scope(struct definition_scope *parent_scope,
360 GQuark field_name, const char *root_name);
361 void bt_free_definition_scope(struct definition_scope *scope);
362
363 GQuark bt_new_definition_path(struct definition_scope *parent_scope,
364 GQuark field_name, const char *root_name);
365
366 static inline
367 int compare_definition_path(struct bt_definition *definition, GQuark path)
368 {
369 return definition->path == path;
370 }
371
372 void bt_declaration_ref(struct bt_declaration *declaration);
373 void bt_declaration_unref(struct bt_declaration *declaration);
374
375 void bt_definition_ref(struct bt_definition *definition);
376 void bt_definition_unref(struct bt_definition *definition);
377
378 struct declaration_integer *bt_integer_declaration_new(size_t len, int byte_order,
379 int signedness, size_t alignment,
380 int base, enum ctf_string_encoding encoding,
381 struct ctf_clock *clock);
382 uint64_t bt_get_unsigned_int(const struct bt_definition *field);
383 int64_t bt_get_signed_int(const struct bt_definition *field);
384 int bt_get_int_signedness(const struct bt_definition *field);
385 int bt_get_int_byte_order(const struct bt_definition *field);
386 int bt_get_int_base(const struct bt_definition *field);
387 size_t bt_get_int_len(const struct bt_definition *field); /* in bits */
388 enum ctf_string_encoding bt_get_int_encoding(const struct bt_definition *field);
389
390 /*
391 * mantissa_len is the length of the number of bytes represented by the mantissa
392 * (e.g. result of DBL_MANT_DIG). It includes the leading 1.
393 */
394 struct declaration_float *bt_float_declaration_new(size_t mantissa_len,
395 size_t exp_len, int byte_order,
396 size_t alignment);
397
398 /*
399 * A GQuark can be translated to/from strings with g_quark_from_string() and
400 * g_quark_to_string().
401 */
402
403 /*
404 * Returns a GArray of GQuark or NULL.
405 * Caller must release the GArray with g_array_unref().
406 */
407 GArray *bt_enum_uint_to_quark_set(const struct declaration_enum *enum_declaration,
408 uint64_t v);
409
410 /*
411 * Returns a GArray of GQuark or NULL.
412 * Caller must release the GArray with g_array_unref().
413 */
414 GArray *bt_enum_int_to_quark_set(const struct declaration_enum *enum_declaration,
415 int64_t v);
416
417 /*
418 * Returns a GArray of struct enum_range or NULL.
419 * Callers do _not_ own the returned GArray (and therefore _don't_ need to
420 * release it).
421 */
422 GArray *bt_enum_quark_to_range_set(const struct declaration_enum *enum_declaration,
423 GQuark q);
424 void bt_enum_signed_insert(struct declaration_enum *enum_declaration,
425 int64_t start, int64_t end, GQuark q);
426 void bt_enum_unsigned_insert(struct declaration_enum *enum_declaration,
427 uint64_t start, uint64_t end, GQuark q);
428 size_t bt_enum_get_nr_enumerators(struct declaration_enum *enum_declaration);
429
430 struct declaration_enum *
431 bt_enum_declaration_new(struct declaration_integer *integer_declaration);
432
433 struct declaration_string *
434 bt_string_declaration_new(enum ctf_string_encoding encoding);
435 char *bt_get_string(const struct bt_definition *field);
436 enum ctf_string_encoding bt_get_string_encoding(const struct bt_definition *field);
437
438 double bt_get_float(const struct bt_definition *field);
439
440 const struct bt_definition *bt_get_variant_field(struct bt_definition *definition);
441
442 struct declaration_struct *
443 bt_struct_declaration_new(struct declaration_scope *parent_scope,
444 uint64_t min_align);
445 void bt_struct_declaration_add_field(struct declaration_struct *struct_declaration,
446 const char *field_name,
447 struct bt_declaration *field_declaration);
448 /*
449 * Returns the index of a field within a structure.
450 */
451 int bt_struct_declaration_lookup_field_index(struct declaration_struct *struct_declaration,
452 GQuark field_name);
453 /*
454 * field returned only valid as long as the field structure is not appended to.
455 */
456 struct declaration_field *
457 bt_struct_declaration_get_field_from_index(struct declaration_struct *struct_declaration,
458 int index);
459 struct bt_definition *
460 bt_struct_definition_get_field_from_index(struct definition_struct *struct_definition,
461 int index);
462 int bt_struct_rw(struct bt_stream_pos *pos, struct bt_definition *definition);
463 uint64_t bt_struct_declaration_len(struct declaration_struct *struct_declaration);
464
465 /*
466 * The tag enumeration is validated to ensure that it contains only mappings
467 * from numeric values to a single tag. Overlapping tag value ranges are
468 * therefore forbidden.
469 */
470 struct declaration_untagged_variant *bt_untagged_bt_variant_declaration_new(
471 struct declaration_scope *parent_scope);
472 struct declaration_variant *bt_variant_declaration_new(struct declaration_untagged_variant *untagged_variant,
473 const char *tag);
474
475 void bt_untagged_variant_declaration_add_field(struct declaration_untagged_variant *untagged_variant_declaration,
476 const char *field_name,
477 struct bt_declaration *field_declaration);
478 struct declaration_field *
479 bt_untagged_variant_declaration_get_field_from_tag(struct declaration_untagged_variant *untagged_variant_declaration,
480 GQuark tag);
481 /*
482 * Returns 0 on success, -EPERM on error.
483 */
484 int variant_definition_set_tag(struct definition_variant *variant,
485 struct bt_definition *enum_tag);
486 /*
487 * Returns the field selected by the current tag value.
488 * field returned only valid as long as the variant structure is not appended
489 * to.
490 */
491 struct bt_definition *bt_variant_get_current_field(struct definition_variant *variant);
492 int bt_variant_rw(struct bt_stream_pos *pos, struct bt_definition *definition);
493
494 /*
495 * elem_declaration passed as parameter now belongs to the array. No
496 * need to free it explicitly. "len" is the number of elements in the
497 * array.
498 */
499 struct declaration_array *
500 bt_array_declaration_new(size_t len, struct bt_declaration *elem_declaration,
501 struct declaration_scope *parent_scope);
502 uint64_t bt_array_len(struct definition_array *array);
503 struct bt_definition *bt_array_index(struct definition_array *array, uint64_t i);
504 int bt_array_rw(struct bt_stream_pos *pos, struct bt_definition *definition);
505 GString *bt_get_char_array(const struct bt_definition *field);
506 int bt_get_array_len(const struct bt_definition *field);
507
508 /*
509 * int_declaration and elem_declaration passed as parameter now belong
510 * to the sequence. No need to free them explicitly.
511 */
512 struct declaration_sequence *
513 bt_sequence_declaration_new(const char *length_name,
514 struct bt_declaration *elem_declaration,
515 struct declaration_scope *parent_scope);
516 uint64_t bt_sequence_len(struct definition_sequence *sequence);
517 struct bt_definition *bt_sequence_index(struct definition_sequence *sequence, uint64_t i);
518 int bt_sequence_rw(struct bt_stream_pos *pos, struct bt_definition *definition);
519
520 /*
521 * in: path (dot separated), out: q (GArray of GQuark)
522 */
523 void bt_append_scope_path(const char *path, GArray *q);
524
525 /*
526 * Lookup helpers.
527 */
528 struct bt_definition *bt_lookup_definition(const struct bt_definition *definition,
529 const char *field_name);
530 struct definition_integer *bt_lookup_integer(const struct bt_definition *definition,
531 const char *field_name,
532 int signedness);
533 struct definition_enum *bt_lookup_enum(const struct bt_definition *definition,
534 const char *field_name,
535 int signedness);
536 struct bt_definition *bt_lookup_variant(const struct bt_definition *definition,
537 const char *field_name);
538
539 static inline
540 const char *rem_(const char *str)
541 {
542 if (str[0] == '_')
543 return &str[1];
544 else
545 return str;
546 }
547
548 #endif /* _BABELTRACE_TYPES_H */
This page took 0.04018 seconds and 3 git commands to generate.