Home | History | Annotate | Download | only in sys
      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 	const void *cts_data;	/* pointer to section data */
     72 	size_t cts_size;	/* size of data in bytes */
     73 	size_t cts_entsize;	/* size of each section entry (symtab only) */
     74 	off64_t cts_offset;	/* file offset of this section (if any) */
     75 } ctf_sect_t;
     76 
     77 /*
     78  * Encoding information for integers, floating-point values, and certain other
     79  * intrinsics can be obtained by calling ctf_type_encoding(), below.  The flags
     80  * field will contain values appropriate for the type defined in <sys/ctf.h>.
     81  */
     82 typedef struct ctf_encoding {
     83 	uint_t cte_format;	/* data format (CTF_INT_* or CTF_FP_* flags) */
     84 	uint_t cte_offset;	/* offset of value in bits */
     85 	uint_t cte_bits;	/* size of storage in bits */
     86 } ctf_encoding_t;
     87 
     88 typedef struct ctf_membinfo {
     89 	ctf_id_t ctm_type;	/* type of struct or union member */
     90 	ulong_t ctm_offset;	/* offset of member in bits */
     91 } ctf_membinfo_t;
     92 
     93 typedef struct ctf_arinfo {
     94 	ctf_id_t ctr_contents;	/* type of array contents */
     95 	ctf_id_t ctr_index;	/* type of array index */
     96 	uint_t ctr_nelems;	/* number of elements */
     97 } ctf_arinfo_t;
     98 
     99 typedef struct ctf_funcinfo {
    100 	ctf_id_t ctc_return;	/* function return type */
    101 	uint_t ctc_argc;	/* number of typed arguments to function */
    102 	uint_t ctc_flags;	/* function attributes (see below) */
    103 } ctf_funcinfo_t;
    104 
    105 typedef struct ctf_lblinfo {
    106 	ctf_id_t ctb_typeidx;	/* last type associated with the label */
    107 } ctf_lblinfo_t;
    108 
    109 #define	CTF_FUNC_VARARG	0x1	/* function arguments end with varargs */
    110 
    111 /*
    112  * Functions that return integer status or a ctf_id_t use the following value
    113  * to indicate failure.  ctf_errno() can be used to obtain an error code.
    114  */
    115 #define	CTF_ERR	(-1L)
    116 
    117 /*
    118  * The CTF data model is inferred to be the caller's data model or the data
    119  * model of the given object, unless ctf_setmodel() is explicitly called.
    120  */
    121 #define	CTF_MODEL_ILP32	1	/* object data model is ILP32 */
    122 #define	CTF_MODEL_LP64	2	/* object data model is LP64 */
    123 #ifdef _LP64
    124 #define	CTF_MODEL_NATIVE	CTF_MODEL_LP64
    125 #else
    126 #define	CTF_MODEL_NATIVE	CTF_MODEL_ILP32
    127 #endif
    128 
    129 /*
    130  * Dynamic CTF containers can be created using ctf_create().  The ctf_add_*
    131  * routines can be used to add new definitions to the dynamic container.
    132  * New types are labeled as root or non-root to determine whether they are
    133  * visible at the top-level program scope when subsequently doing a lookup.
    134  */
    135 #define	CTF_ADD_NONROOT	0	/* type only visible in nested scope */
    136 #define	CTF_ADD_ROOT	1	/* type visible at top-level scope */
    137 
    138 /*
    139  * These typedefs are used to define the signature for callback functions
    140  * that can be used with the iteration and visit functions below:
    141  */
    142 typedef int ctf_visit_f(const char *, ctf_id_t, ulong_t, int, void *);
    143 typedef int ctf_member_f(const char *, ctf_id_t, ulong_t, void *);
    144 typedef int ctf_enum_f(const char *, int, void *);
    145 typedef int ctf_type_f(ctf_id_t, void *);
    146 typedef int ctf_label_f(const char *, const ctf_lblinfo_t *, void *);
    147 
    148 extern ctf_file_t *ctf_bufopen(const ctf_sect_t *, const ctf_sect_t *,
    149     const ctf_sect_t *, int *);
    150 extern ctf_file_t *ctf_fdopen(int, int *);
    151 extern ctf_file_t *ctf_open(const char *, int *);
    152 extern ctf_file_t *ctf_create(int *);
    153 extern void ctf_close(ctf_file_t *);
    154 
    155 extern ctf_file_t *ctf_parent_file(ctf_file_t *);
    156 extern const char *ctf_parent_name(ctf_file_t *);
    157 
    158 extern int ctf_import(ctf_file_t *, ctf_file_t *);
    159 extern int ctf_setmodel(ctf_file_t *, int);
    160 extern int ctf_getmodel(ctf_file_t *);
    161 
    162 extern void ctf_setspecific(ctf_file_t *, void *);
    163 extern void *ctf_getspecific(ctf_file_t *);
    164 
    165 extern int ctf_errno(ctf_file_t *);
    166 extern const char *ctf_errmsg(int);
    167 extern int ctf_version(int);
    168 
    169 extern int ctf_func_info(ctf_file_t *, ulong_t, ctf_funcinfo_t *);
    170 extern int ctf_func_args(ctf_file_t *, ulong_t, uint_t, ctf_id_t *);
    171 
    172 extern ctf_id_t ctf_lookup_by_name(ctf_file_t *, const char *);
    173 extern ctf_id_t ctf_lookup_by_symbol(ctf_file_t *, ulong_t);
    174 
    175 extern ctf_id_t ctf_type_resolve(ctf_file_t *, ctf_id_t);
    176 extern ssize_t ctf_type_lname(ctf_file_t *, ctf_id_t, char *, size_t);
    177 extern char *ctf_type_name(ctf_file_t *, ctf_id_t, char *, size_t);
    178 extern ssize_t ctf_type_size(ctf_file_t *, ctf_id_t);
    179 extern ssize_t ctf_type_align(ctf_file_t *, ctf_id_t);
    180 extern int ctf_type_kind(ctf_file_t *, ctf_id_t);
    181 extern ctf_id_t ctf_type_reference(ctf_file_t *, ctf_id_t);
    182 extern ctf_id_t ctf_type_pointer(ctf_file_t *, ctf_id_t);
    183 extern int ctf_type_encoding(ctf_file_t *, ctf_id_t, ctf_encoding_t *);
    184 extern int ctf_type_visit(ctf_file_t *, ctf_id_t, ctf_visit_f *, void *);
    185 extern int ctf_type_cmp(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
    186 extern int ctf_type_compat(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
    187 
    188 extern int ctf_member_info(ctf_file_t *, ctf_id_t, const char *,
    189     ctf_membinfo_t *);
    190 extern int ctf_array_info(ctf_file_t *, ctf_id_t, ctf_arinfo_t *);
    191 
    192 extern const char *ctf_enum_name(ctf_file_t *, ctf_id_t, int);
    193 extern int ctf_enum_value(ctf_file_t *, ctf_id_t, const char *, int *);
    194 
    195 extern const char *ctf_label_topmost(ctf_file_t *);
    196 extern int ctf_label_info(ctf_file_t *, const char *, ctf_lblinfo_t *);
    197 
    198 extern int ctf_member_iter(ctf_file_t *, ctf_id_t, ctf_member_f *, void *);
    199 extern int ctf_enum_iter(ctf_file_t *, ctf_id_t, ctf_enum_f *, void *);
    200 extern int ctf_type_iter(ctf_file_t *, ctf_type_f *, void *);
    201 extern int ctf_label_iter(ctf_file_t *, ctf_label_f *, void *);
    202 
    203 extern ctf_id_t ctf_add_array(ctf_file_t *, uint_t, const ctf_arinfo_t *);
    204 extern ctf_id_t ctf_add_const(ctf_file_t *, uint_t, ctf_id_t);
    205 extern ctf_id_t ctf_add_enum(ctf_file_t *, uint_t, const char *);
    206 extern ctf_id_t ctf_add_float(ctf_file_t *, uint_t,
    207     const char *, const ctf_encoding_t *);
    208 extern ctf_id_t ctf_add_forward(ctf_file_t *, uint_t, const char *, uint_t);
    209 extern ctf_id_t ctf_add_function(ctf_file_t *, uint_t,
    210     const ctf_funcinfo_t *, const ctf_id_t *);
    211 extern ctf_id_t ctf_add_integer(ctf_file_t *, uint_t,
    212     const char *, const ctf_encoding_t *);
    213 extern ctf_id_t ctf_add_pointer(ctf_file_t *, uint_t, ctf_id_t);
    214 extern ctf_id_t ctf_add_type(ctf_file_t *, ctf_file_t *, ctf_id_t);
    215 extern ctf_id_t ctf_add_typedef(ctf_file_t *, uint_t, const char *, ctf_id_t);
    216 extern ctf_id_t ctf_add_restrict(ctf_file_t *, uint_t, ctf_id_t);
    217 extern ctf_id_t ctf_add_struct(ctf_file_t *, uint_t, const char *);
    218 extern ctf_id_t ctf_add_union(ctf_file_t *, uint_t, const char *);
    219 extern ctf_id_t ctf_add_volatile(ctf_file_t *, uint_t, ctf_id_t);
    220 
    221 extern int ctf_add_enumerator(ctf_file_t *, ctf_id_t, const char *, int);
    222 extern int ctf_add_member(ctf_file_t *, ctf_id_t, const char *, ctf_id_t);
    223 
    224 extern int ctf_set_array(ctf_file_t *, ctf_id_t, const ctf_arinfo_t *);
    225 
    226 extern int ctf_update(ctf_file_t *);
    227 extern int ctf_discard(ctf_file_t *);
    228 extern int ctf_write(ctf_file_t *, int);
    229 
    230 #ifdef _KERNEL
    231 
    232 struct module;
    233 extern ctf_file_t *ctf_modopen(struct module *, int *);
    234 
    235 #endif
    236 
    237 #ifdef	__cplusplus
    238 }
    239 #endif
    240 
    241 #endif	/* _CTF_API_H */
    242