include/ctf-api.h

   1 /* Public API to libctf.
   2    Copyright (C) 2019 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 /* This header file defines the interfaces available from the CTF debugger
  21    library, libctf.  This API can be used by a debugger to operate on data in
  22    the Compact ANSI-C Type Format (CTF).  */
  23
  24 #ifndef _CTF_API_H
  25 #define _CTF_API_H
  26
  27 #include <sys/param.h>
  28 #include <sys/types.h>
  29 #include <ctf.h>
  30 #include <zlib.h>
  31
  32 #ifdef  __cplusplus
  33 extern "C"
  34   {
  35 #endif
  36
  37 /* Clients can open one or more CTF containers and obtain a pointer to an
  38    opaque ctf_file_t.  Types are identified by an opaque ctf_id_t token.
  39    They can also open or create read-only archives of CTF containers in a
  40    ctf_archive_t.
  41
  42    These opaque definitions allow libctf to evolve without breaking clients.  */
  43
  44 typedef struct ctf_file ctf_file_t;
  45 typedef struct ctf_archive_internal ctf_archive_t;
  46 typedef unsigned long ctf_id_t;
  47
  48 /* This opaque definition allows libctf to accept BFD data structures without
  49    importing all the BFD noise into users' namespaces.  */
  50
  51 struct bfd;
  52
  53 /* If the debugger needs to provide the CTF library with a set of raw buffers
  54    for use as the CTF data, symbol table, and string table, it can do so by
  55    filling in ctf_sect_t structures and passing them to ctf_bufopen().
  56
  57    The contents of this structure must always be in native endianness (no
  58    byteswapping is performed).  */
  59
  60 typedef struct ctf_sect
  61 {
  62   const char *cts_name;           /* Section name (if any).  */
  63   const void *cts_data;           /* Pointer to section data.  */
  64   size_t cts_size;                /* Size of data in bytes.  */
  65   size_t cts_entsize;             /* Size of each section entry (symtab only).  */
  66 } ctf_sect_t;
  67
  68 /* A minimal symbol extracted from a linker's internal symbol table
  69    representation.  */
  70
  71 typedef struct ctf_link_sym
  72 {
  73   /* The st_name will not be accessed outside the call to
  74      ctf_link_shuffle_syms().  */
  75
  76   const char *st_name;
  77   uint32_t st_shndx;
  78   uint32_t st_type;
  79   uint32_t st_value;
  80 } ctf_link_sym_t;
  81
  82 /* Indication of how to share types when linking.  */
  83
  84 /* Share all types thare are not in conflict.  The default.  */
  85 #define CTF_LINK_SHARE_UNCONFLICTED 0x0
  86
  87 /* Share only types that are used by multiple inputs.  Not implemented yet.  */
  88 #define CTF_LINK_SHARE_DUPLICATED 0x1
  89
  90 /* Symbolic names for CTF sections.  */
  91
  92 typedef enum ctf_sect_names
  93   {
  94    CTF_SECT_HEADER,
  95    CTF_SECT_LABEL,
  96    CTF_SECT_OBJT,
  97    CTF_SECT_FUNC,
  98    CTF_SECT_VAR,
  99    CTF_SECT_TYPE,
 100    CTF_SECT_STR
 101   } ctf_sect_names_t;
 102
 103 /* Encoding information for integers, floating-point values, and certain other
 104    intrinsics can be obtained by calling ctf_type_encoding(), below.  The flags
 105    field will contain values appropriate for the type defined in <ctf.h>.  */
 106
 107 typedef struct ctf_encoding
 108 {
 109   uint32_t cte_format;           /* Data format (CTF_INT_* or CTF_FP_* flags).  */
 110   uint32_t cte_offset;           /* Offset of value in bits.  */
 111   uint32_t cte_bits;             /* Size of storage in bits.  */
 112 } ctf_encoding_t;
 113
 114 typedef struct ctf_membinfo
 115 {
 116   ctf_id_t ctm_type;            /* Type of struct or union member.  */
 117   unsigned long ctm_offset;     /* Offset of member in bits.  */
 118 } ctf_membinfo_t;
 119
 120 typedef struct ctf_arinfo
 121 {
 122   ctf_id_t ctr_contents;        /* Type of array contents.  */
 123   ctf_id_t ctr_index;           /* Type of array index.  */
 124   uint32_t ctr_nelems;          /* Number of elements.  */
 125 } ctf_arinfo_t;
 126
 127 typedef struct ctf_funcinfo
 128 {
 129   ctf_id_t ctc_return;          /* Function return type.  */
 130   uint32_t ctc_argc;            /* Number of typed arguments to function.  */
 131   uint32_t ctc_flags;           /* Function attributes (see below).  */
 132 } ctf_funcinfo_t;
 133
 134 typedef struct ctf_lblinfo
 135 {
 136   ctf_id_t ctb_type;            /* Last type associated with the label.  */
 137 } ctf_lblinfo_t;
 138
 139 typedef struct ctf_snapshot_id
 140 {
 141   unsigned long dtd_id;         /* Highest DTD ID at time of snapshot.  */
 142   unsigned long snapshot_id;    /* Snapshot id at time of snapshot.  */
 143 } ctf_snapshot_id_t;
 144
 145 #define CTF_FUNC_VARARG 0x1     /* Function arguments end with varargs.  */
 146
 147 /* Functions that return a ctf_id_t use the following value to indicate failure.
 148    ctf_errno() can be used to obtain an error code.  Functions that return
 149    a straight integral -1 also use ctf_errno().  */
 150 #define CTF_ERR ((ctf_id_t) -1L)
 151
 152 #define ECTF_BASE       1000    /* Base value for libctf errnos.  */
 153
 154
 155 enum
 156   {
 157    ECTF_FMT = ECTF_BASE,        /* File is not in CTF or ELF format.  */
 158    ECTF_BFDERR,                 /* BFD error.  */
 159    ECTF_CTFVERS,                /* CTF version is more recent than libctf.  */
 160    ECTF_BFD_AMBIGUOUS,          /* Ambiguous BFD target.  */
 161    ECTF_SYMTAB,                 /* Symbol table uses invalid entry size.  */
 162    ECTF_SYMBAD,                 /* Symbol table data buffer invalid.  */
 163    ECTF_STRBAD,                 /* String table data buffer invalid.  */
 164    ECTF_CORRUPT,                /* File data corruption detected.  */
 165    ECTF_NOCTFDATA,              /* ELF file does not contain CTF data.  */
 166    ECTF_NOCTFBUF,               /* Buffer does not contain CTF data.  */
 167    ECTF_NOSYMTAB,               /* Symbol table data is not available.  */
 168    ECTF_NOPARENT,               /* Parent CTF container is not available.  */
 169    ECTF_DMODEL,                 /* Data model mismatch.  */
 170    ECTF_LINKADDEDLATE,          /* File added to link too late.  */
 171    ECTF_ZALLOC,                 /* Failed to allocate (de)compression buffer.  */
 172    ECTF_DECOMPRESS,             /* Failed to decompress CTF data.  */
 173    ECTF_STRTAB,                 /* String table for this string is missing.  */
 174    ECTF_BADNAME,                /* String offset is corrupt w.r.t. strtab.  */
 175    ECTF_BADID,                  /* Invalid type ID number.  */
 176    ECTF_NOTSOU,                 /* Type is not a struct or union.  */
 177    ECTF_NOTENUM,                /* Type is not an enum.  */
 178    ECTF_NOTSUE,                 /* Type is not a struct, union, or enum.  */
 179    ECTF_NOTINTFP,               /* Type is not an integer, float, or enum.  */
 180    ECTF_NOTARRAY,               /* Type is not an array.  */
 181    ECTF_NOTREF,                 /* Type does not reference another type.  */
 182    ECTF_NAMELEN,                /* Buffer is too small to hold type name.  */
 183    ECTF_NOTYPE,                 /* No type found corresponding to name.  */
 184    ECTF_SYNTAX,                 /* Syntax error in type name.  */
 185    ECTF_NOTFUNC,                /* Symbol entry or type is not a function.  */
 186    ECTF_NOFUNCDAT,              /* No func info available for function.  */
 187    ECTF_NOTDATA,                /* Symtab entry does not refer to a data obj.  */
 188    ECTF_NOTYPEDAT,              /* No type info available for object.  */
 189    ECTF_NOLABEL,                /* No label found corresponding to name.  */
 190    ECTF_NOLABELDATA,            /* File does not contain any labels.  */
 191    ECTF_NOTSUP,                 /* Feature not supported.  */
 192    ECTF_NOENUMNAM,              /* Enum element name not found.  */
 193    ECTF_NOMEMBNAM,              /* Member name not found.  */
 194    ECTF_RDONLY,                 /* CTF container is read-only.  */
 195    ECTF_DTFULL,                 /* CTF type is full (no more members allowed).  */
 196    ECTF_FULL,                   /* CTF container is full.  */
 197    ECTF_DUPLICATE,              /* Duplicate member or variable name.  */
 198    ECTF_CONFLICT,               /* Conflicting type definition present.  */
 199    ECTF_OVERROLLBACK,           /* Attempt to roll back past a ctf_update.  */
 200    ECTF_COMPRESS,               /* Failed to compress CTF data.  */
 201    ECTF_ARCREATE,               /* Error creating CTF archive.  */
 202    ECTF_ARNNAME,                /* Name not found in CTF archive.  */
 203    ECTF_SLICEOVERFLOW,          /* Overflow of type bitness or offset in slice.  */
 204    ECTF_DUMPSECTUNKNOWN,        /* Unknown section number in dump.  */
 205    ECTF_DUMPSECTCHANGED,        /* Section changed in middle of dump.  */
 206    ECTF_NOTYET,                 /* Feature not yet implemented.  */
 207    ECTF_INTERNAL                /* Internal error in link.  */
 208   };
 209
 210 /* The CTF data model is inferred to be the caller's data model or the data
 211    model of the given object, unless ctf_setmodel() is explicitly called.  */
 212 #define CTF_MODEL_ILP32 1       /* Object data model is ILP32.  */
 213 #define CTF_MODEL_LP64  2       /* Object data model is LP64.  */
 214 #ifdef _LP64
 215 # define CTF_MODEL_NATIVE CTF_MODEL_LP64
 216 #else
 217 # define CTF_MODEL_NATIVE CTF_MODEL_ILP32
 218 #endif
 219
 220 /* Dynamic CTF containers can be created using ctf_create().  The ctf_add_*
 221    routines can be used to add new definitions to the dynamic container.
 222    New types are labeled as root or non-root to determine whether they are
 223    visible at the top-level program scope when subsequently doing a lookup.  */
 224
 225 #define CTF_ADD_NONROOT 0       /* Type only visible in nested scope.  */
 226 #define CTF_ADD_ROOT    1       /* Type visible at top-level scope.  */
 227
 228 /* These typedefs are used to define the signature for callback functions
 229    that can be used with the iteration and visit functions below.  */
 230
 231 typedef int ctf_visit_f (const char *name, ctf_id_t type, unsigned long offset,
 232                          int depth, void *arg);
 233 typedef int ctf_member_f (const char *name, ctf_id_t membtype,
 234                           unsigned long offset, void *arg);
 235 typedef int ctf_enum_f (const char *name, int val, void *arg);
 236 typedef int ctf_variable_f (const char *name, ctf_id_t type, void *arg);
 237 typedef int ctf_type_f (ctf_id_t type, void *arg);
 238 typedef int ctf_type_all_f (ctf_id_t type, int flag, void *arg);
 239 typedef int ctf_label_f (const char *name, const ctf_lblinfo_t *info,
 240                          void *arg);
 241 typedef int ctf_archive_member_f (ctf_file_t *fp, const char *name, void *arg);
 242 typedef int ctf_archive_raw_member_f (const char *name, const void *content,
 243                                       size_t len, void *arg);
 244 typedef char *ctf_dump_decorate_f (ctf_sect_names_t sect,
 245                                    char *line, void *arg);
 246
 247 typedef struct ctf_dump_state ctf_dump_state_t;
 248
 249 /* Opening.  These mostly return an abstraction over both CTF files and CTF
 250    archives: so they can be used to open both.  CTF files will appear to be an
 251    archive with one member named '.ctf'.  The low-level functions
 252    ctf_simple_open() and ctf_bufopen() return ctf_file_t's directly, and cannot
 253    be used on CTF archives.  */
 254
 255 extern ctf_archive_t *ctf_bfdopen (struct bfd *, int *);
 256 extern ctf_archive_t *ctf_bfdopen_ctfsect (struct bfd *, const ctf_sect_t *,
 257                                            int *);
 258 extern ctf_archive_t *ctf_fdopen (int fd, const char *filename,
 259                                   const char *target, int *errp);
 260 extern ctf_archive_t *ctf_open (const char *filename,
 261                                 const char *target, int *errp);
 262 extern void ctf_close (ctf_archive_t *);
 263 extern ctf_sect_t ctf_getdatasect (const ctf_file_t *);
 264 extern ctf_archive_t *ctf_get_arc (const ctf_file_t *);
 265 extern ctf_archive_t *ctf_arc_open (const char *, int *);
 266 extern void ctf_arc_close (ctf_archive_t *);
 267 extern ctf_file_t *ctf_arc_open_by_name (const ctf_archive_t *,
 268                                          const char *, int *);
 269 extern ctf_file_t *ctf_arc_open_by_name_sections (const ctf_archive_t *,
 270                                                   const ctf_sect_t *,
 271                                                   const ctf_sect_t *,
 272                                                   const char *, int *);
 273
 274 /* The next functions return or close real CTF files, or write out CTF archives,
 275    not opaque containers around either.  */
 276
 277 extern ctf_file_t *ctf_simple_open (const char *, size_t, const char *, size_t,
 278                                    size_t, const char *, size_t, int *);
 279 extern ctf_file_t *ctf_bufopen (const ctf_sect_t *, const ctf_sect_t *,
 280                                 const ctf_sect_t *, int *);
 281 extern void ctf_file_close (ctf_file_t *);
 282
 283 extern int ctf_arc_write (const char *, ctf_file_t **, size_t,
 284                           const char **, size_t);
 285 extern int ctf_arc_write_fd (int, ctf_file_t **, size_t, const char **,
 286                              size_t);
 287
 288 extern const char *ctf_cuname (ctf_file_t *);
 289 extern void ctf_cuname_set (ctf_file_t *, const char *);
 290 extern ctf_file_t *ctf_parent_file (ctf_file_t *);
 291 extern const char *ctf_parent_name (ctf_file_t *);
 292 extern void ctf_parent_name_set (ctf_file_t *, const char *);
 293 extern int ctf_type_isparent (ctf_file_t *, ctf_id_t);
 294 extern int ctf_type_ischild (ctf_file_t *, ctf_id_t);
 295
 296 extern int ctf_import (ctf_file_t *, ctf_file_t *);
 297 extern int ctf_setmodel (ctf_file_t *, int);
 298 extern int ctf_getmodel (ctf_file_t *);
 299
 300 extern void ctf_setspecific (ctf_file_t *, void *);
 301 extern void *ctf_getspecific (ctf_file_t *);
 302
 303 extern int ctf_errno (ctf_file_t *);
 304 extern const char *ctf_errmsg (int);
 305 extern int ctf_version (int);
 306
 307 extern int ctf_func_info (ctf_file_t *, unsigned long, ctf_funcinfo_t *);
 308 extern int ctf_func_args (ctf_file_t *, unsigned long, uint32_t, ctf_id_t *);
 309 extern int ctf_func_type_info (ctf_file_t *, ctf_id_t, ctf_funcinfo_t *);
 310 extern int ctf_func_type_args (ctf_file_t *, ctf_id_t, uint32_t, ctf_id_t *);
 311
 312 extern ctf_id_t ctf_lookup_by_name (ctf_file_t *, const char *);
 313 extern ctf_id_t ctf_lookup_by_symbol (ctf_file_t *, unsigned long);
 314 extern ctf_id_t ctf_lookup_variable (ctf_file_t *, const char *);
 315
 316 extern ctf_id_t ctf_type_resolve (ctf_file_t *, ctf_id_t);
 317 extern char *ctf_type_aname (ctf_file_t *, ctf_id_t);
 318 extern char *ctf_type_aname_raw (ctf_file_t *, ctf_id_t);
 319 extern ssize_t ctf_type_lname (ctf_file_t *, ctf_id_t, char *, size_t);
 320 extern char *ctf_type_name (ctf_file_t *, ctf_id_t, char *, size_t);
 321 extern ssize_t ctf_type_size (ctf_file_t *, ctf_id_t);
 322 extern ssize_t ctf_type_align (ctf_file_t *, ctf_id_t);
 323 extern int ctf_type_kind (ctf_file_t *, ctf_id_t);
 324 extern ctf_id_t ctf_type_reference (ctf_file_t *, ctf_id_t);
 325 extern ctf_id_t ctf_type_pointer (ctf_file_t *, ctf_id_t);
 326 extern int ctf_type_encoding (ctf_file_t *, ctf_id_t, ctf_encoding_t *);
 327 extern int ctf_type_visit (ctf_file_t *, ctf_id_t, ctf_visit_f *, void *);
 328 extern int ctf_type_cmp (ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
 329 extern int ctf_type_compat (ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
 330
 331 extern int ctf_member_info (ctf_file_t *, ctf_id_t, const char *,
 332                             ctf_membinfo_t *);
 333 extern int ctf_array_info (ctf_file_t *, ctf_id_t, ctf_arinfo_t *);
 334
 335 extern const char *ctf_enum_name (ctf_file_t *, ctf_id_t, int);
 336 extern int ctf_enum_value (ctf_file_t *, ctf_id_t, const char *, int *);
 337
 338 extern void ctf_label_set (ctf_file_t *, const char *);
 339 extern const char *ctf_label_get (ctf_file_t *);
 340
 341 extern const char *ctf_label_topmost (ctf_file_t *);
 342 extern int ctf_label_info (ctf_file_t *, const char *, ctf_lblinfo_t *);
 343
 344 extern int ctf_member_iter (ctf_file_t *, ctf_id_t, ctf_member_f *, void *);
 345 extern int ctf_enum_iter (ctf_file_t *, ctf_id_t, ctf_enum_f *, void *);
 346 extern int ctf_type_iter (ctf_file_t *, ctf_type_f *, void *);
 347 extern int ctf_type_iter_all (ctf_file_t *, ctf_type_all_f *, void *);
 348 extern int ctf_label_iter (ctf_file_t *, ctf_label_f *, void *);
 349 extern int ctf_variable_iter (ctf_file_t *, ctf_variable_f *, void *);
 350 extern int ctf_archive_iter (const ctf_archive_t *, ctf_archive_member_f *,
 351                              void *);
 352 /* This function alone does not currently operate on CTF files masquerading
 353    as archives, and returns -EINVAL: the raw data is no longer available.  It is
 354    expected to be used only by archiving tools, in any case, which have no need
 355    to deal with non-archives at all.  */
 356 extern int ctf_archive_raw_iter (const ctf_archive_t *,
 357                                  ctf_archive_raw_member_f *, void *);
 358 extern char *ctf_dump (ctf_file_t *, ctf_dump_state_t **state,
 359                        ctf_sect_names_t sect, ctf_dump_decorate_f *,
 360                        void *arg);
 361
 362 extern ctf_id_t ctf_add_array (ctf_file_t *, uint32_t,
 363                                const ctf_arinfo_t *);
 364 extern ctf_id_t ctf_add_const (ctf_file_t *, uint32_t, ctf_id_t);
 365 extern ctf_id_t ctf_add_enum_encoded (ctf_file_t *, uint32_t, const char *,
 366                                       const ctf_encoding_t *);
 367 extern ctf_id_t ctf_add_enum (ctf_file_t *, uint32_t, const char *);
 368 extern ctf_id_t ctf_add_float (ctf_file_t *, uint32_t,
 369                                const char *, const ctf_encoding_t *);
 370 extern ctf_id_t ctf_add_forward (ctf_file_t *, uint32_t, const char *,
 371                                  uint32_t);
 372 extern ctf_id_t ctf_add_function (ctf_file_t *, uint32_t,
 373                                   const ctf_funcinfo_t *, const ctf_id_t *);
 374 extern ctf_id_t ctf_add_integer (ctf_file_t *, uint32_t, const char *,
 375                                  const ctf_encoding_t *);
 376 extern ctf_id_t ctf_add_slice (ctf_file_t *, uint32_t, ctf_id_t, const ctf_encoding_t *);
 377 extern ctf_id_t ctf_add_pointer (ctf_file_t *, uint32_t, ctf_id_t);
 378 extern ctf_id_t ctf_add_type (ctf_file_t *, ctf_file_t *, ctf_id_t);
 379 extern ctf_id_t ctf_add_typedef (ctf_file_t *, uint32_t, const char *,
 380                                  ctf_id_t);
 381 extern ctf_id_t ctf_add_restrict (ctf_file_t *, uint32_t, ctf_id_t);
 382 extern ctf_id_t ctf_add_struct (ctf_file_t *, uint32_t, const char *);
 383 extern ctf_id_t ctf_add_union (ctf_file_t *, uint32_t, const char *);
 384 extern ctf_id_t ctf_add_struct_sized (ctf_file_t *, uint32_t, const char *,
 385                                       size_t);
 386 extern ctf_id_t ctf_add_union_sized (ctf_file_t *, uint32_t, const char *,
 387                                      size_t);
 388 extern ctf_id_t ctf_add_volatile (ctf_file_t *, uint32_t, ctf_id_t);
 389
 390 extern int ctf_add_enumerator (ctf_file_t *, ctf_id_t, const char *, int);
 391 extern int ctf_add_member (ctf_file_t *, ctf_id_t, const char *, ctf_id_t);
 392 extern int ctf_add_member_offset (ctf_file_t *, ctf_id_t, const char *,
 393                                   ctf_id_t, unsigned long);
 394 extern int ctf_add_member_encoded (ctf_file_t *, ctf_id_t, const char *,
 395                                    ctf_id_t, unsigned long,
 396                                    const ctf_encoding_t);
 397
 398 extern int ctf_add_variable (ctf_file_t *, const char *, ctf_id_t);
 399
 400 extern int ctf_set_array (ctf_file_t *, ctf_id_t, const ctf_arinfo_t *);
 401
 402 extern ctf_file_t *ctf_create (int *);
 403 extern int ctf_update (ctf_file_t *);
 404 extern ctf_snapshot_id_t ctf_snapshot (ctf_file_t *);
 405 extern int ctf_rollback (ctf_file_t *, ctf_snapshot_id_t);
 406 extern int ctf_discard (ctf_file_t *);
 407 extern int ctf_write (ctf_file_t *, int);
 408 extern int ctf_gzwrite (ctf_file_t *fp, gzFile fd);
 409 extern int ctf_compress_write (ctf_file_t * fp, int fd);
 410 extern unsigned char *ctf_write_mem (ctf_file_t *, size_t *, size_t threshold);
 411
 412 extern int ctf_link_add_ctf (ctf_file_t *, ctf_archive_t *, const char *);
 413 extern int ctf_link (ctf_file_t *, int share_mode);
 414 typedef const char *ctf_link_strtab_string_f (uint32_t *offset, void *arg);
 415 extern int ctf_link_add_strtab (ctf_file_t *, ctf_link_strtab_string_f *,
 416                                 void *);
 417 typedef ctf_link_sym_t *ctf_link_iter_symbol_f (ctf_link_sym_t *dest,
 418                                                 void *arg);
 419 extern int ctf_link_shuffle_syms (ctf_file_t *, ctf_link_iter_symbol_f *,
 420                                   void *);
 421 extern unsigned char *ctf_link_write (ctf_file_t *, size_t *size,
 422                                       size_t threshold);
 423
 424 extern void ctf_setdebug (int debug);
 425 extern int ctf_getdebug (void);
 426
 427 #ifdef  __cplusplus
 428 }
 429 #endif
 430
 431 #endif                          /* _CTF_API_H */