include/ctf.h

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