xref: /titanic_41/usr/src/uts/common/sys/ctf_api.h (revision 6ab3986229f6d7d9a83c94e3a6e68fd05da5cff0)
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) 2013, Joyent, Inc.  All rights reserved.
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 /*
64  * If the debugger needs to provide the CTF library with a set of raw buffers
65  * for use as the CTF data, symbol table, and string table, it can do so by
66  * filling in ctf_sect_t structures and passing them to ctf_bufopen():
67  */
68 typedef struct ctf_sect {
69 	const char *cts_name;	/* section name (if any) */
70 	ulong_t cts_type;	/* section type (ELF SHT_... value) */
71 	ulong_t cts_flags;	/* section flags (ELF SHF_... value) */
72 	const void *cts_data;	/* pointer to section data */
73 	size_t cts_size;	/* size of data in bytes */
74 	size_t cts_entsize;	/* size of each section entry (symtab only) */
75 	off64_t cts_offset;	/* file offset of this section (if any) */
76 } ctf_sect_t;
77 
78 /*
79  * Encoding information for integers, floating-point values, and certain other
80  * intrinsics can be obtained by calling ctf_type_encoding(), below.  The flags
81  * field will contain values appropriate for the type defined in <sys/ctf.h>.
82  */
83 typedef struct ctf_encoding {
84 	uint_t cte_format;	/* data format (CTF_INT_* or CTF_FP_* flags) */
85 	uint_t cte_offset;	/* offset of value in bits */
86 	uint_t cte_bits;	/* size of storage in bits */
87 } ctf_encoding_t;
88 
89 typedef struct ctf_membinfo {
90 	ctf_id_t ctm_type;	/* type of struct or union member */
91 	ulong_t ctm_offset;	/* offset of member in bits */
92 } ctf_membinfo_t;
93 
94 typedef struct ctf_arinfo {
95 	ctf_id_t ctr_contents;	/* type of array contents */
96 	ctf_id_t ctr_index;	/* type of array index */
97 	uint_t ctr_nelems;	/* number of elements */
98 } ctf_arinfo_t;
99 
100 typedef struct ctf_funcinfo {
101 	ctf_id_t ctc_return;	/* function return type */
102 	uint_t ctc_argc;	/* number of typed arguments to function */
103 	uint_t ctc_flags;	/* function attributes (see below) */
104 } ctf_funcinfo_t;
105 
106 typedef struct ctf_lblinfo {
107 	ctf_id_t ctb_typeidx;	/* last type associated with the label */
108 } ctf_lblinfo_t;
109 
110 #define	CTF_FUNC_VARARG	0x1	/* function arguments end with varargs */
111 
112 /*
113  * Functions that return integer status or a ctf_id_t use the following value
114  * to indicate failure.  ctf_errno() can be used to obtain an error code.
115  */
116 #define	CTF_ERR	(-1L)
117 
118 /*
119  * The CTF data model is inferred to be the caller's data model or the data
120  * model of the given object, unless ctf_setmodel() is explicitly called.
121  */
122 #define	CTF_MODEL_ILP32	1	/* object data model is ILP32 */
123 #define	CTF_MODEL_LP64	2	/* object data model is LP64 */
124 #ifdef _LP64
125 #define	CTF_MODEL_NATIVE	CTF_MODEL_LP64
126 #else
127 #define	CTF_MODEL_NATIVE	CTF_MODEL_ILP32
128 #endif
129 
130 /*
131  * Dynamic CTF containers can be created using ctf_create().  The ctf_add_*
132  * routines can be used to add new definitions to the dynamic container.
133  * New types are labeled as root or non-root to determine whether they are
134  * visible at the top-level program scope when subsequently doing a lookup.
135  */
136 #define	CTF_ADD_NONROOT	0	/* type only visible in nested scope */
137 #define	CTF_ADD_ROOT	1	/* type visible at top-level scope */
138 
139 /*
140  * These typedefs are used to define the signature for callback functions
141  * that can be used with the iteration and visit functions below:
142  */
143 typedef int ctf_visit_f(const char *, ctf_id_t, ulong_t, int, void *);
144 typedef int ctf_member_f(const char *, ctf_id_t, ulong_t, void *);
145 typedef int ctf_enum_f(const char *, int, void *);
146 typedef int ctf_type_f(ctf_id_t, void *);
147 typedef int ctf_label_f(const char *, const ctf_lblinfo_t *, void *);
148 
149 extern ctf_file_t *ctf_bufopen(const ctf_sect_t *, const ctf_sect_t *,
150     const ctf_sect_t *, int *);
151 extern ctf_file_t *ctf_fdopen(int, int *);
152 extern ctf_file_t *ctf_open(const char *, int *);
153 extern ctf_file_t *ctf_create(int *);
154 extern ctf_file_t *ctf_dup(ctf_file_t *);
155 extern void ctf_close(ctf_file_t *);
156 
157 extern ctf_file_t *ctf_parent_file(ctf_file_t *);
158 extern const char *ctf_parent_name(ctf_file_t *);
159 
160 extern int ctf_import(ctf_file_t *, ctf_file_t *);
161 extern int ctf_setmodel(ctf_file_t *, int);
162 extern int ctf_getmodel(ctf_file_t *);
163 
164 extern void ctf_setspecific(ctf_file_t *, void *);
165 extern void *ctf_getspecific(ctf_file_t *);
166 
167 extern int ctf_errno(ctf_file_t *);
168 extern const char *ctf_errmsg(int);
169 extern int ctf_version(int);
170 
171 extern int ctf_func_info(ctf_file_t *, ulong_t, ctf_funcinfo_t *);
172 extern int ctf_func_args(ctf_file_t *, ulong_t, uint_t, ctf_id_t *);
173 
174 extern ctf_id_t ctf_lookup_by_name(ctf_file_t *, const char *);
175 extern ctf_id_t ctf_lookup_by_symbol(ctf_file_t *, ulong_t);
176 
177 extern ctf_id_t ctf_type_resolve(ctf_file_t *, ctf_id_t);
178 extern ssize_t ctf_type_lname(ctf_file_t *, ctf_id_t, char *, size_t);
179 extern char *ctf_type_name(ctf_file_t *, ctf_id_t, char *, size_t);
180 extern char *ctf_type_qname(ctf_file_t *, ctf_id_t, char *, size_t,
181     const char *);
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_delete_type(ctf_file_t *, ctf_id_t);
231 
232 extern int ctf_update(ctf_file_t *);
233 extern int ctf_discard(ctf_file_t *);
234 extern int ctf_write(ctf_file_t *, int);
235 
236 #ifdef _KERNEL
237 
238 struct module;
239 extern ctf_file_t *ctf_modopen(struct module *, int *);
240 
241 #endif
242 
243 #ifdef	__cplusplus
244 }
245 #endif
246 
247 #endif	/* _CTF_API_H */
248