xref: /illumos-gate/usr/src/lib/libctf/common/libctf.h (revision 88a08813800ed7ba7c927986421cee437f7f2233)
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 2001-2003 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  */
26 /*
27  * Copyright (c) 2019, Joyent, Inc.
28  * Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
29  */
30 
31 /*
32  * This header file defines the interfaces available from the CTF debugger
33  * library, libctf.  This library provides functions that a debugger can
34  * use to operate on data in the Compact ANSI-C Type Format (CTF).  This
35  * is NOT a public interface, although it may eventually become one in
36  * the fullness of time after we gain more experience with the interfaces.
37  *
38  * In the meantime, be aware that any program linked with libctf in this
39  * release of illumos is almost guaranteed to break in the next release.
40  *
41  * In short, do not use this header file or libctf for any purpose.
42  */
43 
44 #ifndef	_LIBCTF_H
45 #define	_LIBCTF_H
46 
47 #include <sys/ctf_api.h>
48 #include <libelf.h>
49 
50 #ifdef	__cplusplus
51 extern "C" {
52 #endif
53 
54 /*
55  * This flag can be used to enable debug messages.
56  */
57 extern int _libctf_debug;
58 
59 typedef enum ctf_diff_flag {
60 	CTF_DIFF_F_IGNORE_INTNAMES = 0x01
61 } ctf_diff_flag_t;
62 
63 typedef struct ctf_diff ctf_diff_t;
64 typedef void (*ctf_diff_type_f)(ctf_file_t *, ctf_id_t, boolean_t, ctf_file_t *,
65     ctf_id_t, void *);
66 typedef void (*ctf_diff_func_f)(ctf_file_t *, ulong_t, boolean_t, ctf_file_t *,
67     ulong_t, void *);
68 typedef void (*ctf_diff_obj_f)(ctf_file_t *, ulong_t, ctf_id_t, boolean_t,
69     ctf_file_t *, ulong_t, ctf_id_t, void *);
70 
71 extern int ctf_diff_init(ctf_file_t *, ctf_file_t *, ctf_diff_t **);
72 extern uint_t ctf_diff_getflags(ctf_diff_t *);
73 extern int ctf_diff_setflags(ctf_diff_t *, uint_t);
74 extern int ctf_diff_types(ctf_diff_t *, ctf_diff_type_f, void *);
75 extern int ctf_diff_functions(ctf_diff_t *, ctf_diff_func_f, void *);
76 extern int ctf_diff_objects(ctf_diff_t *, ctf_diff_obj_f, void *);
77 extern void ctf_diff_fini(ctf_diff_t *);
78 
79 #define	CTF_CONVERT_DEFAULT_BATCHSIZE	256
80 #define	CTF_CONVERT_DEFAULT_NTHREADS	4
81 
82 typedef enum ctf_convert_flag {
83 	/*
84 	 * Normally, we return a failure if we find a C-derived compilation
85 	 * unit that lacks DWARF or CTF (as required).  This flag over-rides
86 	 * this check.
87 	 */
88 	CTF_ALLOW_MISSING_DEBUG	 = 0x01,
89 	/*
90 	 * Normally, we return a failure if we can't fully convert a structure
91 	 * to CTF format, such as an enum with too many values. This flag
92 	 * allows us to continue and convert what we can.
93 	 */
94 	CTF_ALLOW_TRUNCATION = 0x02,
95 	/*
96 	 * Conversion is not usually attempted for objects that don't appear
97 	 * to be built from C sources. This flag overrides this and attempts
98 	 * conversion anyway.
99 	 */
100 	CTF_FORCE_CONVERSION = 0x04
101 } ctf_convert_flag_t;
102 
103 #define	CTF_CONVERT_ALL_FLAGS	(CTF_ALLOW_MISSING_DEBUG | \
104 				    CTF_ALLOW_TRUNCATION | \
105 				    CTF_FORCE_CONVERSION)
106 
107 /* opaque handle for ctfconvert functions */
108 struct ctf_convert_handle;
109 typedef struct ctf_convert_handle ctf_convert_t;
110 
111 extern ctf_convert_t *ctf_convert_init(int *);
112 extern void ctf_convert_fini(ctf_convert_t *);
113 
114 typedef void (*ctf_convert_warn_f)(void *, const char *, ...);
115 /* Any warning callback must be MT-Safe if multiple threads are used */
116 extern int ctf_convert_set_warncb(ctf_convert_t *, ctf_convert_warn_f, void *);
117 extern int ctf_convert_set_batchsize(ctf_convert_t *, uint_t);
118 extern int ctf_convert_set_flags(ctf_convert_t *, ctf_convert_flag_t);
119 extern int ctf_convert_set_label(ctf_convert_t *, const char *);
120 extern int ctf_convert_set_nthreads(ctf_convert_t *, uint_t);
121 extern int ctf_convert_add_ignore(ctf_convert_t *, const char *);
122 
123 extern ctf_file_t *ctf_fdconvert(ctf_convert_t *, int, int *, char *, size_t);
124 
125 
126 typedef enum ctf_hsc_ret {
127 	CHR_ERROR = -1,
128 	CHR_NO_C_SOURCE = 0,
129 	CHR_HAS_C_SOURCE = 1
130 } ctf_hsc_ret_t;
131 
132 extern ctf_hsc_ret_t ctf_has_c_source(Elf *, char *, size_t);
133 
134 typedef struct ctf_merge_handle ctf_merge_t;
135 extern ctf_merge_t *ctf_merge_init(int, int *);
136 extern int ctf_merge_add(ctf_merge_t *, ctf_file_t *);
137 extern int ctf_merge_set_nthreads(ctf_merge_t *, const uint_t);
138 extern int ctf_merge_label(ctf_merge_t *, const char *);
139 extern int ctf_merge_uniquify(ctf_merge_t *, ctf_file_t *, const char *);
140 extern int ctf_merge_merge(ctf_merge_t *, ctf_file_t **);
141 extern int ctf_merge_dedup(ctf_merge_t *, ctf_file_t **);
142 extern void ctf_merge_fini(ctf_merge_t *);
143 
144 #define	CTF_ELFWRITE_F_COMPRESS		0x1
145 extern int ctf_elffdwrite(ctf_file_t *, int, int, int);
146 extern int ctf_elfwrite(ctf_file_t *, const char *, const char *, int);
147 
148 #ifdef	__cplusplus
149 }
150 #endif
151 
152 #endif	/* _LIBCTF_H */
153