sys/cddl/contrib/opensolaris/uts/common/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 /*
  28  * This header file defines the interfaces available from the CTF debugger
  29  * library, libctf, and an equivalent kernel module.  This API can be used by
  30  * a debugger to operate on data in the Compact ANSI-C Type Format (CTF).
  31  * This is NOT a public interface, although it may eventually become one in
  32  * the fullness of time after we gain more experience with the interfaces.
  33  *
  34  * In the meantime, be aware that any program linked with this API in this
  35  * release of Solaris is almost guaranteed to break in the next release.
  36  *
  37  * In short, do not user this header file or the CTF routines for any purpose.
  38  */
  39
  40 #ifndef _CTF_API_H
  41 #define _CTF_API_H
  42
  43 #pragma ident   "%Z%%M% %I%     %E% SMI"
  44
  45 #include <sys/types.h>
  46 #include <sys/param.h>
  47 #include <sys/elf.h>
  48 #include <sys/ctf.h>
  49
  50 #ifdef  __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /*
  55  * Clients can open one or more CTF containers and obtain a pointer to an
  56  * opaque ctf_file_t.  Types are identified by an opaque ctf_id_t token.
  57  * These opaque definitions allow libctf to evolve without breaking clients.
  58  */
  59 typedef struct ctf_file ctf_file_t;
  60 typedef long ctf_id_t;
  61
  62 /*
  63  * If the debugger needs to provide the CTF library with a set of raw buffers
  64  * for use as the CTF data, symbol table, and string table, it can do so by
  65  * filling in ctf_sect_t structures and passing them to ctf_bufopen():
  66  */
  67 typedef struct ctf_sect {
  68         const char *cts_name;   /* section name (if any) */
  69         ulong_t cts_type;       /* section type (ELF SHT_... value) */
  70         ulong_t cts_flags;      /* section flags (ELF SHF_... value) */
  71 #if defined(sun)
  72         const void *cts_data;   /* pointer to section data */
  73 #else
  74         void *cts_data;         /* pointer to section data */
  75 #endif
  76         size_t cts_size;        /* size of data in bytes */
  77         size_t cts_entsize;     /* size of each section entry (symtab only) */
  78         off64_t cts_offset;     /* file offset of this section (if any) */
  79 } ctf_sect_t;
  80
  81 /*
  82  * Encoding information for integers, floating-point values, and certain other
  83  * intrinsics can be obtained by calling ctf_type_encoding(), below.  The flags
  84  * field will contain values appropriate for the type defined in <sys/ctf.h>.
  85  */
  86 typedef struct ctf_encoding {
  87         uint_t cte_format;      /* data format (CTF_INT_* or CTF_FP_* flags) */
  88         uint_t cte_offset;      /* offset of value in bits */
  89         uint_t cte_bits;        /* size of storage in bits */
  90 } ctf_encoding_t;
  91
  92 typedef struct ctf_membinfo {
  93         ctf_id_t ctm_type;      /* type of struct or union member */
  94         ulong_t ctm_offset;     /* offset of member in bits */
  95 } ctf_membinfo_t;
  96
  97 typedef struct ctf_arinfo {
  98         ctf_id_t ctr_contents;  /* type of array contents */
  99         ctf_id_t ctr_index;     /* type of array index */
 100         uint_t ctr_nelems;      /* number of elements */
 101 } ctf_arinfo_t;
 102
 103 typedef struct ctf_funcinfo {
 104         ctf_id_t ctc_return;    /* function return type */
 105         uint_t ctc_argc;        /* number of typed arguments to function */
 106         uint_t ctc_flags;       /* function attributes (see below) */
 107 } ctf_funcinfo_t;
 108
 109 typedef struct ctf_lblinfo {
 110         ctf_id_t ctb_typeidx;   /* last type associated with the label */
 111 } ctf_lblinfo_t;
 112
 113 #define CTF_FUNC_VARARG 0x1     /* function arguments end with varargs */
 114
 115 /*
 116  * Functions that return integer status or a ctf_id_t use the following value
 117  * to indicate failure.  ctf_errno() can be used to obtain an error code.
 118  */
 119 #define CTF_ERR (-1L)
 120
 121 /*
 122  * The CTF data model is inferred to be the caller's data model or the data
 123  * model of the given object, unless ctf_setmodel() is explicitly called.
 124  */
 125 #define CTF_MODEL_ILP32 1       /* object data model is ILP32 */
 126 #define CTF_MODEL_LP64  2       /* object data model is LP64 */
 127 #ifdef _LP64
 128 #define CTF_MODEL_NATIVE        CTF_MODEL_LP64
 129 #else
 130 #define CTF_MODEL_NATIVE        CTF_MODEL_ILP32
 131 #endif
 132
 133 /*
 134  * Dynamic CTF containers can be created using ctf_create().  The ctf_add_*
 135  * routines can be used to add new definitions to the dynamic container.
 136  * New types are labeled as root or non-root to determine whether they are
 137  * visible at the top-level program scope when subsequently doing a lookup.
 138  */
 139 #define CTF_ADD_NONROOT 0       /* type only visible in nested scope */
 140 #define CTF_ADD_ROOT    1       /* type visible at top-level scope */
 141
 142 /*
 143  * These typedefs are used to define the signature for callback functions
 144  * that can be used with the iteration and visit functions below:
 145  */
 146 typedef int ctf_visit_f(const char *, ctf_id_t, ulong_t, int, void *);
 147 typedef int ctf_member_f(const char *, ctf_id_t, ulong_t, void *);
 148 typedef int ctf_enum_f(const char *, int, void *);
 149 typedef int ctf_type_f(ctf_id_t, void *);
 150 typedef int ctf_label_f(const char *, const ctf_lblinfo_t *, void *);
 151
 152 extern ctf_file_t *ctf_bufopen(const ctf_sect_t *, const ctf_sect_t *,
 153     const ctf_sect_t *, int *);
 154 extern ctf_file_t *ctf_fdopen(int, int *);
 155 extern ctf_file_t *ctf_open(const char *, int *);
 156 extern ctf_file_t *ctf_create(int *);
 157 extern void ctf_close(ctf_file_t *);
 158
 159 extern ctf_file_t *ctf_parent_file(ctf_file_t *);
 160 extern const char *ctf_parent_name(ctf_file_t *);
 161
 162 extern int ctf_import(ctf_file_t *, ctf_file_t *);
 163 extern int ctf_setmodel(ctf_file_t *, int);
 164 extern int ctf_getmodel(ctf_file_t *);
 165
 166 extern void ctf_setspecific(ctf_file_t *, void *);
 167 extern void *ctf_getspecific(ctf_file_t *);
 168
 169 extern int ctf_errno(ctf_file_t *);
 170 extern const char *ctf_errmsg(int);
 171 extern int ctf_version(int);
 172
 173 extern int ctf_func_info(ctf_file_t *, ulong_t, ctf_funcinfo_t *);
 174 extern int ctf_func_args(ctf_file_t *, ulong_t, uint_t, ctf_id_t *);
 175
 176 extern ctf_id_t ctf_lookup_by_name(ctf_file_t *, const char *);
 177 extern ctf_id_t ctf_lookup_by_symbol(ctf_file_t *, ulong_t);
 178
 179 extern ctf_id_t ctf_type_resolve(ctf_file_t *, ctf_id_t);
 180 extern ssize_t ctf_type_lname(ctf_file_t *, ctf_id_t, char *, size_t);
 181 extern char *ctf_type_name(ctf_file_t *, ctf_id_t, char *, size_t);
 182 extern ssize_t ctf_type_size(ctf_file_t *, ctf_id_t);
 183 extern ssize_t ctf_type_align(ctf_file_t *, ctf_id_t);
 184 extern int ctf_type_kind(ctf_file_t *, ctf_id_t);
 185 extern ctf_id_t ctf_type_reference(ctf_file_t *, ctf_id_t);
 186 extern ctf_id_t ctf_type_pointer(ctf_file_t *, ctf_id_t);
 187 extern int ctf_type_encoding(ctf_file_t *, ctf_id_t, ctf_encoding_t *);
 188 extern int ctf_type_visit(ctf_file_t *, ctf_id_t, ctf_visit_f *, void *);
 189 extern int ctf_type_cmp(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
 190 extern int ctf_type_compat(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
 191
 192 extern int ctf_member_info(ctf_file_t *, ctf_id_t, const char *,
 193     ctf_membinfo_t *);
 194 extern int ctf_array_info(ctf_file_t *, ctf_id_t, ctf_arinfo_t *);
 195
 196 extern const char *ctf_enum_name(ctf_file_t *, ctf_id_t, int);
 197 extern int ctf_enum_value(ctf_file_t *, ctf_id_t, const char *, int *);
 198
 199 extern const char *ctf_label_topmost(ctf_file_t *);
 200 extern int ctf_label_info(ctf_file_t *, const char *, ctf_lblinfo_t *);
 201
 202 extern int ctf_member_iter(ctf_file_t *, ctf_id_t, ctf_member_f *, void *);
 203 extern int ctf_enum_iter(ctf_file_t *, ctf_id_t, ctf_enum_f *, void *);
 204 extern int ctf_type_iter(ctf_file_t *, ctf_type_f *, void *);
 205 extern int ctf_label_iter(ctf_file_t *, ctf_label_f *, void *);
 206
 207 extern ctf_id_t ctf_add_array(ctf_file_t *, uint_t, const ctf_arinfo_t *);
 208 extern ctf_id_t ctf_add_const(ctf_file_t *, uint_t, ctf_id_t);
 209 extern ctf_id_t ctf_add_enum(ctf_file_t *, uint_t, const char *);
 210 extern ctf_id_t ctf_add_float(ctf_file_t *, uint_t,
 211     const char *, const ctf_encoding_t *);
 212 extern ctf_id_t ctf_add_forward(ctf_file_t *, uint_t, const char *, uint_t);
 213 extern ctf_id_t ctf_add_function(ctf_file_t *, uint_t,
 214     const ctf_funcinfo_t *, const ctf_id_t *);
 215 extern ctf_id_t ctf_add_integer(ctf_file_t *, uint_t,
 216     const char *, const ctf_encoding_t *);
 217 extern ctf_id_t ctf_add_pointer(ctf_file_t *, uint_t, ctf_id_t);
 218 extern ctf_id_t ctf_add_type(ctf_file_t *, ctf_file_t *, ctf_id_t);
 219 extern ctf_id_t ctf_add_typedef(ctf_file_t *, uint_t, const char *, ctf_id_t);
 220 extern ctf_id_t ctf_add_restrict(ctf_file_t *, uint_t, ctf_id_t);
 221 extern ctf_id_t ctf_add_struct(ctf_file_t *, uint_t, const char *);
 222 extern ctf_id_t ctf_add_union(ctf_file_t *, uint_t, const char *);
 223 extern ctf_id_t ctf_add_volatile(ctf_file_t *, uint_t, ctf_id_t);
 224
 225 extern int ctf_add_enumerator(ctf_file_t *, ctf_id_t, const char *, int);
 226 extern int ctf_add_member(ctf_file_t *, ctf_id_t, const char *, ctf_id_t);
 227
 228 extern int ctf_set_array(ctf_file_t *, ctf_id_t, const ctf_arinfo_t *);
 229
 230 extern int ctf_update(ctf_file_t *);
 231 extern int ctf_discard(ctf_file_t *);
 232 extern int ctf_write(ctf_file_t *, int);
 233
 234 #ifdef _KERNEL
 235
 236 struct module;
 237 extern ctf_file_t *ctf_modopen(struct module *, int *);
 238
 239 #endif
 240
 241 #ifdef  __cplusplus
 242 }
 243 #endif
 244
 245 #endif  /* _CTF_API_H */