Differential D34360 Diff 103577 cddl/contrib/opensolaris/lib/libctf/common/ctf.5

Changeset View

Standalone View

View Options

cddl/contrib/opensolaris/lib/libctf/common/ctf.5

.\"

.\" This file and its contents are supplied under the terms of the

.\" Common Development and Distribution License ("CDDL"), version 1.0.

.\" You may only use this file in accordance with the terms of version

.\" 1.0 of the CDDL.

.\"

.\" A full copy of the text of the CDDL should have accompanied this

.\" source. A copy of the CDDL is also available via the Internet at

.\" http://www.illumos.org/license/CDDL.

.\"

.Dd Sep 26, 2014

.Dd February 28, 2022

.Dt CTF 5

.Os

.Sh NAME

.Nm ctf

.Nd Compact C Type Format

.Sh SYNOPSIS

.In sys/ctf.h

.Sh DESCRIPTION

Show All 37 Lines

.Xr dtrace 1 .

Programmatic access to

.Nm

data can be obtained through libctf.

.Lp

The

.Nm

file format is broken down into seven different sections.

The first section is the

The first two sections are the

pauamma_gundo.comUnsubmitted

Done

file format is broken down into seven different sections.

- The first section is the

+ The first two sections are the

.Sy preamble

preamble and header are separate sections, consistent with ASCII art below and sections numbering 7.

pauamma_gundo.com: preamble and header are separate sections, consistent with ASCII art below and sections…

.Sy preamble

and

.Sy header ,

which describes the version of the

which describe the version of the

pauamma_gundo.comUnsubmitted

Done

.Sy header ,

- which describes the version of the

+ which describe the version of the

.Nm

file, the links it has to other

pauamma_gundo.com:

.Nm

file, the links it has to other

.Nm

files, and the sizes of the other sections.

The next section is the

.Sy label

section,

which provides a way of identifying similar groups of

▲ Show 20 Lines • Show All 43 Lines • ▼ Show 20 Lines

A common example of this is that most kernel modules in illumos are uniquified

against the kernel module

.Sy genunix

and the type information that comes from the

.Sy IP

module.

This means that a module only has types that are unique to itself and the most

common types in the kernel are not duplicated.

Uniquification is not used when building kernel modules on

.Fx .

.Sh FILE FORMAT

This documents version

.Em two

.Em three

of the

.Nm

file format.

All applications and tools on

The

.Fx

.Xr ctfconvert 1

currently produce and operate on this version.

and

.Xr ctfmerge 1

utilities emit

.Nm

version 3, and all other applications and libraries can operate on

versions 2 and 3.

.Lp

The file format can be summarized with the following image, the

pauamma_gundo.comUnsubmitted

Not Done

Please remove the whole ASCII art segment and make sure the description under it using C declarations is complete by itself. You can't reasonably expect a screenreader user to tolerate 4K of ASCII, let alone make sense of it.

pauamma_gundo.com: Please remove the whole ASCII art segment and make sure the description under it using C…

markjAuthorUnsubmitted

Done

It's been helpful in the past, so I prefer to keep it. This document describes a file format that's useful to a vanishingly small number of developers who work on kernel tracing utilities.

Having worked in the past for a few years for someone who relied a screenreader and wrote some elaborate system software based on dense Infiniband specs replete with tables, diagrams, etc., please forgive me for being skeptical that deleting this diagram represents much of an accessibility improvement. Nonetheless, feel free to submit a patch which does as you request, I will merge it.

markj: It's been helpful in the past, so I prefer to keep it. This document describes a file format…

pauamma_gundo.comUnsubmitted

Not Done

They may have found it possible. That doesn't mean it was at all easy or that others may have succeeded, and I believe this kind of difficulty is the same as what Fred Brooks calls "accidental complexity" in one of the essays in The Mythical Man Month. The gist of that essay is that every change that lowers accidental complexity (as opposed to essential complexity) is worth making for that very reason.

