xref: /illumos-gate/usr/src/uts/common/sys/ctf_api.h (revision fe2dc8bddec347e173d402f53feeb492640a9f98)
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 2020 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_CONVNODEBUG	/* No debug info to convert into CTF */
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 ctf_id_t ctf_max_id(ctf_file_t *);
237 extern ulong_t ctf_nr_syms(ctf_file_t *);
238 
239 extern int ctf_func_info(ctf_file_t *, ulong_t, ctf_funcinfo_t *);
240 extern int ctf_func_info_by_id(ctf_file_t *, ctf_id_t, ctf_funcinfo_t *);
241 extern int ctf_func_args(ctf_file_t *, ulong_t, uint_t, ctf_id_t *);
242 extern int ctf_func_args_by_id(ctf_file_t *, ctf_id_t, uint_t, ctf_id_t *);
243 
244 extern ctf_id_t ctf_lookup_by_name(ctf_file_t *, const char *);
245 extern ctf_id_t ctf_lookup_by_symbol(ctf_file_t *, ulong_t);
246 
247 extern char *ctf_symbol_name(ctf_file_t *, ulong_t, char *, size_t);
248 
249 extern ctf_id_t ctf_type_resolve(ctf_file_t *, ctf_id_t);
250 extern ssize_t ctf_type_lname(ctf_file_t *, ctf_id_t, char *, size_t);
251 extern char *ctf_type_name(ctf_file_t *, ctf_id_t, char *, size_t);
252 extern char *ctf_type_qname(ctf_file_t *, ctf_id_t, char *, size_t,
253     const char *);
254 extern char *ctf_type_cname(ctf_file_t *, ctf_id_t, char *, size_t,
255     const char *);
256 extern ssize_t ctf_type_size(ctf_file_t *, ctf_id_t);
257 extern ssize_t ctf_type_align(ctf_file_t *, ctf_id_t);
258 extern int ctf_type_kind(ctf_file_t *, ctf_id_t);
259 extern const char *ctf_kind_name(ctf_file_t *, int);
260 extern ctf_id_t ctf_type_reference(ctf_file_t *, ctf_id_t);
261 extern ctf_id_t ctf_type_pointer(ctf_file_t *, ctf_id_t);
262 extern int ctf_type_encoding(ctf_file_t *, ctf_id_t, ctf_encoding_t *);
263 extern int ctf_type_visit(ctf_file_t *, ctf_id_t, ctf_visit_f *, void *);
264 extern int ctf_type_cmp(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
265 extern int ctf_type_compat(ctf_file_t *, ctf_id_t, ctf_file_t *, ctf_id_t);
266 
267 extern int ctf_member_info(ctf_file_t *, ctf_id_t, const char *,
268     ctf_membinfo_t *);
269 extern int ctf_array_info(ctf_file_t *, ctf_id_t, ctf_arinfo_t *);
270 
271 extern const char *ctf_enum_name(ctf_file_t *, ctf_id_t, int);
272 extern int ctf_enum_value(ctf_file_t *, ctf_id_t, const char *, int *);
273 
274 extern const char *ctf_label_topmost(ctf_file_t *);
275 extern int ctf_label_info(ctf_file_t *, const char *, ctf_lblinfo_t *);
276 
277 extern int ctf_member_iter(ctf_file_t *, ctf_id_t, ctf_member_f *, void *);
278 extern int ctf_enum_iter(ctf_file_t *, ctf_id_t, ctf_enum_f *, void *);
279 extern int ctf_type_iter(ctf_file_t *, boolean_t, ctf_type_f *, void *);
280 extern int ctf_label_iter(ctf_file_t *, ctf_label_f *, void *);
281 extern int ctf_function_iter(ctf_file_t *, ctf_function_f *, void *);
282 extern int ctf_object_iter(ctf_file_t *, ctf_object_f *, void *);
283 extern int ctf_string_iter(ctf_file_t *, ctf_string_f *, void *);
284 
285 extern ctf_id_t ctf_add_array(ctf_file_t *, uint_t, const ctf_arinfo_t *);
286 extern ctf_id_t ctf_add_const(ctf_file_t *, uint_t, const char *, ctf_id_t);
287 extern ctf_id_t ctf_add_enum(ctf_file_t *, uint_t, const char *, size_t);
288 extern ctf_id_t ctf_add_float(ctf_file_t *, uint_t,
289     const char *, const ctf_encoding_t *);
290 extern ctf_id_t ctf_add_forward(ctf_file_t *, uint_t, const char *, uint_t);
291 extern ctf_id_t ctf_add_funcptr(ctf_file_t *, uint_t, const ctf_funcinfo_t *,
292     const ctf_id_t *);
293 extern ctf_id_t ctf_add_integer(ctf_file_t *, uint_t,
294     const char *, const ctf_encoding_t *);
295 extern ctf_id_t ctf_add_pointer(ctf_file_t *, uint_t, const char *, ctf_id_t);
296 extern ctf_id_t ctf_add_type(ctf_file_t *, ctf_file_t *, ctf_id_t);
297 extern ctf_id_t ctf_add_typedef(ctf_file_t *, uint_t, const char *, ctf_id_t);
298 extern ctf_id_t ctf_add_restrict(ctf_file_t *, uint_t, const char *, ctf_id_t);
299 extern ctf_id_t ctf_add_struct(ctf_file_t *, uint_t, const char *);
300 extern ctf_id_t ctf_add_union(ctf_file_t *, uint_t, const char *);
301 extern ctf_id_t ctf_add_volatile(ctf_file_t *, uint_t, const char *, ctf_id_t);
302 
303 extern int ctf_add_enumerator(ctf_file_t *, ctf_id_t, const char *, int);
304 extern int ctf_add_member(ctf_file_t *, ctf_id_t, const char *, ctf_id_t,
305     ulong_t);
306 
307 
308 extern int ctf_add_function(ctf_file_t *, ulong_t, const ctf_funcinfo_t *,
309     const ctf_id_t *);
310 extern int ctf_add_object(ctf_file_t *, ulong_t, ctf_id_t);
311 extern int ctf_add_label(ctf_file_t *, const char *, ctf_id_t, uint_t);
312 
313 extern int ctf_set_array(ctf_file_t *, ctf_id_t, const ctf_arinfo_t *);
314 extern int ctf_set_root(ctf_file_t *, ctf_id_t, const boolean_t);
315 extern int ctf_set_size(ctf_file_t *, ctf_id_t, const ulong_t);
316 
317 extern int ctf_delete_type(ctf_file_t *, ctf_id_t);
318 
319 extern int ctf_update(ctf_file_t *);
320 extern int ctf_discard(ctf_file_t *);
321 extern int ctf_write(ctf_file_t *, int);
322 extern void ctf_dataptr(ctf_file_t *, const void **, size_t *);
323 
324 #ifdef _KERNEL
325 
326 struct module;
327 extern ctf_file_t *ctf_modopen(struct module *, int *);
328 
329 #endif
330 
331 #ifdef	__cplusplus
332 }
333 #endif
334 
335 #endif	/* _CTF_API_H */
336