binutils (2.41)
1 /* CTF format description.
2 Copyright (C) 2019-2023 Free Software Foundation, Inc.
3
4 This file is part of libctf.
5
6 libctf is free software; you can redistribute it and/or modify it under
7 the terms of the GNU General Public License as published by the Free
8 Software Foundation; either version 3, or (at your option) any later
9 version.
10
11 This program is distributed in the hope that it will be useful, but
12 WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 See the GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program; see the file COPYING. If not see
18 <http://www.gnu.org/licenses/>. */
19
20 #ifndef _CTF_H
21 #define _CTF_H
22
23 #include <sys/types.h>
24 #include <limits.h>
25 #include <stdint.h>
26
27
28 #ifdef __cplusplus
29 extern "C"
30 {
31 #endif
32
33 /* CTF - Compact ANSI-C Type Format
34
35 This file format can be used to compactly represent the information needed
36 by a debugger to interpret the ANSI-C types used by a given program.
37 Traditionally, this kind of information is generated by the compiler when
38 invoked with the -g flag and is stored in "stabs" strings or in the more
39 modern DWARF format. CTF provides a representation of only the information
40 that is relevant to debugging a complex, optimized C program such as the
41 operating system kernel in a form that is significantly more compact than
42 the equivalent stabs or DWARF representation. The format is data-model
43 independent, so consumers do not need different code depending on whether
44 they are 32-bit or 64-bit programs; libctf automatically compensates for
45 endianness variations. CTF assumes that a standard ELF symbol table is
46 available for use in the debugger, and uses the structure and data of the
47 symbol table to avoid storing redundant information. The CTF data may be
48 compressed on disk or in memory, indicated by a bit in the header. CTF may
49 be interpreted in a raw disk file, or it may be stored in an ELF section,
50 typically named .ctf. Data structures are aligned so that a raw CTF file or
51 CTF ELF section may be manipulated using mmap(2).
52
53 The CTF file or section itself has the following structure:
54
55 +--------+--------+---------+----------+--------+----------+...
56 | file | type | data | function | object | function |...
57 | header | labels | objects | info | index | index |...
58 +--------+--------+---------+----------+--------+----------+...
59
60 ...+----------+-------+--------+
61 ...| variable | data | string |
62 ...| info | types | table |
63 +----------+-------+--------+
64
65 The file header stores a magic number and version information, encoding
66 flags, and the byte offset of each of the sections relative to the end of the
67 header itself. If the CTF data has been uniquified against another set of
68 CTF data, a reference to that data also appears in the the header. This
69 reference is the name of the label corresponding to the types uniquified
70 against.
71
72 Following the header is a list of labels, used to group the types included in
73 the data types section. Each label is accompanied by a type ID i. A given
74 label refers to the group of types whose IDs are in the range [0, i].
75
76 Data object and function records (collectively, "symtypetabs") are stored in
77 the same order as they appear in the corresponding symbol table, except that
78 symbols marked SHN_UNDEF are not stored and symbols that have no type data
79 are padded out with zeroes. For each entry in these tables, the type ID (a
80 small integer) is recorded. (Functions get CTF_K_FUNCTION types, just like
81 data objects that are function pointers.)
82
83 For situations in which the order of the symbols in the symtab is not known,
84 or most symbols have no type in this dict and most entries would be
85 zero-pads, a pair of optional indexes follow the data object and function
86 info sections: each of these is an array of strtab indexes, mapped 1:1 to the
87 corresponding data object / function info section, giving each entry in those
88 sections a name so that the linker can correlate them with final symtab
89 entries and reorder them accordingly (dropping the indexes in the process).
90
91 Variable records (as distinct from data objects) provide a modicum of support
92 for non-ELF systems, mapping a variable or function name to a CTF type ID.
93 The names are sorted into ASCIIbetical order, permitting binary searching.
94 We do not define how the consumer maps these variable names to addresses or
95 anything else, or indeed what these names represent: they might be names
96 looked up at runtime via dlsym() or names extracted at runtime by a debugger
97 or anything else the consumer likes. Variable records with identically-
98 named entries in the data object or function index section are removed.
99
100 The data types section is a list of variable size records that represent each
101 type, in order by their ID. The types themselves form a directed graph,
102 where each node may contain one or more outgoing edges to other type nodes,
103 denoted by their ID. Most type nodes are standalone or point backwards to
104 earlier nodes, but this is not required: nodes can point to later nodes,
105 particularly structure and union members.
106
107 Strings are recorded as a string table ID (0 or 1) and a byte offset into the
108 string table. String table 0 is the internal CTF string table. String table
109 1 is the external string table, which is the string table associated with the
110 ELF dynamic symbol table for this object. CTF does not record any strings
111 that are already in the symbol table, and the CTF string table does not
112 contain any duplicated strings.
113
114 If the CTF data has been merged with another parent CTF object, some outgoing
115 edges may refer to type nodes that exist in another CTF object. The debugger
116 and libctf library are responsible for connecting the appropriate objects
117 together so that the full set of types can be explored and manipulated.
118
119 This connection is done purely using the ctf_import() function. The
120 ctf_archive machinery (and thus ctf_open et al) automatically imports archive
121 members named ".ctf" into child dicts if available in the same archive, to
122 match the relationship set up by the linker, but callers can call ctf_import
123 themselves as well if need be, if they know a different relationship is in
124 force. */
125
126 #define CTF_MAX_TYPE 0xfffffffe /* Max type identifier value. */
127 #define CTF_MAX_PTYPE 0x7fffffff /* Max parent type identifier value. */
128 #define CTF_MAX_NAME 0x7fffffff /* Max offset into a string table. */
129 #define CTF_MAX_VLEN 0xffffff /* Max struct, union, enum members or args. */
130
131 /* See ctf_type_t */
132 #define CTF_MAX_SIZE 0xfffffffe /* Max size of a v2 type in bytes. */
133 #define CTF_LSIZE_SENT 0xffffffff /* Sentinel for v2 ctt_size. */
134
135 # define CTF_MAX_TYPE_V1 0xffff /* Max type identifier value. */
136 # define CTF_MAX_PTYPE_V1 0x7fff /* Max parent type identifier value. */
137 # define CTF_MAX_VLEN_V1 0x3ff /* Max struct, union, enums or args. */
138 # define CTF_MAX_SIZE_V1 0xfffe /* Max size of a type in bytes. */
139 # define CTF_LSIZE_SENT_V1 0xffff /* Sentinel for v1 ctt_size. */
140
141 /* Start of actual data structure definitions.
142
143 Every field in these structures must have corresponding code in the
144 endianness-swapping machinery in libctf/ctf-open.c. */
145
146 typedef struct ctf_preamble
147 {
148 unsigned short ctp_magic; /* Magic number (CTF_MAGIC). */
149 unsigned char ctp_version; /* Data format version number (CTF_VERSION). */
150 unsigned char ctp_flags; /* Flags (see below). */
151 } ctf_preamble_t;
152
153 typedef struct ctf_header_v2
154 {
155 ctf_preamble_t cth_preamble;
156 uint32_t cth_parlabel; /* Ref to name of parent lbl uniq'd against. */
157 uint32_t cth_parname; /* Ref to basename of parent. */
158 uint32_t cth_lbloff; /* Offset of label section. */
159 uint32_t cth_objtoff; /* Offset of object section. */
160 uint32_t cth_funcoff; /* Offset of function section. */
161 uint32_t cth_varoff; /* Offset of variable section. */
162 uint32_t cth_typeoff; /* Offset of type section. */
163 uint32_t cth_stroff; /* Offset of string section. */
164 uint32_t cth_strlen; /* Length of string section in bytes. */
165 } ctf_header_v2_t;
166
167 typedef struct ctf_header
168 {
169 ctf_preamble_t cth_preamble;
170 uint32_t cth_parlabel; /* Ref to name of parent lbl uniq'd against. */
171 uint32_t cth_parname; /* Ref to basename of parent. */
172 uint32_t cth_cuname; /* Ref to CU name (may be 0). */
173 uint32_t cth_lbloff; /* Offset of label section. */
174 uint32_t cth_objtoff; /* Offset of object section. */
175 uint32_t cth_funcoff; /* Offset of function section. */
176 uint32_t cth_objtidxoff; /* Offset of object index section. */
177 uint32_t cth_funcidxoff; /* Offset of function index section. */
178 uint32_t cth_varoff; /* Offset of variable section. */
179 uint32_t cth_typeoff; /* Offset of type section. */
180 uint32_t cth_stroff; /* Offset of string section. */
181 uint32_t cth_strlen; /* Length of string section in bytes. */
182 } ctf_header_t;
183
184 #define cth_magic cth_preamble.ctp_magic
185 #define cth_version cth_preamble.ctp_version
186 #define cth_flags cth_preamble.ctp_flags
187
188 #define CTF_MAGIC 0xdff2 /* Magic number identifying header. */
189
190 /* Data format version number. */
191
192 /* v1 upgraded to a later version is not quite the same as the native form,
193 because the boundary between parent and child types is different but not
194 recorded anywhere, and you can write it out again via ctf_compress_write(),
195 so we must track whether the thing was originally v1 or not. If we were
196 writing the header from scratch, we would add a *pair* of version number
197 fields to allow for this, but this will do for now. (A flag will not do,
198 because we need to encode both the version we came from and the version we
199 went to, not just "we were upgraded".) */
200
201 # define CTF_VERSION_1 1
202 # define CTF_VERSION_1_UPGRADED_3 2
203 # define CTF_VERSION_2 3
204
205 #define CTF_VERSION_3 4
206 #define CTF_VERSION CTF_VERSION_3 /* Current version. */
207
208 /* All of these flags bar CTF_F_COMPRESS and CTF_F_IDXSORTED are bug-workaround
209 flags and are valid only in format v3: in v2 and below they cannot occur and
210 in v4 and later, they will be recycled for other purposes. */
211
212 #define CTF_F_COMPRESS 0x1 /* Data buffer is compressed by libctf. */
213 #define CTF_F_NEWFUNCINFO 0x2 /* New v3 func info section format. */
214 #define CTF_F_IDXSORTED 0x4 /* Index sections already sorted. */
215 #define CTF_F_DYNSTR 0x8 /* Strings come from .dynstr. */
216 #define CTF_F_MAX (CTF_F_COMPRESS | CTF_F_NEWFUNCINFO | CTF_F_IDXSORTED \
217 | CTF_F_DYNSTR)
218
219 typedef struct ctf_lblent
220 {
221 uint32_t ctl_label; /* Ref to name of label. */
222 uint32_t ctl_type; /* Last type associated with this label. */
223 } ctf_lblent_t;
224
225 typedef struct ctf_varent
226 {
227 uint32_t ctv_name; /* Reference to name in string table. */
228 uint32_t ctv_type; /* Index of type of this variable. */
229 } ctf_varent_t;
230
231 /* In format v2, type sizes, measured in bytes, come in two flavours. Nearly
232 all of them fit into a (UINT_MAX - 1), and thus can be stored in the ctt_size
233 member of a ctf_stype_t. The maximum value for these sizes is CTF_MAX_SIZE.
234 Types larger than this must be stored in the ctf_lsize member of a
235 ctf_type_t. Use of this member is indicated by the presence of
236 CTF_LSIZE_SENT in ctt_size. */
237
238 /* In v1, the same applies, only the limit is (USHRT_MAX - 1) and
239 CTF_MAX_SIZE_V1, and CTF_LSIZE_SENT_V1 is the sentinel. */
240
241 typedef struct ctf_stype_v1
242 {
243 uint32_t ctt_name; /* Reference to name in string table. */
244 unsigned short ctt_info; /* Encoded kind, variant length (see below). */
245 #ifndef __GNUC__
246 union
247 {
248 unsigned short _size; /* Size of entire type in bytes. */
249 unsigned short _type; /* Reference to another type. */
250 } _u;
251 #else
252 __extension__
253 union
254 {
255 unsigned short ctt_size; /* Size of entire type in bytes. */
256 unsigned short ctt_type; /* Reference to another type. */
257 };
258 #endif
259 } ctf_stype_v1_t;
260
261 typedef struct ctf_type_v1
262 {
263 uint32_t ctt_name; /* Reference to name in string table. */
264 unsigned short ctt_info; /* Encoded kind, variant length (see below). */
265 #ifndef __GNUC__
266 union
267 {
268 unsigned short _size; /* Always CTF_LSIZE_SENT_V1. */
269 unsigned short _type; /* Do not use. */
270 } _u;
271 #else
272 __extension__
273 union
274 {
275 unsigned short ctt_size; /* Always CTF_LSIZE_SENT_V1. */
276 unsigned short ctt_type; /* Do not use. */
277 };
278 #endif
279 uint32_t ctt_lsizehi; /* High 32 bits of type size in bytes. */
280 uint32_t ctt_lsizelo; /* Low 32 bits of type size in bytes. */
281 } ctf_type_v1_t;
282
283
284 typedef struct ctf_stype
285 {
286 uint32_t ctt_name; /* Reference to name in string table. */
287 uint32_t ctt_info; /* Encoded kind, variant length (see below). */
288 #ifndef __GNUC__
289 union
290 {
291 uint32_t _size; /* Size of entire type in bytes. */
292 uint32_t _type; /* Reference to another type. */
293 } _u;
294 #else
295 __extension__
296 union
297 {
298 uint32_t ctt_size; /* Size of entire type in bytes. */
299 uint32_t ctt_type; /* Reference to another type. */
300 };
301 #endif
302 } ctf_stype_t;
303
304 typedef struct ctf_type
305 {
306 uint32_t ctt_name; /* Reference to name in string table. */
307 uint32_t ctt_info; /* Encoded kind, variant length (see below). */
308 #ifndef __GNUC__
309 union
310 {
311 uint32_t _size; /* Always CTF_LSIZE_SENT. */
312 uint32_t _type; /* Do not use. */
313 } _u;
314 #else
315 __extension__
316 union
317 {
318 uint32_t ctt_size; /* Always CTF_LSIZE_SENT. */
319 uint32_t ctt_type; /* Do not use. */
320 };
321 #endif
322 uint32_t ctt_lsizehi; /* High 32 bits of type size in bytes. */
323 uint32_t ctt_lsizelo; /* Low 32 bits of type size in bytes. */
324 } ctf_type_t;
325
326 #ifndef __GNUC__
327 #define ctt_size _u._size /* For fundamental types that have a size. */
328 #define ctt_type _u._type /* For types that reference another type. */
329 #endif
330
331 /* The following macros and inline functions compose and decompose values for
332 ctt_info and ctt_name, as well as other structures that contain name
333 references. Use outside libdtrace-ctf itself is explicitly for access to CTF
334 files directly: types returned from the library will always appear to be
335 CTF_V2.
336
337 v1: (transparently upgraded to v2 at open time: may be compiled out of the
338 library)
339 ------------------------
340 ctt_info: | kind | isroot | vlen |
341 ------------------------
342 15 11 10 9 0
343
344 v2:
345 ------------------------
346 ctt_info: | kind | isroot | vlen |
347 ------------------------
348 31 26 25 24 0
349
350 CTF_V1 and V2 _INFO_VLEN have the same interface:
351
352 kind = CTF_*_INFO_KIND(c.ctt_info); <-- CTF_K_* value (see below)
353 vlen = CTF_*_INFO_VLEN(fp, c.ctt_info); <-- length of variable data list
354
355 stid = CTF_NAME_STID(c.ctt_name); <-- string table id number (0 or 1)
356 offset = CTF_NAME_OFFSET(c.ctt_name); <-- string table byte offset
357
358 c.ctt_info = CTF_TYPE_INFO(kind, vlen);
359 c.ctt_name = CTF_TYPE_NAME(stid, offset); */
360
361 #define CTF_V1_INFO_KIND(info) (((info) & 0xf800) >> 11)
362 #define CTF_V1_INFO_ISROOT(info) (((info) & 0x0400) >> 10)
363 #define CTF_V1_INFO_VLEN(info) (((info) & CTF_MAX_VLEN_V1))
364
365 #define CTF_V2_INFO_KIND(info) (((info) & 0xfc000000) >> 26)
366 #define CTF_V2_INFO_ISROOT(info) (((info) & 0x2000000) >> 25)
367 #define CTF_V2_INFO_VLEN(info) (((info) & CTF_MAX_VLEN))
368
369 #define CTF_NAME_STID(name) ((name) >> 31)
370 #define CTF_NAME_OFFSET(name) ((name) & CTF_MAX_NAME)
371 #define CTF_SET_STID(name, stid) ((name) | ((unsigned int) stid) << 31)
372
373 /* V2 only. */
374 #define CTF_TYPE_INFO(kind, isroot, vlen) \
375 (((kind) << 26) | (((isroot) ? 1 : 0) << 25) | ((vlen) & CTF_MAX_VLEN))
376
377 #define CTF_TYPE_NAME(stid, offset) \
378 (((stid) << 31) | ((offset) & CTF_MAX_NAME))
379
380 /* The next set of macros are for public consumption only. Not used internally,
381 since the relevant type boundary is dependent upon the version of the file at
382 *opening* time, not the version after transparent upgrade. Use
383 ctf_type_isparent() / ctf_type_ischild() for that. */
384
385 #define CTF_V2_TYPE_ISPARENT(fp, id) ((id) <= CTF_MAX_PTYPE)
386 #define CTF_V2_TYPE_ISCHILD(fp, id) ((id) > CTF_MAX_PTYPE)
387 #define CTF_V2_TYPE_TO_INDEX(id) ((id) & CTF_MAX_PTYPE)
388 #define CTF_V2_INDEX_TO_TYPE(id, child) ((child) ? ((id) | (CTF_MAX_PTYPE+1)) : (id))
389
390 #define CTF_V1_TYPE_ISPARENT(fp, id) ((id) <= CTF_MAX_PTYPE_V1)
391 #define CTF_V1_TYPE_ISCHILD(fp, id) ((id) > CTF_MAX_PTYPE_V1)
392 #define CTF_V1_TYPE_TO_INDEX(id) ((id) & CTF_MAX_PTYPE_V1)
393 #define CTF_V1_INDEX_TO_TYPE(id, child) ((child) ? ((id) | (CTF_MAX_PTYPE_V1+1)) : (id))
394
395 /* Valid for both V1 and V2. */
396 #define CTF_TYPE_LSIZE(cttp) \
397 (((uint64_t)(cttp)->ctt_lsizehi) << 32 | (cttp)->ctt_lsizelo)
398 #define CTF_SIZE_TO_LSIZE_HI(size) ((uint32_t)((uint64_t)(size) >> 32))
399 #define CTF_SIZE_TO_LSIZE_LO(size) ((uint32_t)(size))
400
401 #define CTF_STRTAB_0 0 /* String table id 0 (in-CTF). */
402 #define CTF_STRTAB_1 1 /* String table id 1 (ELF strtab). */
403
404 /* Values for CTF_TYPE_KIND(). If the kind has an associated data list,
405 CTF_INFO_VLEN() will extract the number of elements in the list, and
406 the type of each element is shown in the comments below. */
407
408 #define CTF_K_UNKNOWN 0 /* Unknown type (used for padding and
409 unrepresentable types). */
410 #define CTF_K_INTEGER 1 /* Variant data is CTF_INT_DATA (see below). */
411 #define CTF_K_FLOAT 2 /* Variant data is CTF_FP_DATA (see below). */
412 #define CTF_K_POINTER 3 /* ctt_type is referenced type. */
413 #define CTF_K_ARRAY 4 /* Variant data is single ctf_array_t. */
414 #define CTF_K_FUNCTION 5 /* ctt_type is return type, variant data is
415 list of argument types (unsigned short's for v1,
416 uint32_t's for v2). */
417 #define CTF_K_STRUCT 6 /* Variant data is list of ctf_member_t's. */
418 #define CTF_K_UNION 7 /* Variant data is list of ctf_member_t's. */
419 #define CTF_K_ENUM 8 /* Variant data is list of ctf_enum_t's. */
420 #define CTF_K_FORWARD 9 /* No additional data; ctt_name is tag. */
421 #define CTF_K_TYPEDEF 10 /* ctt_type is referenced type. */
422 #define CTF_K_VOLATILE 11 /* ctt_type is base type. */
423 #define CTF_K_CONST 12 /* ctt_type is base type. */
424 #define CTF_K_RESTRICT 13 /* ctt_type is base type. */
425 #define CTF_K_SLICE 14 /* Variant data is a ctf_slice_t. */
426
427 #define CTF_K_MAX 63 /* Maximum possible (V2) CTF_K_* value. */
428
429 /* Values for ctt_type when kind is CTF_K_INTEGER. The flags, offset in bits,
430 and size in bits are encoded as a single word using the following macros.
431 (However, you can also encode the offset and bitness in a slice.) */
432
433 #define CTF_INT_ENCODING(data) (((data) & 0xff000000) >> 24)
434 #define CTF_INT_OFFSET(data) (((data) & 0x00ff0000) >> 16)
435 #define CTF_INT_BITS(data) (((data) & 0x0000ffff))
436
437 #define CTF_INT_DATA(encoding, offset, bits) \
438 (((encoding) << 24) | ((offset) << 16) | (bits))
439
440 #define CTF_INT_SIGNED 0x01 /* Integer is signed (otherwise unsigned). */
441 #define CTF_INT_CHAR 0x02 /* Character display format. */
442 #define CTF_INT_BOOL 0x04 /* Boolean display format. */
443 #define CTF_INT_VARARGS 0x08 /* Varargs display format. */
444
445 /* Use CTF_CHAR to produce a char that agrees with the system's native
446 char signedness. */
447 #if CHAR_MIN == 0
448 # define CTF_CHAR (CTF_INT_CHAR)
449 #else
450 # define CTF_CHAR (CTF_INT_CHAR | CTF_INT_SIGNED)
451 #endif
452
453 /* Values for ctt_type when kind is CTF_K_FLOAT. The encoding, offset in bits,
454 and size in bits are encoded as a single word using the following macros.
455 (However, you can also encode the offset and bitness in a slice.) */
456
457 #define CTF_FP_ENCODING(data) (((data) & 0xff000000) >> 24)
458 #define CTF_FP_OFFSET(data) (((data) & 0x00ff0000) >> 16)
459 #define CTF_FP_BITS(data) (((data) & 0x0000ffff))
460
461 #define CTF_FP_DATA(encoding, offset, bits) \
462 (((encoding) << 24) | ((offset) << 16) | (bits))
463
464 /* Variant data when kind is CTF_K_FLOAT is an encoding in the top eight bits. */
465 #define CTF_FP_ENCODING(data) (((data) & 0xff000000) >> 24)
466
467 #define CTF_FP_SINGLE 1 /* IEEE 32-bit float encoding. */
468 #define CTF_FP_DOUBLE 2 /* IEEE 64-bit float encoding. */
469 #define CTF_FP_CPLX 3 /* Complex encoding. */
470 #define CTF_FP_DCPLX 4 /* Double complex encoding. */
471 #define CTF_FP_LDCPLX 5 /* Long double complex encoding. */
472 #define CTF_FP_LDOUBLE 6 /* Long double encoding. */
473 #define CTF_FP_INTRVL 7 /* Interval (2x32-bit) encoding. */
474 #define CTF_FP_DINTRVL 8 /* Double interval (2x64-bit) encoding. */
475 #define CTF_FP_LDINTRVL 9 /* Long double interval (2x128-bit) encoding. */
476 #define CTF_FP_IMAGRY 10 /* Imaginary (32-bit) encoding. */
477 #define CTF_FP_DIMAGRY 11 /* Long imaginary (64-bit) encoding. */
478 #define CTF_FP_LDIMAGRY 12 /* Long double imaginary (128-bit) encoding. */
479
480 #define CTF_FP_MAX 12 /* Maximum possible CTF_FP_* value */
481
482 /* A slice increases the offset and reduces the bitness of the referenced
483 ctt_type, which must be a type which has an encoding (fp, int, or enum). We
484 also store the referenced type in here, because it is easier to keep the
485 ctt_size correct for the slice than to shuffle the size into here and keep
486 the ctt_type where it is for other types.
487
488 In a future version, where we loosen requirements on alignment in the CTF
489 file, the cts_offset and cts_bits will be chars: but for now they must be
490 shorts or everything after a slice will become unaligned. */
491
492 typedef struct ctf_slice
493 {
494 uint32_t cts_type;
495 unsigned short cts_offset;
496 unsigned short cts_bits;
497 } ctf_slice_t;
498
499 typedef struct ctf_array_v1
500 {
501 unsigned short cta_contents; /* Reference to type of array contents. */
502 unsigned short cta_index; /* Reference to type of array index. */
503 uint32_t cta_nelems; /* Number of elements. */
504 } ctf_array_v1_t;
505
506 typedef struct ctf_array
507 {
508 uint32_t cta_contents; /* Reference to type of array contents. */
509 uint32_t cta_index; /* Reference to type of array index. */
510 uint32_t cta_nelems; /* Number of elements. */
511 } ctf_array_t;
512
513 /* Most structure members have bit offsets that can be expressed using a short.
514 Some don't. ctf_member_t is used for structs which cannot contain any of
515 these large offsets, whereas ctf_lmember_t is used in the latter case. If
516 any member of a given struct has an offset that cannot be expressed using a
517 uint32_t, all members will be stored as type ctf_lmember_t. This is expected
518 to be very rare (but nonetheless possible). */
519
520 #define CTF_LSTRUCT_THRESH 536870912
521
522 /* In v1, the same is true, except that lmembers are used for structs >= 8192
523 bytes in size. (The ordering of members in the ctf_member_* structures is
524 different to improve padding.) */
525
526 #define CTF_LSTRUCT_THRESH_V1 8192
527
528 typedef struct ctf_member_v1
529 {
530 uint32_t ctm_name; /* Reference to name in string table. */
531 unsigned short ctm_type; /* Reference to type of member. */
532 unsigned short ctm_offset; /* Offset of this member in bits. */
533 } ctf_member_v1_t;
534
535 typedef struct ctf_lmember_v1
536 {
537 uint32_t ctlm_name; /* Reference to name in string table. */
538 unsigned short ctlm_type; /* Reference to type of member. */
539 unsigned short ctlm_pad; /* Padding. */
540 uint32_t ctlm_offsethi; /* High 32 bits of member offset in bits. */
541 uint32_t ctlm_offsetlo; /* Low 32 bits of member offset in bits. */
542 } ctf_lmember_v1_t;
543
544 typedef struct ctf_member_v2
545 {
546 uint32_t ctm_name; /* Reference to name in string table. */
547 uint32_t ctm_offset; /* Offset of this member in bits. */
548 uint32_t ctm_type; /* Reference to type of member. */
549 } ctf_member_t;
550
551 typedef struct ctf_lmember_v2
552 {
553 uint32_t ctlm_name; /* Reference to name in string table. */
554 uint32_t ctlm_offsethi; /* High 32 bits of member offset in bits. */
555 uint32_t ctlm_type; /* Reference to type of member. */
556 uint32_t ctlm_offsetlo; /* Low 32 bits of member offset in bits. */
557 } ctf_lmember_t;
558
559 #define CTF_LMEM_OFFSET(ctlmp) \
560 (((uint64_t)(ctlmp)->ctlm_offsethi) << 32 | (ctlmp)->ctlm_offsetlo)
561 #define CTF_OFFSET_TO_LMEMHI(offset) ((uint32_t)((uint64_t)(offset) >> 32))
562 #define CTF_OFFSET_TO_LMEMLO(offset) ((uint32_t)(offset))
563
564 typedef struct ctf_enum
565 {
566 uint32_t cte_name; /* Reference to name in string table. */
567 int32_t cte_value; /* Value associated with this name. */
568 } ctf_enum_t;
569
570 /* The ctf_archive is a collection of ctf_dict_t's stored together. The format
571 is suitable for mmap()ing: this control structure merely describes the
572 mmap()ed archive (and overlaps the first few bytes of it), hence the
573 greater care taken with integral types. All CTF files in an archive
574 must have the same data model. (This is not validated.)
575
576 All integers in this structure are stored in little-endian byte order.
577
578 The code relies on the fact that everything in this header is a uint64_t
579 and thus the header needs no padding (in particular, that no padding is
580 needed between ctfa_ctfs and the unnamed ctfa_archive_modent array
581 that follows it).
582
583 This is *not* the same as the data structure returned by the ctf_arc_*()
584 functions: this is the low-level on-disk representation. */
585
586 #define CTFA_MAGIC 0x8b47f2a4d7623eeb /* Random. */
587 struct ctf_archive
588 {
589 /* Magic number. (In loaded files, overwritten with the file size
590 so ctf_arc_close() knows how much to munmap()). */
591 uint64_t ctfa_magic;
592
593 /* CTF data model. */
594 uint64_t ctfa_model;
595
596 /* Number of CTF dicts in the archive. */
597 uint64_t ctfa_ndicts;
598
599 /* Offset of the name table. */
600 uint64_t ctfa_names;
601
602 /* Offset of the CTF table. Each element starts with a size (a little-
603 endian uint64_t) then a ctf_dict_t of that size. */
604 uint64_t ctfa_ctfs;
605 };
606
607 /* An array of ctfa_ndicts of this structure lies at
608 ctf_archive[sizeof(struct ctf_archive)] and gives the ctfa_ctfs or
609 ctfa_names-relative offsets of each name or ctf_dict_t. */
610
611 typedef struct ctf_archive_modent
612 {
613 uint64_t name_offset;
614 uint64_t ctf_offset;
615 } ctf_archive_modent_t;
616
617 #ifdef __cplusplus
618 }
619 #endif
620
621 #endif /* _CTF_H */
Browse
Usage
Versions