So if no one beats me to that, I will indeed submit an accessibility patch as soon as I have time for that.

pauamma_gundo.com: They may have found it possible. That doesn't mean it was at all easy or that others may have…

following sections will cover this in more detail.

.Bd -literal

+-------------+ 0t0

pauamma_gundo.comUnsubmitted

Not Done

What does the 0t prefix mean anyway?

pauamma_gundo.com: What does the 0t prefix mean anyway?

markjAuthorUnsubmitted

Done

It's a prefix sometimes used to indicate octal representation. I'm not sure why it's used here.

markj: It's a prefix sometimes used to indicate octal representation. I'm not sure why it's used here.

pauamma_gundo.comUnsubmitted

Not Done

Looking at the 0t36+ctf_*off offsets in this diagram and the text below, for instance;

Therefore, something with an offset of 0 is at an offset of thirty-six
bytes relative to the start of the
.Nm
file.

implies those offsets aren't octal at all (which is one interpretation of "not sure why", another being "the offsets should use decimal instead"). Can you confirm that 36 is actually decimal 36, not octal 36 = decimal 30?

pauamma_gundo.com: Looking at the 0t36+ctf_*off offsets in this diagram and the text below, for instance; ```…

markjAuthorUnsubmitted

Done

Yes, it looks like it should indeed be decimal. Apparently in Solaris "0t" is supposed to denote a decimal number, not an octal number, at least based on their printf man page: https://docs.oracle.com/cd/E19683-01/806-6545/api-21/index.html

So the man page is correct, but uses some rather unfamiliar notation.

markj: Yes, it looks like it should indeed be decimal. Apparently in Solaris "0t" is supposed to…

+--------| Preamble |

| +-------------+ 0t4

|+-------| Header |

|| +-------------+ 0t36 + cth_lbloff

||+------| Labels |

||| +-------------+ 0t36 + cth_objtoff

|||+-----| Objects |

|||| +-------------+ 0t36 + cth_funcoff

||||+----| Functions |

||||| +-------------+ 0t36 + cth_typeoff

|||||+---| Types |

|||||| +-------------+ 0t36 + cth_stroff

||||||+--| Strings |

||||||| +-------------+ 0t36 + cth_stroff + cth_strlen

|||||||

||||||| +-- magic - vers flags

||||||| | | | |

||||||| +------+------+------+------+

+---------| 0xcf | 0xf1 | 0x02 | 0x00 |

+---------| 0xcf | 0xf1 | 0x03 | 0x00 |

emasteUnsubmitted

Done

vers 0x03 now?

emaste: vers 0x03 now?

|||||| +------+------+------+------+

|||||| 0 1 2 3 4

||||||

|||||| + parent label + objects

|||||| | + parent name | + functions + strings

|||||| | | + label | | + types | + strlen

|||||| | | | | | | | |

|||||| +------+------+------+------+------+-------+-------+-------+

+--------| 0x00 | 0x00 | 0x00 | 0x08 | 0x36 | 0x110 | 0x5f4 | 0x611 |

||||| +------+------+------+------+------+-------+-------+-------+

||||| 0x04 0x08 0x0c 0x10 0x14 0x18 0x1c 0x20 0x24

|||||

||||| + Label name

||||| | + Label type

||||| | | + Next label

||||| | | |

||||| +-------+------+-----+

+-----------| 0x01 | 0x42 | ... |

|||| +-------+------+-----+

|||| cth_lbloff +0x4 +0x8 cth_objtoff

||||

|||| Symidx 0t15 0t43 0t44

|||| +------+------+------+-----+

+----------| 0x00 | 0x42 | 0x36 | ... |

emasteUnsubmitted

Not Done

Should we make these 0x0000 0x0042 0x0036 now?
And similar elsewhere.

emaste: Should we make these 0x0000 0x0042 0x0036 now? And similar elsewhere.

markjAuthorUnsubmitted

Done

Well, to be pedantic it should really be 0x00000000, 0x00000042, 0x00000036, no? I don't know that it's really useful to expand the sample values to the proper width when the offsets are provided as well.

markj: Well, to be pedantic it should really be 0x00000000, 0x00000042, 0x00000036, no? I don't know…

emasteUnsubmitted

Not Done

Well, to be pedantic it should really be 0x00000000, 0x00000042, 0x00000036, no? I don't know that it's really useful to expand the sample values to the proper width when the offsets are provided as well.

Oh, indeed, it should have been 0x0000, 0x0042 already if my comment was to hold. Fine.

emaste: > Well, to be pedantic it should really be 0x00000000, 0x00000042, 0x00000036, no? I don't know…

||| +------+------+------+-----+

||| cth_objtoff +0x2 +0x4 +0x6 cth_funcoff

||| cth_objtoff +0x4 +0x8 +0xc cth_funcoff

|||

||| + CTF_TYPE_INFO + CTF_TYPE_INFO

||| | + Return type |

||| | | + arg0 |

||| +--------+------+------+-----+

+---------| 0x2c10 | 0x08 | 0x0c | ... |

|| +--------+------+------+-----+

|| cth_funcff +0x2 +0x4 +0x6 cth_typeoff

|| cth_funcff +0x4 +0x8 +0xc cth_typeoff

|| + ctf_stype_t for type 1

|| | integer + integer encoding

|| | | + ctf_stype_t for type 2

|| | | |

|| +--------------------+-----------+-----+

+--------| 0x19 * 0xc01 * 0x0 | 0x1000000 | ... |

| +--------------------+-----------+-----+

| cth_typeoff +0x08 +0x0c cth_stroff

| cth_typeoff +0x0c +0x10 cth_stroff

| +--- str 0

| | +--- str 1 + str 2

| | | |

| v v v

| +----+---+---+---+----+---+---+---+---+---+----+

+---| \\0 | i | n | t | \\0 | f | o | o | _ | t | \\0 |

+----+---+---+---+----+---+---+---+---+---+----+

Show All 40 Lines

.Nm

file.

The

.Em ctp_version

member defines the version of the

.Nm

file.

The current version is

.Li 2 .

.Li 3 .

It is possible to encounter an unsupported version.

In that case, software should not try to parse the format, as it may have

changed.

Finally, the

.Em ctp_flags

member describes aspects of the file which modify its interpretation.

The following flags are currently defined:

.Bd -literal

Show All 14 Lines

If this flag is not present, then the body has not been compressed and no

special action is needed to interpret it.

All offsets into the data as described by

.Sy header ,

always refer to the

.Sy uncompressed

data.

.Lp

In version two of the

In versions two and three of the

.Nm

file format, the

.Sy header

denotes whether or not this

.Nm

file is the child of another

.Nm

file and also indicates the size of the remaining sections.

Show All 14 Lines

typedef struct ctf_header {

uint32_t cth_stroff; /* offset of string section */

uint32_t cth_strlen; /* length of string section in bytes */

} ctf_header_t;

.Ed

.Pp

After the

.Sy preamble ,

the next two members

.Em cth_parlablel

.Em cth_parlabel

pauamma_gundo.comUnsubmitted

Done

the next two members

- .Em cth_parlablel

+ .Em cth_parlabel

and

.Em cth_parname ,

pauamma_gundo.com:

and

.Em cth_parname ,

are used to identify the parent.

The value of both members are offsets into the

.Sy string

section which point to the start of a null-terminated string.

For more information on the encoding of strings, see the subsection on

.Sx String Identifiers .

Show All 13 Lines

For more information on labels and their interpretation, see

.Sx The Label Section .

.Lp

The remaining members (excepting

.Em cth_strlen )

describe the beginning of the corresponding sections.

These offsets are relative to the end of the

.Sy header .

Therefore, something with an offset of 0 is at an offset of thirty-six

pauamma_gundo.comUnsubmitted

Not Done

If this change or a stacked one embiggen the preamble or the header, "thirty-six" needs to be updated.

pauamma_gundo.com: If this change or a stacked one embiggen the preamble or the header, "thirty-six" needs to be…

markjAuthorUnsubmitted

Done

The header is unchanged.

markj: The header is unchanged.

bytes relative to the start of the

.Nm

file.

The difference between members indicates the size of the section itself.

Different offsets have different alignment requirements.

The start of the

.Em cth_objotoff

.Em cth_objtoff

pauamma_gundo.comUnsubmitted

Done

The start of the

- .Em cth_objotoff

+ .Em cth_objtoff

and

.Em cth_funcoff

pauamma_gundo.com:

and

.Em cth_funcoff

must be two byte aligned, while the sections

.Em cth_lbloff

and

.Em cth_typeoff

must be four-byte aligned.

The section

.Em cth_stroff

has no alignment requirements.

To calculate the size of a given section, excepting the

.Sy string

section, one should subtract the offset of the section from the following one.

For example, the size of the

.Sy types

section can be calculated by subtracting

.Em cth_stroff

.Em cth_typeoff

from

.Em cth_typeoff .

.Em cth_stroff .

pauamma_gundo.comUnsubmitted

Done

Isn't that the other way? Subtract the offset of the earlier section (cth_typeoff) from the offset of the latter section (cth_stroff)?

pauamma_gundo.com: Isn't that the other way? Subtract the offset of the earlier section (cth_typeoff) from the…

.Lp

Finally, the member

.Em cth_strlen

describes the length of the string section itself.

From it, you can also calculate the size of the entire

.Nm

file by adding together the size of the

.Sy ctf_header_t ,

the offset of the string section in

.Em cth_stroff ,

and the size of the string section in

.Em cth_srlen .

.Ss Type Identifiers

Through the

.Nm ctf

data, types are referred to by identifiers.

A given

.Nm

file supports up to 32767 (0x7fff) types.

file supports up to 2147483646 (0x7ffffffe) types.

.Nm

version 2 had a much smaller limit of 32767 types.

emasteUnsubmitted

Done

32767 or 32768?

emaste: 32767 or 32768?

The first valid type identifier is 0x1.

When a given

.Nm

file is a child, indicated by a non-zero entry for the

.Sy header Ns 's

.Em cth_parname ,

then the first valid type identifier is 0x8000 and the last is 0xffff.

then the first valid type identifier is 0x80000000 and the last is 0xfffffffe.

In this case, type identifiers 0x1 through 0x7fff are references to the

In this case, type identifiers 0x1 through 0x7ffffffe are references to the

parent.

0x7fffffff and 0xffffffff are not treated as valid type identifiers so as to

enable the use of -1 as an error value.

pauamma_gundo.comUnsubmitted

Not Done

31-bit signed integers? (Otherwise, 0x7fffffff isn't -1.)

pauamma_gundo.com: 31-bit signed integers? (Otherwise, 0x7fffffff isn't -1.)

markjAuthorUnsubmitted

Done

From the description of child containers above, there are two type identifier spaces [0x1, 0x7ffffffe] and [0x80000001, 0xfffffffe] which have a one-to-one correspondence. 0xffffffff is not a valid type identifier, so 0x7fffffff cannot be valid either.

markj: From the description of child containers above, there are two type identifier spaces [0x1…

.Lp

The type identifier zero is a sentinel value used to indicate that there

is no type information available or it is an unknown type.

.Lp

Throughout the file format, the identifier is stored in different sized

values; however, the minimum size to represent a given identifier is a

.Sy uint16_t .

Other consumers of

Show All 16 Lines

String table identifier one refers to an external string table which is the ELF

string table for the ELF symbol table associated with the

.Nm

container.

.Ss Type Encoding

Every

.Nm

type begins with metadata encoded into a

.Sy uint16_t .

.Sy uint32_t .

This encoded information tells us three different pieces of information:

.Bl -bullet -offset indent -compact

.It

The kind of the type

.It

Whether this type is a root type or not

.It

The length of the variable data

.El

.Lp

The 16 bits that make up the encoding are broken down such that you have

The 32 bits that make up the encoding are broken down into six bits

five bits for the kind, one bit for indicating whether or not it is a

for the kind (bits 26 to 31), one bit for the root type flag (bit 25),

root type, and 10 bits for the variable length.

and 25 bits for the length of the variable data.

pauamma_gundo.comUnsubmitted

Done

The length of the variable data

.El

.Lp

- The 32 bits that make up the encoding are broken down such that you have

- six bits for the kind, one bit for indicating whether or not it is a

- root type, and 25 bits for the variable length.

- This is laid out as follows:

- .Bd -literal -offset indent

- +--------------------+

- | kind | root | vlen |

- +--------------------+

- 32 26 25 25 0

- .Ed

- .Lp

+ The 32 bits that make up the encoding are broken down into

+ six bits for kind (bits 31 to 26), one bit for the

+ root type flag (bit 25), and 25 bits for vlen (bits 24 to 0)..Lp

The current version of the file format defines 14 different kinds.

Most significant bit is 31, not 32, since bit number start at 0. Likewise, most significant bit of vlen is 24, since bit 25 is root.

Also, should kind, root, and vlen have .Sy (or maybe .Em as used elsewhere for struct fields)?

pauamma_gundo.com: Most significant bit is 31, not 32, since bit number start at 0. Likewise, most significant bit…

This is laid out as follows:

.Bd -literal -offset indent

+--------------------+

| kind | root | vlen |

+--------------------+

15 11 10 9 0

.Ed

.Lp

The current version of the file format defines 14 different kinds.

The interpretation of these different kinds will be discussed in the section

.Sx The Type Section .

If a kind is encountered that is not listed below, then it is not a valid

.Nm

file.

The kinds are defined as follows:

Show All 21 Lines

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

.Sy root

type.

If a type is a

.Sy root

type, then it will have bit 10 set.

type, then it will have bit 25 set.

.Lp

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

section

.Sx The Type Section .

.Lp

The following macros are useful for constructing and deconstructing the encoded

type information:

.Bd -literal -offset indent

#define CTF_MAX_VLEN 0x3ff

#define CTF_V3_MAX_VLEN 0x00ffffff

#define CTF_INFO_KIND(info) (((info) & 0xf800) >> 11)

#define CTF_V3_INFO_KIND(info) (((info) & 0xfc000000) >> 26)

#define CTF_INFO_ISROOT(info) (((info) & 0x0400) >> 10)

#define CTF_V3_INFO_ISROOT(info) (((info) & 0x02000000) >> 25)

#define CTF_INFO_VLEN(info) (((info) & CTF_MAX_VLEN))

#define CTF_V3_INFO_VLEN(info) (((info) & CTF_V3_MAX_VLEN))

#define CTF_TYPE_INFO(kind, isroot, vlen) \\

#define CTF_V3_TYPE_INFO(kind, isroot, vlen) \\

(((kind) << 11) | (((isroot) ? 1 : 0) << 10) | ((vlen) & CTF_MAX_VLEN))

(((kind) << 26) | (((isroot) ? 1 : 0) << 25) | ((vlen) & CTF_V3_MAX_VLEN))

.Ed

.Ss The Label Section

When consuming

.Nm

data, it is often useful to know whether two different

.Nm

containers come from the same source base and version.

For example, when building illumos, there are many kernel modules that are built

against a single collection of source code.

A label is encoded into the

.Nm

files that corresponds with the particular build.

This ensures that if files on the system were to become mixed up from multiple

releases, that they are not used together by tools, particularly when a child

needs to refer to a type in the parent.

Because they are linked using the type identifiers, if the wrong parent is used

then the wrong type will be encountered.

Note that this mechanism is not currently used on

.Fx .

In particular, kernel modules built on

.Fx

each contain a complete type graph.

.Lp

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

structure:

.Bd -literal

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;

Show All 21 Lines

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.

.Ss The Object Section

The object section provides a mapping from ELF symbols of type

.Sy STT_OBJECT

in the symbol table to a type identifier.

Every entry in this section is a

.Sy uint16_t

.Sy uint32_t

which contains a type identifier as described in the section

.Sx Type Identifiers .

If there is no information for an object, then the type identifier 0x0

is stored for that entry.

.Lp

To walk the object section, you need to have a corresponding

.Sy symbol table

in the ELF object that contains the

Show All 27 Lines

.Lp

The following sample code shows an example of iterating the object

section and skipping the correct symbols:

.Bd -literal

#include <gelf.h>

#include <stdio.h>

* Given the start of the object section in the CTF file, the number of symbols,

* 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(uint16_t *objtoff, Elf_Data *symdata, Elf_Data *strdata,

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;

Show All 26 Lines

.Sx The Object Section ,

the function section encodes information for all symbols of type

.Sy STT_FUNCTION ,

excepting those that fit specific criteria.

Unlike with objects, because functions have a variable number of arguments, they

start with a type encoding as defined in

.Sx Type Encoding ,

which is the size of a

.Sy uint16_t .

.Sy uint32_t .

For functions which have no type information available, they are encoded as

.Li CTF_TYPE_INFO(CTF_K_UNKNOWN, 0, 0) .

.Li CTF_V3_TYPE_INFO(CTF_K_UNKNOWN, 0, 0) .

Functions with arguments are encoded differently.

Here, the variable length is turned into the number of arguments in the

function.

If a function is a

.Sy varargs

type function, then the number of arguments is increased by one.

Functions with type information are encoded as:

.Li CTF_TYPE_INFO(CTF_K_FUNCTION, 0, nargs) .

.Li CTF_V3_TYPE_INFO(CTF_K_FUNCTION, 0, nargs) .

.Lp

For functions that have no type information, nothing else is encoded, and the

next function is encoded.

For functions with type information, the next

.Sy uint16_t

.Sy 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.

.Lp

Show All 24 Lines

The type section is the heart of the

.Nm

data.

It encodes all of the information about the types themselves.

The base of the type information comes in two forms, a short form and a long

form, each of which may be followed by a variable number of arguments.

The following definitions describe the short and long forms:

.Bd -literal

#define CTF_MAX_SIZE 0xfffe /* max size of a type in bytes */

#define CTF_V3_MAX_SIZE 0xfffffffe /* max size of a type in bytes */

#define CTF_LSIZE_SENT 0xffff /* sentinel for ctt_size */

#define CTF_V3_LSIZE_SENT 0xffffffff /* sentinel for ctt_size */

#define CTF_MAX_LSIZE UINT64_MAX

#define CTF_V3_MAX_LSIZE UINT64_MAX

typedef struct ctf_stype {

struct ctf_stype_v3 {

uint32_t ctt_name; /* reference to name in string table */

uint16_t ctt_info; /* encoded kind, variant length */

uint32_t ctt_info; /* encoded kind, variant length */

union {

uint16_t _size; /* size of entire type in bytes */

uint32_t _size; /* size of entire type in bytes */

uint16_t _type; /* reference to another type */

uint32_t _type; /* reference to another type */

} _u;

} ctf_stype_t;

};

typedef struct ctf_type {

struct ctf_type_v3 {

uint32_t ctt_name; /* reference to name in string table */

uint16_t ctt_info; /* encoded kind, variant length */

uint32_t ctt_info; /* encoded kind, variant length */

union {

uint16_t _size; /* always CTF_LSIZE_SENT */

uint32_t _size; /* always CTF_LSIZE_SENT */

uint16_t _type; /* do not use */

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 */

} ctf_type_t;

};

#define ctt_size _u._size /* for fundamental types that have a size */

#define ctt_type _u._type /* for types that reference another type */

.Ed

.Pp

Type sizes are stored in

.Sy bytes .

The basic small form uses a

.Sy uint16_t

.Sy uint32_t

to store the number of bytes.

If the number of bytes in a structure would exceed 0xfffe, then the alternate

If the number of bytes in a structure would exceed 0xfffffffe, then the

form, the

alternate form, the

.Sy ctf_type_t ,

.Sy struct ctf_type_v3 ,

is used instead.

To indicate that the larger form is being used, the member

.Em ctt_size

is set to value of

.Sy CTF_LSIZE_SENT

.Sy CTF_V3_LSIZE_SENT

(0xffff).

(0xffffffff).

In general, when going through the type section, consumers use the

.Sy ctf_type_t

.Sy struct ctf_type_v3

structure, but pay attention to the value of the member

.Em ctt_size

to determine whether they should increment their scan by the size of the

to determine whether they should increment their scan by the size of

.Sy ctf_stype_t

.Sy struct ctf_stype_v3

.Sy ctf_type_t .

.Sy struct ctf_type_v3 .

Not all kinds of types use

.Sy ctt_size .

Those which do not, will always use the

.Sy ctf_stype_t

.Sy struct ctf_stype_v3

structure.

The individual sections for each kind have more information.

.Lp

Types are written out in order.

Therefore the first entry encountered has a type id of 0x1, or 0x8000 if a

child.

The member

.Em ctt_name

is encoded as described in the section

.Sx 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.

.Lp

The next member, the

.Em ctt_info ,

is encoded as described in the section

.Sx Type Encoding .

The type's kind tells us how to interpret the remaining data in the

.Sy ctf_type_t

.Sy 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.

.Ss Encoding of Integers

Integers, which are of type

.Sy CTF_K_INTEGER ,

have no variable length arguments.

Instead, they are followed by a

▲ Show 20 Lines • Show All 121 Lines • ▼ Show 20 Lines

They are followed by a structure which describes the number of elements in the

array, the type identifier of the elements in the array, and the type identifier

of the index of the array.

With arrays, the

.Em ctt_size

member is set to zero.

The structure that follows an array is defined as:

.Bd -literal

typedef struct ctf_array {

struct ctf_array_v3 {

uint16_t cta_contents; /* reference to type of array contents */

uint32_t cta_contents; /* reference to type of array contents */

uint16_t cta_index; /* reference to type of array index */

uint32_t cta_index; /* reference to type of array index */

uint32_t cta_nelems; /* number of elements */

} ctf_array_t;

};

.Ed

.Lp

The

.Em cta_contents

and

.Em cta_index

members of the

.Sy ctf_array_t

.Sy struct ctf_array_v3

are type identifiers which are encoded as per the section

.Sx Type Identifiers .

The member

.Em 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.

.Ss Encoding of Functions

Function types, which are of type

.Sy CTF_K_FUNCTION ,

use the variable length list to be the number of arguments in the function.

When the function has a final member which is a varargs, then the argument count

is incremented by one to account for the variable argument.

Here, the

.Em ctt_type

member is encoded with the type identifier of the return type of the function.

Note that the

.Em ctt_size

member is not used here.

.Lp

The variable argument list contains the type identifiers for the arguments of

the function, if any.

Each one is represented by a

.Sy uint16_t

.Sy uint32_t

and encoded according to the

.Sx 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.

An extra type identifier may follow the argument and return type identifiers

in order to maintain four-byte alignment for the following type definition.

.Nm

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.

.Nm

version 3, four-byte alignment occurs naturally and no padding is used.

.Ss Encoding of Structures and Unions

Structures and Unions, which are encoded with

.Sy CTF_K_STRUCT

and

.Sy CTF_K_UNION

respectively, are very similar constructs in C.

The main difference between them is the fact that members of a structure

follow one another, where as in a union, all members share the same memory.

They are also very similar in terms of their encoding in

.Nm .

The variable length argument for structures and unions represents the number of

members that they have.

The value of the member

.Em ctt_size

is the size of the structure and union.

There are two different structures which are used to encode members in the

variable list.

When the size of a structure or union is greater than or equal to the large

member threshold, 8192, then a different structure is used to encode the member,

member threshold, 536870912, then a different structure is used to encode the

all members are encoded using the same structure.

member; all members are encoded using the same structure.

pauamma_gundo.comUnsubmitted

Done

member threshold, 536870912, then a different structure is used to encode the

- member, all members are encoded using the same structure.

+ member; all members are encoded using the same structure.

The structure for members is as follows:

pauamma_gundo.com:

The structure for members is as follows:

.Bd -literal

typedef struct ctf_member {

struct ctf_member_v3 {

uint32_t ctm_name; /* reference to name in string table */

uint16_t ctm_type; /* reference to type of member */

uint32_t ctm_type; /* reference to type of member */

uint16_t ctm_offset; /* offset of this member in bits */

uint32_t ctm_offset; /* offset of this member in bits */

} ctf_member_t;

};

typedef struct ctf_lmember {

struct ctf_lmember_v3 {

uint32_t ctlm_name; /* reference to name in string table */

uint16_t ctlm_type; /* reference to type of member */

uint32_t ctlm_type; /* reference to type of member */

uint16_t ctlm_pad; /* padding */

uint32_t ctlm_offsethi; /* high 32 bits of member offset in bits */

uint32_t ctlm_offsetlo; /* low 32 bits of member offset in bits */

} ctf_lmember_t;

};

.Ed

.Lp

Both the

.Em ctm_name

and

.Em ctlm_name

refer to the name of the member.

The name is encoded as an offset into the string table as described by the

Show All 12 Lines

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

.Sy 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 8192 bytes, the

When the size of the overall structure is strictly less than 536870912 bytes,

normal structure,

the normal structure,

.Sy ctf_member_t ,

.Sy struct ctf_member_v3 ,

is used and the offset in bits is stored in the member

.Em ctm_offset .

However, when the size of the structure is greater than or equal to 8192 bytes,

However, when the size of the structure is greater than or equal to 536870912

then the number of bits is split into two 32-bit quantities.

bytes, then the number of bits is split into two 32-bit quantities.

One member,

.Em ctlm_offsethi ,

represents the upper 32 bits of the offset, while the other member,

.Em 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

.Em ctlm_offsethi

▲ Show 20 Lines • Show All 46 Lines • ▼ Show 20 Lines

file refer to types which may not have a definition at all, only a name.

If the

.Nm

file is a child, then it may be that the forward is resolved to an

actual type in the parent, otherwise the definition may be in another

.Nm

container or may not be known at all.

The only member of the

.Sy ctf_type_t

.Sy struct ctf_type_v3

that matters for a forward declaration is the

.Em ctt_name

which points to the name of the forward reference in the string table as

described earlier.

There is no other information recorded for forward references.

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

Pointers, typedefs, volatile, const, and restrict are all similar in

.Nm .

▲ Show 20 Lines • Show All 85 Lines • ▼ Show 20 Lines

file should be included in its own ELF section.

The section's name must be

.Ql .SUNW_ctf .

The type of the section must be

.Sy SHT_PROGBITS .

The section should have a link set to the symbol table and its address

alignment must be 4.

.Sh SEE ALSO

.Xr ctfconvert 1 ,

.Xr ctfdump 1 ,

.Xr ctfmerge 1 ,

.Xr dtrace 1 ,

.Xr elf 3 ,

.Xr gelf 3 ,

.Xr a.out 5 ,

.Xr elf 5 ,

.Xr arch 7