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 27 #ifndef _CTF_H 28 #define _CTF_H 29 30 #ifdef illumos 31 #pragma ident "%Z%%M% %I% %E% SMI" 32 #endif 33 34 #include <sys/types.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /* 41 * CTF - Compact ANSI-C Type Format 42 * 43 * This file format can be used to compactly represent the information needed 44 * by a debugger to interpret the ANSI-C types used by a given program. 45 * Traditionally, this kind of information is generated by the compiler when 46 * invoked with the -g flag and is stored in "stabs" strings or in the more 47 * modern DWARF format. CTF provides a representation of only the information 48 * that is relevant to debugging a complex, optimized C program such as the 49 * operating system kernel in a form that is significantly more compact than 50 * the equivalent stabs or DWARF representation. The format is data-model 51 * independent, so consumers do not need different code depending on whether 52 * they are 32-bit or 64-bit programs. CTF assumes that a standard ELF symbol 53 * table is available for use in the debugger, and uses the structure and data 54 * of the symbol table to avoid storing redundant information. The CTF data 55 * may be compressed on disk or in memory, indicated by a bit in the header. 56 * CTF may be interpreted in a raw disk file, or it may be stored in an ELF 57 * section, typically named .SUNW_ctf. Data structures are aligned so that 58 * a raw CTF file or CTF ELF section may be manipulated using mmap(2). 59 * 60 * The CTF file or section itself has the following structure: 61 * 62 * +--------+--------+---------+----------+-------+--------+ 63 * | file | type | data | function | data | string | 64 * | header | labels | objects | info | types | table | 65 * +--------+--------+---------+----------+-------+--------+ 66 * 67 * The file header stores a magic number and version information, encoding 68 * flags, and the byte offset of each of the sections relative to the end of the 69 * header itself. If the CTF data has been uniquified against another set of 70 * CTF data, a reference to that data also appears in the the header. This 71 * reference is the name of the label corresponding to the types uniquified 72 * against. 73 * 74 * Following the header is a list of labels, used to group the types included in 75 * the data types section. Each label is accompanied by a type ID i. A given 76 * label refers to the group of types whose IDs are in the range [0, i]. 77 * 78 * Data object and function records are stored in the same order as they appear 79 * in the corresponding symbol table, except that symbols marked SHN_UNDEF are 80 * not stored and symbols that have no type data are padded out with zeroes. 81 * For each data object, the type ID (a small integer) is recorded. For each 82 * function, the type ID of the return type and argument types is recorded. 83 * 84 * The data types section is a list of variable size records that represent each 85 * type, in order by their ID. The types themselves form a directed graph, 86 * where each node may contain one or more outgoing edges to other type nodes, 87 * denoted by their ID. 88 * 89 * Strings are recorded as a string table ID (0 or 1) and a byte offset into the 90 * string table. String table 0 is the internal CTF string table. String table 91 * 1 is the external string table, which is the string table associated with the 92 * ELF symbol table for this object. CTF does not record any strings that are 93 * already in the symbol table, and the CTF string table does not contain any 94 * duplicated strings. 95 * 96 * If the CTF data has been merged with another parent CTF object, some outgoing 97 * edges may refer to type nodes that exist in another CTF object. The debugger 98 * and libctf library are responsible for connecting the appropriate objects 99 * together so that the full set of types can be explored and manipulated. 100 */ 101 102 #define CTF_MAX_TYPE 0xffff /* max type identifier value */ 103 #define CTF_MAX_NAME 0x7fffffff /* max offset into a string table */ 104 #define CTF_MAX_VLEN 0x3ff /* max struct, union, enum members or args */ 105 #define CTF_MAX_INTOFF 0xff /* max offset of intrinsic value in bits */ 106 #define CTF_MAX_INTBITS 0xffff /* max size of an intrinsic in bits */ 107 108 /* See ctf_type_t */ 109 #define CTF_MAX_SIZE 0xfffe /* max size of a type in bytes */ 110 #define CTF_LSIZE_SENT 0xffff /* sentinel for ctt_size */ 111 #define CTF_MAX_LSIZE UINT64_MAX 112 113 typedef struct ctf_preamble { 114 ushort_t ctp_magic; /* magic number (CTF_MAGIC) */ 115 uchar_t ctp_version; /* data format version number (CTF_VERSION) */ 116 uchar_t ctp_flags; /* flags (see below) */ 117 } ctf_preamble_t; 118 119 typedef struct ctf_header { 120 ctf_preamble_t cth_preamble; 121 uint_t cth_parlabel; /* ref to name of parent lbl uniq'd against */ 122 uint_t cth_parname; /* ref to basename of parent */ 123 uint_t cth_lbloff; /* offset of label section */ 124 uint_t cth_objtoff; /* offset of object section */ 125 uint_t cth_funcoff; /* offset of function section */ 126 uint_t cth_typeoff; /* offset of type section */ 127 uint_t cth_stroff; /* offset of string section */ 128 uint_t cth_strlen; /* length of string section in bytes */ 129 } ctf_header_t; 130 131 #define cth_magic cth_preamble.ctp_magic 132 #define cth_version cth_preamble.ctp_version 133 #define cth_flags cth_preamble.ctp_flags 134 135 #ifdef CTF_OLD_VERSIONS 136 137 typedef struct ctf_header_v1 { 138 ctf_preamble_t cth_preamble; 139 uint_t cth_objtoff; 140 uint_t cth_funcoff; 141 uint_t cth_typeoff; 142 uint_t cth_stroff; 143 uint_t cth_strlen; 144 } ctf_header_v1_t; 145 146 #endif /* CTF_OLD_VERSIONS */ 147 148 #define CTF_MAGIC 0xcff1 /* magic number identifying header */ 149 150 /* data format version number */ 151 #define CTF_VERSION_1 1 152 #define CTF_VERSION_2 2 153 #define CTF_VERSION CTF_VERSION_2 /* current version */ 154 155 #define CTF_F_COMPRESS 0x1 /* data buffer is compressed */ 156 157 typedef struct ctf_lblent { 158 uint_t ctl_label; /* ref to name of label */ 159 uint_t ctl_typeidx; /* last type associated with this label */ 160 } ctf_lblent_t; 161 162 typedef struct ctf_stype { 163 uint_t ctt_name; /* reference to name in string table */ 164 ushort_t ctt_info; /* encoded kind, variant length (see below) */ 165 union { 166 ushort_t _size; /* size of entire type in bytes */ 167 ushort_t _type; /* reference to another type */ 168 } _u; 169 } ctf_stype_t; 170 171 /* 172 * type sizes, measured in bytes, come in two flavors. 99% of them fit within 173 * (USHRT_MAX - 1), and thus can be stored in the ctt_size member of a 174 * ctf_stype_t. The maximum value for these sizes is CTF_MAX_SIZE. The sizes 175 * larger than CTF_MAX_SIZE must be stored in the ctt_lsize member of a 176 * ctf_type_t. Use of this member is indicated by the presence of 177 * CTF_LSIZE_SENT in ctt_size. 178 */ 179 typedef struct ctf_type { 180 uint_t ctt_name; /* reference to name in string table */ 181 ushort_t ctt_info; /* encoded kind, variant length (see below) */ 182 union { 183 ushort_t _size; /* always CTF_LSIZE_SENT */ 184 ushort_t _type; /* do not use */ 185 } _u; 186 uint_t ctt_lsizehi; /* high 32 bits of type size in bytes */ 187 uint_t ctt_lsizelo; /* low 32 bits of type size in bytes */ 188 } ctf_type_t; 189 190 #define ctt_size _u._size /* for fundamental types that have a size */ 191 #define ctt_type _u._type /* for types that reference another type */ 192 193 /* 194 * The following macros compose and decompose values for ctt_info and 195 * ctt_name, as well as other structures that contain name references. 196 * 197 * ------------------------ 198 * ctt_info: | kind | isroot | vlen | 199 * ------------------------ 200 * 15 11 10 9 0 201 * 202 * kind = CTF_INFO_KIND(c.ctt_info); <-- CTF_K_* value (see below) 203 * vlen = CTF_INFO_VLEN(c.ctt_info); <-- length of variable data list 204 * 205 * stid = CTF_NAME_STID(c.ctt_name); <-- string table id number (0 or 1) 206 * offset = CTF_NAME_OFFSET(c.ctt_name); <-- string table byte offset 207 * 208 * c.ctt_info = CTF_TYPE_INFO(kind, vlen); 209 * c.ctt_name = CTF_TYPE_NAME(stid, offset); 210 */ 211 212 #define CTF_INFO_KIND(info) (((info) & 0xf800) >> 11) 213 #define CTF_INFO_ISROOT(info) (((info) & 0x0400) >> 10) 214 #define CTF_INFO_VLEN(info) (((info) & CTF_MAX_VLEN)) 215 216 #define CTF_NAME_STID(name) ((name) >> 31) 217 #define CTF_NAME_OFFSET(name) ((name) & 0x7fffffff) 218 219 #define CTF_TYPE_INFO(kind, isroot, vlen) \ 220 (((kind) << 11) | (((isroot) ? 1 : 0) << 10) | ((vlen) & CTF_MAX_VLEN)) 221 222 #define CTF_TYPE_NAME(stid, offset) \ 223 (((stid) << 31) | ((offset) & 0x7fffffff)) 224 225 #define CTF_TYPE_ISPARENT(id) ((id) < 0x8000) 226 #define CTF_TYPE_ISCHILD(id) ((id) > 0x7fff) 227 228 #define CTF_TYPE_TO_INDEX(id) ((id) & 0x7fff) 229 #define CTF_INDEX_TO_TYPE(id, child) ((child) ? ((id) | 0x8000) : (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