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