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