Type Identifiers

The type identifier zero is a sentinel value used to indicate that there is no type information available or it is an unknown type.

Throughout the file format, the identifier is stored in different sized values; however, the minimum size to represent a given identifier is a uint16_t. Other consumers of ctf information may use larger or opaque identifiers.

String Identifiers

Table identifier zero, always refers to the string section in the CTF file itself. String table identifier one refers to an external string table which is the ELF string table for the ELF symbol table associated with the ctf container.

Type Encoding

• The kind of the type
• Whether this type is a root type or not
• The length of the variable data

The 32 bits that make up the encoding are broken down into six bits for the kind (bits 26 to 31), one bit for the root type flag (bit 25), and 25 bits for the length of the variable data.

The current version of the file format defines 14 different kinds. The interpretation of these different kinds will be discussed in the section The Type Section. If a kind is encountered that is not listed below, then it is not a valid ctf file. The kinds are defined as follows:

#define	CTF_K_UNKNOWN	0
#define	CTF_K_INTEGER	1
#define	CTF_K_FLOAT	2
#define	CTF_K_POINTER	3
#define	CTF_K_ARRAY	4
#define	CTF_K_FUNCTION	5
#define	CTF_K_STRUCT	6
#define	CTF_K_UNION	7
#define	CTF_K_ENUM	8
#define	CTF_K_FORWARD	9
#define	CTF_K_TYPEDEF	10
#define	CTF_K_VOLATILE	11
#define	CTF_K_CONST	12
#define	CTF_K_RESTRICT	13

Programs directly reference many types; however, other types are referenced indirectly because they are part of some other structure. These types that are referenced directly and used are called root types. Other types may be used indirectly, for example, a program may reference a structure directly, but not one of its members which has a type. That type is not considered a root type. If a type is a root type, then it will have bit 25 set.

The variable length section is specific to each kind and is discussed in the section The Type Section.

The following macros are useful for constructing and deconstructing the encoded type information:

#define	CTF_V3_MAX_VLEN			0x00ffffff
#define	CTF_V3_INFO_KIND(info)		(((info) & 0xfc000000) >> 26)
#define	CTF_V3_INFO_ISROOT(info)	(((info) & 0x02000000) >> 25)
#define	CTF_V3_INFO_VLEN(info)		(((info) & CTF_V3_MAX_VLEN))

#define	CTF_V3_TYPE_INFO(kind, isroot, vlen) \
	(((kind) << 26) | (((isroot) ? 1 : 0) << 25) | ((vlen) & CTF_V3_MAX_VLEN))

The Label Section

Each label is encoded in the file format using the following eight byte structure:

typedef struct ctf_lblent {
	uint32_t ctl_label;	/* ref to name of label */
	uint32_t ctl_typeidx;	/* last type associated with this label */
} ctf_lblent_t;

Each label has two different components, a name and a type identifier. The name is encoded in the ctl_label member which is in the format defined in the section String Identifiers. Generally, the names of all labels are found in the internal string section.

The type identifier encoded in the member ctl_typeidx refers to the last type identifier that a label refers to in the current file. Labels only refer to types in the current file, if the ctf file is a child, then it will have the same label as its parent; however, its label will only refer to its types, not its parent's.

It is also possible, though rather uncommon, for a ctf file to have multiple labels. Labels are placed one after another, every eight bytes. When multiple labels are present, types may only belong to a single label.

The Object Section

To walk the object section, you need to have a corresponding symbol table in the ELF object that contains the ctf data. Not every object is included in this section. Specifically, when walking the symbol table, an entry is skipped if it matches any of the following conditions:

• The symbol type is not STT_OBJECT
• The symbol's section index is SHN_UNDEF
• The symbol's name offset is zero
• The symbol's section index is SHN_ABS and the value of the symbol is zero.
• The symbol's name is _START_ or _END_. These are skipped because they are used for scoping local symbols in ELF.

The following sample code shows an example of iterating the object section and skipping the correct symbols:

#include <gelf.h>
#include <stdio.h>

