xref: /illumos-gate/usr/src/uts/common/sys/ctf.h (revision bc1f688b4872ace323eaddbb1a6365d054e7bf56)
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 2004 Sun Microsystems, Inc.  All rights reserved.
24  * Use is subject to license terms.
25  *
26  * Copyright 2018 Joyent, Inc.
27  */
28 
29 #ifndef	_CTF_H
30 #define	_CTF_H
31 
32 #include <sys/types.h>
33 
34 #ifdef	__cplusplus
35 extern "C" {
36 #endif
37 
38 /*
39  * CTF - Compact ANSI-C Type Format
40  *
41  * This file format can be used to compactly represent the information needed
42  * by a debugger to interpret the ANSI-C types used by a given program.
43  * Traditionally, this kind of information is generated by the compiler when
44  * invoked with the -g flag and is stored in "stabs" strings or in the more
45  * modern DWARF format.  CTF provides a representation of only the information
46  * that is relevant to debugging a complex, optimized C program such as the
47  * operating system kernel in a form that is significantly more compact than
48  * the equivalent stabs or DWARF representation.  The format is data-model
49  * independent, so consumers do not need different code depending on whether
50  * they are 32-bit or 64-bit programs.  CTF assumes that a standard ELF symbol
51  * table is available for use in the debugger, and uses the structure and data
52  * of the symbol table to avoid storing redundant information.  The CTF data
53  * may be compressed on disk or in memory, indicated by a bit in the header.
54  * CTF may be interpreted in a raw disk file, or it may be stored in an ELF
55  * section, typically named .SUNW_ctf.  Data structures are aligned so that
56  * a raw CTF file or CTF ELF section may be manipulated using mmap(2).
57  *
58  * The CTF file or section itself has the following structure:
59  *
60  * +--------+--------+---------+----------+-------+--------+
61  * |  file  |  type  |  data   | function | data  | string |
62  * | header | labels | objects |   info   | types | table  |
63  * +--------+--------+---------+----------+-------+--------+
64  *
65  * The file header stores a magic number and version information, encoding
66  * flags, and the byte offset of each of the sections relative to the end of the
67  * header itself.  If the CTF data has been uniquified against another set of
68  * CTF data, a reference to that data also appears in the the header.  This
69  * reference is the name of the label corresponding to the types uniquified
70  * against.
71  *
72  * Following the header is a list of labels, used to group the types included in
73  * the data types section.  Each label is accompanied by a type ID i.  A given
74  * label refers to the group of types whose IDs are in the range [0, i].
75  *
76  * Data object and function records are stored in the same order as they appear
77  * in the corresponding symbol table, except that symbols marked SHN_UNDEF are
78  * not stored and symbols that have no type data are padded out with zeroes.
79  * For each data object, the type ID (a small integer) is recorded.  For each
80  * function, the type ID of the return type and argument types is recorded.
81  *
82  * The data types section is a list of variable size records that represent each
83  * type, in order by their ID.  The types themselves form a directed graph,
84  * where each node may contain one or more outgoing edges to other type nodes,
85  * denoted by their ID.
86  *
87  * Strings are recorded as a string table ID (0 or 1) and a byte offset into the
88  * string table.  String table 0 is the internal CTF string table.  String table
89  * 1 is the external string table, which is the string table associated with the
90  * ELF symbol table for this object.  CTF does not record any strings that are
91  * already in the symbol table, and the CTF string table does not contain any
92  * duplicated strings.
93  *
94  * If the CTF data has been merged with another parent CTF object, some outgoing
95  * edges may refer to type nodes that exist in another CTF object.  The debugger
96  * and libctf library are responsible for connecting the appropriate objects
97  * together so that the full set of types can be explored and manipulated.
98  */
99 
100 #define	CTF_MAX_TYPE	0xffff	/* max type identifier value */
101 #define	CTF_MAX_NAME 0x7fffffff	/* max offset into a string table */
102 #define	CTF_MAX_VLEN	0x3ff	/* max struct, union, enum members or args */
103 #define	CTF_MAX_INTOFF	0xff	/* max offset of intrinsic value in bits */
104 #define	CTF_MAX_INTBITS	0xffff	/* max size of an intrinsic in bits */
105 
106 /* See ctf_type_t */
107 #define	CTF_MAX_SIZE	0xfffe	/* max size of a type in bytes */
108 #define	CTF_LSIZE_SENT	0xffff	/* sentinel for ctt_size */
109 #define	CTF_MAX_LSIZE	UINT64_MAX
110 
111 typedef struct ctf_preamble {
112 	ushort_t ctp_magic;	/* magic number (CTF_MAGIC) */
113 	uchar_t ctp_version;	/* data format version number (CTF_VERSION) */
114 	uchar_t ctp_flags;	/* flags (see below) */
115 } ctf_preamble_t;
116 
117 typedef struct ctf_header {
118 	ctf_preamble_t cth_preamble;
119 	uint_t cth_parlabel;	/* ref to name of parent lbl uniq'd against */
120 	uint_t cth_parname;	/* ref to basename of parent */
121 	uint_t cth_lbloff;	/* offset of label section */
122 	uint_t cth_objtoff;	/* offset of object section */
123 	uint_t cth_funcoff;	/* offset of function section */
124 	uint_t cth_typeoff;	/* offset of type section */
125 	uint_t cth_stroff;	/* offset of string section */
126 	uint_t cth_strlen;	/* length of string section in bytes */
127 } ctf_header_t;
128 
129 #define	cth_magic   cth_preamble.ctp_magic
130 #define	cth_version cth_preamble.ctp_version
131 #define	cth_flags   cth_preamble.ctp_flags
132 
133 #ifdef CTF_OLD_VERSIONS
134 
135 typedef struct ctf_header_v1 {
136 	ctf_preamble_t cth_preamble;
137 	uint_t cth_objtoff;
138 	uint_t cth_funcoff;
139 	uint_t cth_typeoff;
140 	uint_t cth_stroff;
141 	uint_t cth_strlen;
142 } ctf_header_v1_t;
143 
144 #endif /* CTF_OLD_VERSIONS */
145 
146 #define	CTF_MAGIC	0xcff1	/* magic number identifying header */
147 
148 /* data format version number */
149 #define	CTF_VERSION_1	1
150 #define	CTF_VERSION_2	2
151 #define	CTF_VERSION	CTF_VERSION_2	/* current version */
152 
153 #define	CTF_F_COMPRESS	0x1	/* data buffer is compressed */
154 
155 typedef struct ctf_lblent {
156 	uint_t ctl_label;	/* ref to name of label */
157 	uint_t ctl_typeidx;	/* last type associated with this label */
158 } ctf_lblent_t;
159 
160 typedef struct ctf_stype {
161 	uint_t ctt_name;	/* reference to name in string table */
162 	ushort_t ctt_info;	/* encoded kind, variant length (see below) */
163 	union {
164 		ushort_t _size;	/* size of entire type in bytes */
165 		ushort_t _type;	/* reference to another type */
166 	} _u;
167 } ctf_stype_t;
168 
169 /*
170  * type sizes, measured in bytes, come in two flavors.  99% of them fit within
171  * (USHRT_MAX - 1), and thus can be stored in the ctt_size member of a
172  * ctf_stype_t.  The maximum value for these sizes is CTF_MAX_SIZE.  The sizes
173  * larger than CTF_MAX_SIZE must be stored in the ctt_lsize member of a
174  * ctf_type_t.  Use of this member is indicated by the presence of
175  * CTF_LSIZE_SENT in ctt_size.
176  */
177 typedef struct ctf_type {
178 	uint_t ctt_name;	/* reference to name in string table */
179 	ushort_t ctt_info;	/* encoded kind, variant length (see below) */
180 	union {
181 		ushort_t _size;	/* always CTF_LSIZE_SENT */
182 		ushort_t _type; /* do not use */
183 	} _u;
184 	uint_t ctt_lsizehi;	/* high 32 bits of type size in bytes */
185 	uint_t ctt_lsizelo;	/* low 32 bits of type size in bytes */
186 } ctf_type_t;
187 
188 #define	ctt_size _u._size	/* for fundamental types that have a size */
189 #define	ctt_type _u._type	/* for types that reference another type */
190 
191 /*
192  * The following macros compose and decompose values for ctt_info and
193  * ctt_name, as well as other structures that contain name references.
194  *
195  *             ------------------------
196  * ctt_info:   | kind | isroot | vlen |
197  *             ------------------------
198  *             15   11    10    9     0
199  *
200  * kind = CTF_INFO_KIND(c.ctt_info);     <-- CTF_K_* value (see below)
201  * vlen = CTF_INFO_VLEN(c.ctt_info);     <-- length of variable data list
202  *
203  * stid = CTF_NAME_STID(c.ctt_name);     <-- string table id number (0 or 1)
204  * offset = CTF_NAME_OFFSET(c.ctt_name); <-- string table byte offset
205  *
206  * c.ctt_info = CTF_TYPE_INFO(kind, vlen);
207  * c.ctt_name = CTF_TYPE_NAME(stid, offset);
208  */
209 
210 #define	CTF_INFO_KIND(info)	(((info) & 0xf800) >> 11)
211 #define	CTF_INFO_ISROOT(info)	(((info) & 0x0400) >> 10)
212 #define	CTF_INFO_VLEN(info)	(((info) & CTF_MAX_VLEN))
213 
214 #define	CTF_NAME_STID(name)	((name) >> 31)
215 #define	CTF_NAME_OFFSET(name)	((name) & 0x7fffffff)
216 
217 #define	CTF_TYPE_INFO(kind, isroot, vlen) \
218 	(((kind) << 11) | (((isroot) ? 1 : 0) << 10) | ((vlen) & CTF_MAX_VLEN))
219 
220 #define	CTF_TYPE_NAME(stid, offset) \
221 	(((stid) << 31) | ((offset) & 0x7fffffff))
222 
223 #define	CTF_CHILD_START		(0x8000)
224 #define	CTF_TYPE_ISPARENT(id)	((id) < CTF_CHILD_START)
225 #define	CTF_TYPE_ISCHILD(id)	((id) >= CTF_CHILD_START)
226 
227 #define	CTF_TYPE_TO_INDEX(id)		((id) & (CTF_CHILD_START - 1))
228 #define	CTF_INDEX_TO_TYPE(id, child) \
229 	((child) ? ((id) | CTF_CHILD_START) : (id))
230 #define	CTF_PARENT_SHIFT	15
231 
232 #define	CTF_STRTAB_0	0	/* symbolic define for string table id 0 */
233 #define	CTF_STRTAB_1	1	/* symbolic define for string table id 1 */
234 
235 #define	CTF_TYPE_LSIZE(cttp) \
236 	(((uint64_t)(cttp)->ctt_lsizehi) << 32 | (cttp)->ctt_lsizelo)
237 #define	CTF_SIZE_TO_LSIZE_HI(size)	((uint32_t)((uint64_t)(size) >> 32))
238 #define	CTF_SIZE_TO_LSIZE_LO(size)	((uint32_t)(size))
239 
240 #ifdef CTF_OLD_VERSIONS
241 
242 #define	CTF_INFO_KIND_V1(info)		(((info) & 0xf000) >> 12)
243 #define	CTF_INFO_ISROOT_V1(info)	(((info) & 0x0800) >> 11)
244 #define	CTF_INFO_VLEN_V1(info)		(((info) & 0x07ff))
245 
246 #define	CTF_TYPE_INFO_V1(kind, isroot, vlen) \
247 	(((kind) << 12) | (((isroot) ? 1 : 0) << 11) | ((vlen) & 0x07ff))
248 
249 #endif /* CTF_OLD_VERSIONS */
250 
251 /*
252  * Values for CTF_TYPE_KIND().  If the kind has an associated data list,
253  * CTF_INFO_VLEN() will extract the number of elements in the list, and
254  * the type of each element is shown in the comments below.
255  */
256 #define	CTF_K_UNKNOWN	0	/* unknown type (used for padding) */
257 #define	CTF_K_INTEGER	1	/* variant data is CTF_INT_DATA() (see below) */
258 #define	CTF_K_FLOAT	2	/* variant data is CTF_FP_DATA() (see below) */
259 #define	CTF_K_POINTER	3	/* ctt_type is referenced type */
260 #define	CTF_K_ARRAY	4	/* variant data is single ctf_array_t */
261 #define	CTF_K_FUNCTION	5	/* ctt_type is return type, variant data is */
262 				/* list of argument types (ushort_t's) */
263 #define	CTF_K_STRUCT	6	/* variant data is list of ctf_member_t's */
264 #define	CTF_K_UNION	7	/* variant data is list of ctf_member_t's */
265 #define	CTF_K_ENUM	8	/* variant data is list of ctf_enum_t's */
266 #define	CTF_K_FORWARD	9	/* no additional data; ctt_name is tag */
267 #define	CTF_K_TYPEDEF	10	/* ctt_type is referenced type */
268 #define	CTF_K_VOLATILE	11	/* ctt_type is base type */
269 #define	CTF_K_CONST	12	/* ctt_type is base type */
270 #define	CTF_K_RESTRICT	13	/* ctt_type is base type */
271 
272 #define	CTF_K_MAX	31	/* Maximum possible CTF_K_* value */
273 
274 /*
275  * Values for ctt_type when kind is CTF_K_INTEGER.  The flags, offset in bits,
276  * and size in bits are encoded as a single word using the following macros.
277  */
278 #define	CTF_INT_ENCODING(data)	(((data) & 0xff000000) >> 24)
279 #define	CTF_INT_OFFSET(data)	(((data) & 0x00ff0000) >> 16)
280 #define	CTF_INT_BITS(data)	(((data) & 0x0000ffff))
281 
282 #define	CTF_INT_DATA(encoding, offset, bits) \
283 	(((encoding) << 24) | ((offset) << 16) | (bits))
284 
285 #define	CTF_INT_SIGNED	0x01	/* integer is signed (otherwise unsigned) */
286 #define	CTF_INT_CHAR	0x02	/* character display format */
287 #define	CTF_INT_BOOL	0x04	/* boolean display format */
288 #define	CTF_INT_VARARGS	0x08	/* varargs display format */
289 
290 /*
291  * Values for ctt_type when kind is CTF_K_FLOAT.  The encoding, offset in bits,
292  * and size in bits are encoded as a single word using the following macros.
293  */
294 #define	CTF_FP_ENCODING(data)	(((data) & 0xff000000) >> 24)
295 #define	CTF_FP_OFFSET(data)	(((data) & 0x00ff0000) >> 16)
296 #define	CTF_FP_BITS(data)	(((data) & 0x0000ffff))
297 
298 #define	CTF_FP_DATA(encoding, offset, bits) \
299 	(((encoding) << 24) | ((offset) << 16) | (bits))
300 
301 #define	CTF_FP_SINGLE	1	/* IEEE 32-bit float encoding */
302 #define	CTF_FP_DOUBLE	2	/* IEEE 64-bit float encoding */
303 #define	CTF_FP_CPLX	3	/* Complex encoding */
304 #define	CTF_FP_DCPLX	4	/* Double complex encoding */
305 #define	CTF_FP_LDCPLX	5	/* Long double complex encoding */
306 #define	CTF_FP_LDOUBLE	6	/* Long double encoding */
307 #define	CTF_FP_INTRVL	7	/* Interval (2x32-bit) encoding */
308 #define	CTF_FP_DINTRVL	8	/* Double interval (2x64-bit) encoding */
309 #define	CTF_FP_LDINTRVL	9	/* Long double interval (2x128-bit) encoding */
310 #define	CTF_FP_IMAGRY	10	/* Imaginary (32-bit) encoding */
311 #define	CTF_FP_DIMAGRY	11	/* Long imaginary (64-bit) encoding */
312 #define	CTF_FP_LDIMAGRY	12	/* Long double imaginary (128-bit) encoding */
313 
314 #define	CTF_FP_MAX	12	/* Maximum possible CTF_FP_* value */
315 
316 typedef struct ctf_array {
317 	ushort_t cta_contents;	/* reference to type of array contents */
318 	ushort_t cta_index;	/* reference to type of array index */
319 	uint_t cta_nelems;	/* number of elements */
320 } ctf_array_t;
321 
322 /*
323  * Most structure members have bit offsets that can be expressed using a
324  * short.  Some don't.  ctf_member_t is used for structs which cannot
325  * contain any of these large offsets, whereas ctf_lmember_t is used in the
326  * latter case.  If ctt_size for a given struct is >= 8192 bytes, all members
327  * will be stored as type ctf_lmember_t.
328  */
329 
330 #define	CTF_LSTRUCT_THRESH	8192
331 
332 typedef struct ctf_member {
333 	uint_t ctm_name;	/* reference to name in string table */
334 	ushort_t ctm_type;	/* reference to type of member */
335 	ushort_t ctm_offset;	/* offset of this member in bits */
336 } ctf_member_t;
337 
338 typedef struct ctf_lmember {
339 	uint_t ctlm_name;	/* reference to name in string table */
340 	ushort_t ctlm_type;	/* reference to type of member */
341 	ushort_t ctlm_pad;	/* padding */
342 	uint_t ctlm_offsethi;	/* high 32 bits of member offset in bits */
343 	uint_t ctlm_offsetlo;	/* low 32 bits of member offset in bits */
344 } ctf_lmember_t;
345 
346 #define	CTF_LMEM_OFFSET(ctlmp) \
347 	(((uint64_t)(ctlmp)->ctlm_offsethi) << 32 | (ctlmp)->ctlm_offsetlo)
348 #define	CTF_OFFSET_TO_LMEMHI(offset)	((uint32_t)((uint64_t)(offset) >> 32))
349 #define	CTF_OFFSET_TO_LMEMLO(offset)	((uint32_t)(offset))
350 
351 typedef struct ctf_enum {
352 	uint_t cte_name;	/* reference to name in string table */
353 	int cte_value;		/* value associated with this name */
354 } ctf_enum_t;
355 
356 #ifdef	__cplusplus
357 }
358 #endif
359 
360 #endif	/* _CTF_H */
361