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