/*
 * Given the start of the object section in a CTFv3 file, the number of symbols,
 * and the ELF Data sections for the symbol table and the string table, this
 * prints the type identifiers that correspond to objects. Note, a more robust
 * implementation should ensure that they don't walk beyond the end of the CTF
 * object section.
 *
 * An implementation that handles CTFv2 must take into account the fact that
 * type identifiers are 16 bits wide rather than 32 bits wide.
 */
static int
walk_symbols(uint32_t *objtoff, Elf_Data *symdata, Elf_Data *strdata,
    long nsyms)
{
	long i;
	uintptr_t strbase = strdata->d_buf;

	for (i = 1; i < nsyms; i++, objftoff++) {
		const char *name;
		GElf_Sym sym;

		if (gelf_getsym(symdata, i, &sym) == NULL)
			return (1);

		if (GELF_ST_TYPE(sym.st_info) != STT_OBJECT)
			continue;
		if (sym.st_shndx == SHN_UNDEF || sym.st_name == 0)
			continue;
		if (sym.st_shndx == SHN_ABS && sym.st_value == 0)
			continue;
		name = (const char *)(strbase + sym.st_name);
		if (strcmp(name, "_START_") == 0 || strcmp(name, "_END_") == 0)
			continue;

		(void) printf("Symbol %d has type %d0, i, *objtoff);
	}

	return (0);
}

The Function Section

For functions that have no type information, nothing else is encoded, and the next function is encoded. For functions with type information, the next uint32_t is encoded with the type identifier of the return type of the function. It is followed by each of the type identifiers of the arguments, if any exist, in the order that they appear in the function. Therefore, argument 0 is the first type identifier and so on. When a function has a final varargs argument, that is encoded with the type identifier of zero.

Like The Object Section, the function section is encoded in the order of the symbol table. It has similar, but slightly different considerations from objects. While iterating the symbol table, if any of the following conditions are true, then the entry is skipped and no corresponding entry is written:

• The symbol type is not STT_FUNCTION
• The symbol's section index is SHN_UNDEF
• The symbol's name offset is zero
• The symbol's name is _START_ or _END_. These are skipped because they are used for scoping local symbols in ELF.

The Type Section

#define	CTF_V3_MAX_SIZE		0xfffffffe	/* max size of a type in bytes */
#define	CTF_V3_LSIZE_SENT	0xffffffff	/* sentinel for ctt_size */
#define	CTF_V3_MAX_LSIZE	UINT64_MAX

struct ctf_stype_v3 {
	uint32_t ctt_name;	/* reference to name in string table */
	uint32_t ctt_info;	/* encoded kind, variant length */
	union {
		uint32_t _size;	/* size of entire type in bytes */
		uint32_t _type;	/* reference to another type */
	} _u;
};

struct ctf_type_v3 {
	uint32_t ctt_name;	/* reference to name in string table */
	uint32_t ctt_info;	/* encoded kind, variant length */
	union {
		uint32_t _size;	/* always CTF_LSIZE_SENT */
		uint32_t _type; /* do not use */
	} _u;
	uint32_t ctt_lsizehi;	/* high 32 bits of type size in bytes */
	uint32_t ctt_lsizelo;	/* low 32 bits of type size in bytes */
};

#define	ctt_size _u._size	/* for fundamental types that have a size */
#define	ctt_type _u._type	/* for types that reference another type */

Type sizes are stored in bytes. The basic small form uses a uint32_t to store the number of bytes. If the number of bytes in a structure would exceed 0xfffffffe, then the alternate form, the struct ctf_type_v3, is used instead. To indicate that the larger form is being used, the member ctt_size is set to value of CTF_V3_LSIZE_SENT (0xffffffff). In general, when going through the type section, consumers use the struct ctf_type_v3 structure, but pay attention to the value of the member ctt_size to determine whether they should increment their scan by the size of struct ctf_stype_v3 or struct ctf_type_v3. Not all kinds of types use ctt_size. Those which do not, will always use the struct ctf_stype_v3 structure. The individual sections for each kind have more information.

Types are written out in order. Therefore the first entry encountered has a type id of 0x1, or 0x8000 if a child. The member ctt_name is encoded as described in the section String Identifiers. The string that it points to is the name of the type. If the identifier points to an empty string (one that consists solely of a null terminator) then the type does not have a name, this is common with anonymous structures and unions that only have a typedef to name them, as well as pointers and qualifiers.

The next member, the ctt_info, is encoded as described in the section Type Encoding. The type's kind tells us how to interpret the remaining data in the struct ctf_type_v3 and any variable length data that may exist. The rest of this section will be broken down into the interpretation of the various kinds.

Encoding of Integers

The integer encoding contains three different pieces of information:

• The encoding of the integer
• The offset in bits of the type
• The size in bits of the type

This encoding can be expressed through the following macros:

#define	CTF_INT_ENCODING(data)	(((data) & 0xff000000) >> 24)
#define	CTF_INT_OFFSET(data)	(((data) & 0x00ff0000) >> 16)
#define	CTF_INT_BITS(data)	(((data) & 0x0000ffff))

#define	CTF_INT_DATA(encoding, offset, bits) \
	(((encoding) << 24) | ((offset) << 16) | (bits))

The following flags are defined for the encoding at this time:

#define	CTF_INT_SIGNED		0x01
#define	CTF_INT_CHAR		0x02
#define	CTF_INT_BOOL		0x04
#define	CTF_INT_VARARGS		0x08

By default, an integer is considered to be unsigned, unless it has the CTF_INT_SIGNED flag set. If the flag CTF_INT_CHAR is set, that indicates that the integer is of a type that stores character data, for example the intrinsic C type char would have the CTF_INT_CHAR flag set. If the flag CTF_INT_BOOL is set, that indicates that the integer represents a boolean type. For example, the intrinsic C type _Bool would have the CTF_INT_BOOL flag set. Finally, the flag CTF_INT_VARARGS indicates that the integer is used as part of a variable number of arguments. This encoding is rather uncommon.

Encoding of Floats

• The specific kind of float that exists
• The offset in bits of the float
• The size in bits of the float

This encoding can be expressed through the following macros:

#define	CTF_FP_ENCODING(data)	(((data) & 0xff000000) >> 24)
#define	CTF_FP_OFFSET(data)	(((data) & 0x00ff0000) >> 16)
#define	CTF_FP_BITS(data)	(((data) & 0x0000ffff))

#define	CTF_FP_DATA(encoding, offset, bits) \
	(((encoding) << 24) | ((offset) << 16) | (bits))

Where as the encoding for integers is a series of flags, the encoding for floats maps to a specific kind of float. It is not a flag-based value. The kinds of floats correspond to both their size, and the encoding. This covers all of the basic C intrinsic floating point types. The following are the different kinds of floats represented in the encoding:

#define	CTF_FP_SINGLE	1	/* IEEE 32-bit float encoding */
#define	CTF_FP_DOUBLE	2	/* IEEE 64-bit float encoding */
#define	CTF_FP_CPLX	3	/* Complex encoding */
#define	CTF_FP_DCPLX	4	/* Double complex encoding */
#define	CTF_FP_LDCPLX	5	/* Long double complex encoding */
#define	CTF_FP_LDOUBLE	6	/* Long double encoding */
#define	CTF_FP_INTRVL	7	/* Interval (2x32-bit) encoding */
#define	CTF_FP_DINTRVL	8	/* Double interval (2x64-bit) encoding */
#define	CTF_FP_LDINTRVL	9	/* Long double interval (2x128-bit) encoding */
#define	CTF_FP_IMAGRY	10	/* Imaginary (32-bit) encoding */
#define	CTF_FP_DIMAGRY	11	/* Long imaginary (64-bit) encoding */
#define	CTF_FP_LDIMAGRY	12	/* Long double imaginary (128-bit) encoding */

Encoding of Arrays

struct ctf_array_v3 {
	uint32_t cta_contents;	/* reference to type of array contents */
	uint32_t cta_index;	/* reference to type of array index */
	uint32_t cta_nelems;	/* number of elements */
};

The cta_contents and cta_index members of the struct ctf_array_v3 are type identifiers which are encoded as per the section Type Identifiers. The member cta_nelems is a simple four byte unsigned count of the number of elements. This count may be zero when encountering C99's flexible array members.

Encoding of Functions

The variable argument list contains the type identifiers for the arguments of the function, if any. Each one is represented by a uint32_t and encoded according to the Type Identifiers section. If the function's last argument is of type varargs, then it is also written out, but the type identifier is zero. This is included in the count of the function's arguments. In ctf version 2, an extra type identifier may follow the argument and return type identifiers in order to maintain four-byte alignment for the following type definition. Such a type identifier is not included in the argument count and has a value of zero. In ctf version 3, four-byte alignment occurs naturally and no padding is used.

Encoding of Structures and Unions

struct ctf_member_v3 {
	uint32_t ctm_name;	/* reference to name in string table */
	uint32_t ctm_type;	/* reference to type of member */
	uint32_t ctm_offset;	/* offset of this member in bits */
};

struct ctf_lmember_v3 {
	uint32_t ctlm_name;	/* reference to name in string table */
	uint32_t ctlm_type;	/* reference to type of member */
	uint32_t ctlm_offsethi;	/* high 32 bits of member offset in bits */
	uint32_t ctlm_offsetlo;	/* low 32 bits of member offset in bits */
};

Both the ctm_name and ctlm_name refer to the name of the member. The name is encoded as an offset into the string table as described by the section String Identifiers. The members ctm_type and ctlm_type both refer to the type of the member. They are encoded as per the section Type Identifiers.

The last piece of information that is present is the offset which describes the offset in memory at which the member begins. For unions, this value will always be zero because each member of a union has an offset of zero. For structures, this is the offset in bits at which the member begins. Note that a compiler may lay out a type with padding. This means that the difference in offset between two consecutive members may be larger than the size of the member. When the size of the overall structure is strictly less than 536870912 bytes, the normal structure, struct ctf_member_v3, is used and the offset in bits is stored in the member ctm_offset. However, when the size of the structure is greater than or equal to 536870912 bytes, then the number of bits is split into two 32-bit quantities. One member, ctlm_offsethi, represents the upper 32 bits of the offset, while the other member, ctlm_offsetlo, represents the lower 32 bits of the offset. These can be joined together to get a 64-bit sized offset in bits by shifting the member ctlm_offsethi to the left by thirty two and then doing a binary or of ctlm_offsetlo.

Encoding of Enumerations

The enumerators encoded in an enumeration have the following structure in the variable list:

typedef struct ctf_enum {
	uint32_t cte_name;	/* reference to name in string table */
	int32_t cte_value;	/* value associated with this name */
} ctf_enum_t;

The member cte_name refers to the name of the enumerator's value, it is encoded according to the rules in the section String Identifiers. The member cte_value contains the integer value of this enumerator.

Encoding of Forward References

Encoding of Pointers, Typedefs, Volatile, Const, and Restrict

These types have no variable list entries and use the member ctt_type to refer to the base type that they modify.

Encoding of Unknown Types

Dependencies Between Types

The String Section

The first entry in the section, at offset zero, is a single null terminator to reference the empty string. Following that, each C string should be written out, including the null terminator. Offsets that refer to something in this section should refer to the first byte which begins a string. Beyond the first byte in the section being the null terminator, the order of strings is unimportant.

Data Encoding and ELF Considerations

When placing a ctf container inside of an ELF object, there are certain conventions that are expected for the purposes of tooling being able to find the ctf data. In particular, a given ELF object should only contain a single ctf section. Multiple containers should be merged together into a single one.

The ctf file should be included in its own ELF section. The section's name must be ‘.SUNW_ctf’. The type of the section must be SHT_PROGBITS. The section should have a link set to the symbol table and its address alignment must be 4.