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