include/sys/ctf_api.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License, Version 1.0 only
   6  * (the "License").  You may not use this file except in compliance
   7  * with the License.
   8  *
   9  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10  * or http://www.opensolaris.org/os/licensing.
  11  * See the License for the specific language governing permissions
  12  * and limitations under the License.
  13  *
  14  * When distributing Covered Code, include this CDDL HEADER in each
  15  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16  * If applicable, add the following below this CDDL HEADER, with the
  17  * fields enclosed by brackets "[]" replaced with your own identifying
  18  * information: Portions Copyright [yyyy] [name of copyright owner]
  19  *
  20  * CDDL HEADER END
  21  */
  22 /*
  23  * Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
  24  * Use is subject to license terms.
  25  */
  26 /*
  27  * Copyright (c) 2015, Joyent, Inc.
  28  */
  29
  30 /*
  31  * This header file defines the interfaces available from the CTF debugger
  32  * library, libctf, and an equivalent kernel module.  This API can be used by
  33  * a debugger to operate on data in the Compact ANSI-C Type Format (CTF).
  34  * This is NOT a public interface, although it may eventually become one in
  35  * the fullness of time after we gain more experience with the interfaces.
  36  *
  37  * In the meantime, be aware that any program linked with this API in this
  38  * release of Solaris is almost guaranteed to break in the next release.
  39  *
  40  * In short, do not user this header file or the CTF routines for any purpose.
  41  */
  42
  43 #ifndef _CTF_API_H
  44 #define _CTF_API_H
  45
  46 #include <sys/types.h>
  47 #include <sys/param.h>
  48 #include <sys/elf.h>
  49 #include <sys/ctf.h>
  50
  51 #ifdef  __cplusplus
  52 extern "C" {
  53 #endif
  54
  55 /*
  56  * Clients can open one or more CTF containers and obtain a pointer to an
  57  * opaque ctf_file_t.  Types are identified by an opaque ctf_id_t token.
  58  * These opaque definitions allow libctf to evolve without breaking clients.
  59  */
  60 typedef struct ctf_file ctf_file_t;
  61 typedef long ctf_id_t;
  62
  63 #define ECTF_BASE       1000    /* base value for libctf errnos */
  64
  65 enum {
  66         ECTF_FMT = ECTF_BASE,   /* file is not in CTF or ELF format */
  67         ECTF_ELFVERS,           /* ELF version is more recent than libctf */
  68         ECTF_CTFVERS,           /* CTF version is more recent than libctf */
  69         ECTF_ENDIAN,            /* data is different endian-ness than lib */
  70         ECTF_SYMTAB,            /* symbol table uses invalid entry size */
  71         ECTF_SYMBAD,            /* symbol table data buffer invalid */
  72         ECTF_STRBAD,            /* string table data buffer invalid */
  73         ECTF_CORRUPT,           /* file data corruption detected */
  74         ECTF_NOCTFDATA,         /* ELF file does not contain CTF data */
  75         ECTF_NOCTFBUF,          /* buffer does not contain CTF data */
  76         ECTF_NOSYMTAB,          /* symbol table data is not available */
  77         ECTF_NOPARENT,          /* parent CTF container is not available */
  78         ECTF_DMODEL,            /* data model mismatch */
  79         ECTF_MMAP,              /* failed to mmap a data section */
  80         ECTF_ZMISSING,          /* decompression library not installed */
  81         ECTF_ZINIT,             /* failed to initialize decompression library */
  82         ECTF_ZALLOC,            /* failed to allocate decompression buffer */
  83         ECTF_DECOMPRESS,        /* failed to decompress CTF data */
  84         ECTF_STRTAB,            /* string table for this string is missing */
  85         ECTF_BADNAME,           /* string offset is corrupt w.r.t. strtab */
  86         ECTF_BADID,             /* invalid type ID number */
  87         ECTF_NOTSOU,            /* type is not a struct or union */
  88         ECTF_NOTENUM,           /* type is not an enum */
  89         ECTF_NOTSUE,            /* type is not a struct, union, or enum */
  90         ECTF_NOTINTFP,          /* type is not an integer or float */
  91         ECTF_NOTARRAY,          /* type is not an array */
  92         ECTF_NOTREF,            /* type does not reference another type */
  93         ECTF_NAMELEN,           /* buffer is too small to hold type name */
  94         ECTF_NOTYPE,            /* no type found corresponding to name */
  95         ECTF_SYNTAX,            /* syntax error in type name */
  96         ECTF_NOTFUNC,           /* symtab entry does not refer to a function */
  97         ECTF_NOFUNCDAT,         /* no func info available for function */
  98         ECTF_NOTDATA,           /* symtab entry does not refer to a data obj */
  99         ECTF_NOTYPEDAT,         /* no type info available for object */
 100         ECTF_NOLABEL,           /* no label found corresponding to name */
 101         ECTF_NOLABELDATA,       /* file does not contain any labels */
 102         ECTF_NOTSUP,            /* feature not supported */
 103         ECTF_NOENUMNAM,         /* enum element name not found */
 104         ECTF_NOMEMBNAM,         /* member name not found */
 105         ECTF_RDONLY,            /* CTF container is read-only */
 106         ECTF_DTFULL,            /* CTF type is full (no more members allowed) */
 107         ECTF_FULL,              /* CTF container is full */
 108         ECTF_DUPMEMBER,         /* duplicate member name definition */
 109         ECTF_CONFLICT,          /* conflicting type definition present */
 110         ECTF_REFERENCED,        /* type has outstanding references */
 111         ECTF_NOTDYN,            /* type is not a dynamic type */
 112         ECTF_ELF,               /* elf library failure */
 113         ECTF_MCHILD,            /* cannot merge child container */
 114         ECTF_LABELEXISTS,       /* label already exists */
 115         ECTF_LCONFLICT,         /* merged labels conflict */
 116         ECTF_ZLIB,              /* zlib library failure */
 117         ECTF_CONVBKERR,         /* CTF conversion backend error */
 118         ECTF_CONVNOCSRC,        /* No C source to convert from */
 119         ECTF_NOCONVBKEND        /* No applicable conversion backend */
 120 };
 121
 122 /*
 123  * If the debugger needs to provide the CTF library with a set of raw buffers
 124  * for use as the CTF data, symbol table, and string table, it can do so by
 125  * filling in ctf_sect_t structures and passing them to ctf_bufopen():
 126  */
 127 typedef struct ctf_sect {
 128         const char *cts_name;   /* section name (if any) */
 129         ulong_t cts_type;       /* section type (ELF SHT_... value) */
 130         ulong_t cts_flags;      /* section flags (ELF SHF_... value) */
 131         const void *cts_data;   /* pointer to section data */
 132         size_t cts_size;        /* size of data in bytes */
 133         size_t cts_entsize;     /* size of each section entry (symtab only) */
 134         off64_t cts_offset;     /* file offset of this section (if any) */
 135 } ctf_sect_t;
 136
 137 /*
 138  * Encoding information for integers, floating-point values, and certain other
 139  * intrinsics can be obtained by calling ctf_type_encoding(), below.  The flags
 140  * field will contain values appropriate for the type defined in <sys/ctf.h>.
 141  */
 142 typedef struct ctf_encoding {
 143         uint_t cte_format;      /* data format (CTF_INT_* or CTF_FP_* flags) */
 144         uint_t cte_offset;      /* offset of value in bits */
 145         uint_t cte_bits;        /* size of storage in bits */
 146 } ctf_encoding_t;
 147
 148 typedef struct ctf_membinfo {
 149         ctf_id_t ctm_type;      /* type of struct or union member */
 150         ulong_t ctm_offset;     /* offset of member in bits */
 151 } ctf_membinfo_t;
 152
 153 typedef struct ctf_arinfo {
 154         ctf_id_t ctr_contents;  /* type of array contents */
 155         ctf_id_t ctr_index;     /* type of array index */
 156         uint_t ctr_nelems;      /* number of elements */
 157 } ctf_arinfo_t;
 158
 159 typedef struct ctf_funcinfo {
 160         ctf_id_t ctc_return;    /* function return type */
 161         uint_t ctc_argc;        /* number of typed arguments to function */
 162         uint_t ctc_flags;       /* function attributes (see below) */
 163 } ctf_funcinfo_t;
 164
 165 typedef struct ctf_lblinfo {
 166         ctf_id_t ctb_typeidx;   /* last type associated with the label */
 167 } ctf_lblinfo_t;
 168
 169 #define CTF_FUNC_VARARG 0x1     /* function arguments end with varargs */
 170
 171 /*
 172  * Functions that return integer status or a ctf_id_t use the following value
 173  * to indicate failure.  ctf_errno() can be used to obtain an error code.
 174  */
 175 #define CTF_ERR (-1L)
 176
 177 /*
 178  * The CTF data model is inferred to be the caller's data model or the data
 179  * model of the given object, unless ctf_setmodel() is explicitly called.
 180  */
 181 #define CTF_MODEL_ILP32 1       /* object data model is ILP32 */
 182 #define CTF_MODEL_LP64  2       /* object data model is LP64 */
 183 #ifdef _LP64
 184 #define CTF_MODEL_NATIVE        CTF_MODEL_LP64
 185 #else
 186 #define CTF_MODEL_NATIVE        CTF_MODEL_ILP32
 187 #endif
 188
 189 /*
 190  * Dynamic CTF containers can be created using ctf_create().  The ctf_add_*
 191  * routines can be used to add new definitions to the dynamic container.
 192  * New types are labeled as root or non-root to determine whether they are
 193  * visible at the top-level program scope when subsequently doing a lookup.
 194  */
 195 #define CTF_ADD_NONROOT 0       /* type only visible in nested scope */
 196 #define CTF_ADD_ROOT    1       /* type visible at top-level scope */
 197
 198 /*
 199  * These typedefs are used to define the signature for callback functions
 200  * that can be used with the iteration and visit functions below:
 201  */
 202 typedef int ctf_visit_f(const char *, ctf_id_t, ulong_t, int, void *);
 203 typedef int ctf_member_f(const char *, ctf_id_t, ulong_t, void *);
 204 typedef int ctf_enum_f(const char *, int, void *);
 205 typedef int ctf_type_f(ctf_id_t, boolean_t, void *);
 206 typedef int ctf_label_f(const char *, const ctf_lblinfo_t *, void *);
 207 typedef int ctf_function_f(const char *, ulong_t, ctf_funcinfo_t *, void *);
 208 typedef int ctf_object_f(const char *, ctf_id_t, ulong_t, void *);
 209 typedef int ctf_string_f(const char *, void *);
 210
 211 extern ctf_file_t *ctf_bufopen(const ctf_sect_t *, const ctf_sect_t *,
 212     const ctf_sect_t *, int *);
 213 extern ctf_file_t *ctf_fdopen(int, int *);
 214 extern ctf_file_t *ctf_open(const char *, int *);
 215 extern ctf_file_t *ctf_create(int *);
 216 extern ctf_file_t *ctf_fdcreate(int, int *);
 217 extern ctf_file_t *ctf_dup(ctf_file_t *);
 218 extern void ctf_close(ctf_file_t *);
 219
 220 extern ctf_file_t *ctf_parent_file(ctf_file_t *);
 221 extern const char *ctf_parent_name(ctf_file_t *);
 222 extern const char *ctf_parent_label(ctf_file_t *);
 223
 224 extern int ctf_import(ctf_file_t *, ctf_file_t *);
 225 extern int ctf_setmodel(ctf_file_t *, int);
 226 extern int ctf_getmodel(ctf_file_t *);
 227
 228 extern void ctf_setspecific(ctf_file_t *, void *);
 229 extern void *ctf_getspecific(ctf_file_t *);
 230
 231 extern int ctf_errno(ctf_file_t *);
 232 extern uint_t ctf_flags(ctf_file_t *);
 233 extern const char *ctf_errmsg(int);
 234 extern int ctf_version(int);
 235
 236 extern int ctf_func_info(ctf_file_t *, ulong_t, ctf_funcinfo_t *);
 237 extern int ctf_func_info_by_id(ctf_file_t *, ctf_id_t, ctf_funcinfo_t *);
 238 extern int ctf_func_args(ctf_file_t *, ulong_t, uint_t, ctf_id_t *);
 239 extern int ctf_func_args_by_id(ctf_file_t *, ctf_id_t, uint_t, ctf_id_t *);
 240
 241 extern ctf_id_t ctf_lookup_by_name(ctf_file_t *, const char *);
 242 extern ctf_id_t ctf_lookup_by_symbol(ctf_file_t *, ulong_t);
 243
 244 extern char *ctf_symbol_name(ctf_file_t *, ulong_t, char *, size_t);
 245
 246 extern ctf_id_t ctf_type_resolve(ctf_file_t *, ctf_id_t);
 247 extern ssize_t ctf_type_lname(ctf_file_t *, ctf_id_t, char *, size_t);
 248 extern char *ctf_type_name(ctf_file_t *, ctf_id_t, char *, size_t);
 249 extern char *ctf_type_qname(ctf_file_t *, ctf_id_t, char *, size_t,
 250     const char *);
 251 extern ssize_t ctf_type_size(ctf_file_t *, ctf_id_t);
 252 extern ssize_t ctf_type_align(ctf_file_t *, ctf_id_t);
 253 extern int ctf_type_kind(ctf_file_t *, ctf_id_t);
 254 extern const char *ctf_kind_name(ctf_file_t *, int);
 255 extern ctf_id_t ctf_type_reference(ctf_file_t *, ctf_id_t);
 256 extern ctf_id_t ctf_type_pointer(ctf_file_t *, ctf_id_t);
 257 extern int ctf_type_encoding(ctf_file_t *, ctf_id_t, ctf_encoding_t *);
 258 extern int ctf_type_visit(ctf_file_t *, ctf_id_t, ctf_visit_f *, void *);
 259 extern int ctf_type_cmp(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
 260 extern int ctf_type_compat(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
 261
 262 extern int ctf_member_info(ctf_file_t *, ctf_id_t, const char *,
 263     ctf_membinfo_t *);
 264 extern int ctf_array_info(ctf_file_t *, ctf_id_t, ctf_arinfo_t *);
 265
 266 extern const char *ctf_enum_name(ctf_file_t *, ctf_id_t, int);
 267 extern int ctf_enum_value(ctf_file_t *, ctf_id_t, const char *, int *);
 268
 269 extern const char *ctf_label_topmost(ctf_file_t *);
 270 extern int ctf_label_info(ctf_file_t *, const char *, ctf_lblinfo_t *);
 271
 272 extern int ctf_member_iter(ctf_file_t *, ctf_id_t, ctf_member_f *, void *);
 273 extern int ctf_enum_iter(ctf_file_t *, ctf_id_t, ctf_enum_f *, void *);
 274 extern int ctf_type_iter(ctf_file_t *, boolean_t, ctf_type_f *, void *);
 275 extern int ctf_label_iter(ctf_file_t *, ctf_label_f *, void *);
 276 extern int ctf_function_iter(ctf_file_t *, ctf_function_f *, void *);
 277 extern int ctf_object_iter(ctf_file_t *, ctf_object_f *, void *);
 278 extern int ctf_string_iter(ctf_file_t *, ctf_string_f *, void *);
 279
 280 extern ctf_id_t ctf_add_array(ctf_file_t *, uint_t, const ctf_arinfo_t *);
 281 extern ctf_id_t ctf_add_const(ctf_file_t *, uint_t, const char *, ctf_id_t);
 282 extern ctf_id_t ctf_add_enum(ctf_file_t *, uint_t, const char *);
 283 extern ctf_id_t ctf_add_float(ctf_file_t *, uint_t,
 284     const char *, const ctf_encoding_t *);
 285 extern ctf_id_t ctf_add_forward(ctf_file_t *, uint_t, const char *, uint_t);
 286 extern ctf_id_t ctf_add_funcptr(ctf_file_t *, uint_t, const ctf_funcinfo_t *,
 287     const ctf_id_t *);
 288 extern ctf_id_t ctf_add_integer(ctf_file_t *, uint_t,
 289     const char *, const ctf_encoding_t *);
 290 extern ctf_id_t ctf_add_pointer(ctf_file_t *, uint_t, const char *, ctf_id_t);
 291 extern ctf_id_t ctf_add_type(ctf_file_t *, ctf_file_t *, ctf_id_t);
 292 extern ctf_id_t ctf_add_typedef(ctf_file_t *, uint_t, const char *, ctf_id_t);
 293 extern ctf_id_t ctf_add_restrict(ctf_file_t *, uint_t, const char *, ctf_id_t);
 294 extern ctf_id_t ctf_add_struct(ctf_file_t *, uint_t, const char *);
 295 extern ctf_id_t ctf_add_union(ctf_file_t *, uint_t, const char *);
 296 extern ctf_id_t ctf_add_volatile(ctf_file_t *, uint_t, const char *, ctf_id_t);
 297
 298 extern int ctf_add_enumerator(ctf_file_t *, ctf_id_t, const char *, int);
 299 extern int ctf_add_member(ctf_file_t *, ctf_id_t, const char *, ctf_id_t,
 300     ulong_t);
 301
 302
 303 extern int ctf_add_function(ctf_file_t *, ulong_t, const ctf_funcinfo_t *,
 304     const ctf_id_t *);
 305 extern int ctf_add_object(ctf_file_t *, ulong_t, ctf_id_t);
 306 extern int ctf_add_label(ctf_file_t *, const char *, ctf_id_t, uint_t);
 307
 308 extern int ctf_set_array(ctf_file_t *, ctf_id_t, const ctf_arinfo_t *);
 309 extern int ctf_set_root(ctf_file_t *, ctf_id_t, const boolean_t);
 310 extern int ctf_set_size(ctf_file_t *, ctf_id_t, const ulong_t);
 311
 312 extern int ctf_delete_type(ctf_file_t *, ctf_id_t);
 313
 314 extern int ctf_update(ctf_file_t *);
 315 extern int ctf_discard(ctf_file_t *);
 316 extern int ctf_write(ctf_file_t *, int);
 317 extern void ctf_dataptr(ctf_file_t *, const void **, size_t *);
 318
 319 #ifdef _KERNEL
 320
 321 struct module;
 322 extern ctf_file_t *ctf_modopen(struct module *, int *);
 323
 324 #endif
 325
 326 #ifdef  __cplusplus
 327 }
 328 #endif
 329
 330 #endif  /* _CTF_API_H */