svn commit: r272851 - vendor/illumos/dist/man/man4
Mark Johnston
markj at FreeBSD.org
Thu Oct 9 23:11:36 UTC 2014
Author: markj
Date: Thu Oct 9 23:11:36 2014
New Revision: 272851
URL: https://svnweb.freebsd.org/changeset/base/272851
Log:
5202 want ctf(4)
Reviewed by: Keith M Wesolowski <wesolows at foobazco.org>
Reviewed by: Jerry Jelinek <jerry.jelinek at joyent.com>
Reviewed by: Garrett D'Amore <garrett at damore.org>
Approved by: Dan McDonald <danmcd at omniti.com>
Author: Robert Mustacchi <rm at joyent.com>
illumos/illumos-gate at fe2e029eea29fd49d0d9058dbd5b79a252667e6b
Added:
vendor/illumos/dist/man/man4/
vendor/illumos/dist/man/man4/ctf.4 (contents, props changed)
Added: vendor/illumos/dist/man/man4/ctf.4
==============================================================================
--- /dev/null 00:00:00 1970 (empty, because file is newly added)
+++ vendor/illumos/dist/man/man4/ctf.4 Thu Oct 9 23:11:36 2014 (r272851)
@@ -0,0 +1,1140 @@
+.\"
+.\" 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.
+.\"
+.\"
+.\" Copyright (c) 2014 Joyent, Inc.
+.\"
+.Dd Sep 26, 2014
+.Dt CTF 4
+.Os
+.Sh NAME
+.Nm ctf
+.Nd Compact C Type Format
+.Sh SYNOPSIS
+.In sys/ctf.h
+.Sh DESCRIPTION
+.Nm
+is designed to be a compact representation of the C programming
+language's type information focused on serving the needs of dynamic
+tracing, debuggers, and other in-situ and post-mortem introspection
+tools.
+.Nm
+data is generally included in
+.Sy ELF
+objects and is tagged as
+.Sy SHT_PROGBITS
+to ensure that the data is accessible in a running process and in subsequent
+core dumps, if generated.
+.Lp
+The
+.Nm
+data contained in each file has information about the layout and
+sizes of C types, including intrinsic types, enumerations, structures,
+typedefs, and unions, that are used by the corresponding
+.Sy ELF
+object. The
+.Nm
+data may also include information about the types of global objects and
+the return type and arguments of functions in the symbol table.
+.Lp
+Because a
+.Nm
+file is often embedded inside a file, rather than being a standalone
+file itself, it may also be referred to as a
+.Nm
+.Sy container .
+.Lp
+On illumos systems,
+.Nm
+data is consumed by multiple programs. It can be used by the modular
+debugger,
+.Xr mdb 1 ,
+as well as by
+.Xr dtrace 1M .
+Programmatic access to
+.Nm
+data can be obtained through
+.Xr libctf 3LIB .
+.Lp
+The
+.Nm
+file format is broken down into seven different sections. The first
+section is the
+.Sy preamble
+and
+.Sy header ,
+which describes the version of the
+.Nm
+file, 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
+.Nm
+data across multiple files. This is followed by the
+.Sy object
+information section, which describes the type of global
+symbols. The subsequent section is the
+.Sy function
+information section, which describes the return
+types and arguments of functions. The next section is the
+.Sy type
+information section, which describes
+the format and layout of the C types themselves, and finally the last
+section is the
+.Sy string
+section, which contains the names of types, enumerations, members, and
+labels.
+.Lp
+While strictly speaking, only the
+.Sy preamble
+and
+.Sy header
+are required, to be actually useful, both the type and string
+sections are necessary.
+.Lp
+A
+.Nm
+file may contain all of the type information that it requires, or it
+may optionally refer to another
+.Nm
+file which holds the remaining types. When a
+.Nm
+file refers to another file, it is called the
+.Sy child
+and the file it refers to is called the
+.Sy parent .
+A given file may only refer to one parent. This process is called
+.Em uniquification
+because it ensures each child only has type information that is
+unique to it. 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.
+.Sh FILE FORMAT
+This documents version
+.Em two
+of the
+.Nm
+file format. All applications and tools currently produce and operate on
+this version.
+.Lp
+The file format can be summarized with the following image, the
+following sections will cover this in more detail.
+.Bd -literal
+
+ +-------------+ 0t0
++--------| 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 |
+ |||||| +------+------+------+------+
+ |||||| 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 | ... |
+ ||| +------+------+------+-----+
+ ||| cth_objtoff +0x2 +0x4 +0x6 cth_funcoff
+ |||
+ ||| + CTF_TYPE_INFO + CTF_TYPE_INFO
+ ||| | + Return type |
+ ||| | | + arg0 |
+ ||| +--------+------+------+-----+
+ +---------| 0x2c10 | 0x08 | 0x0c | ... |
+ || +--------+------+------+-----+
+ || cth_funcff +0x2 +0x4 +0x6 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
+ |
+ | +--- str 0
+ | | +--- str 1 + str 2
+ | | | |
+ | v v v
+ | +----+---+---+---+----+---+---+---+---+---+----+
+ +---| \\0 | i | n | t | \\0 | f | o | o | _ | t | \\0 |
+ +----+---+---+---+----+---+---+---+---+---+----+
+ 0 1 2 3 4 5 6 7 8 9 10 11
+.Ed
+.Lp
+Every
+.Nm
+file begins with a
+.Sy preamble ,
+followed by a
+.Sy header .
+The
+.Sy preamble
+is defined as follows:
+.Bd -literal
+typedef struct ctf_preamble {
+ ushort_t ctp_magic; /* magic number (CTF_MAGIC) */
+ uchar_t ctp_version; /* data format version number (CTF_VERSION) */
+ uchar_t ctp_flags; /* flags (see below) */
+} ctf_preamble_t;
+.Ed
+.Pp
+The
+.Sy preamble
+is four bytes long and must be four byte aligned.
+This
+.Sy preamble
+defines the version of the
+.Nm
+file which defines the format of the rest of the header. While the
+header may change in subsequent versions, the preamble will not change
+across versions, though the interpretation of its flags may change from
+version to version. The
+.Em ctp_magic
+member defines the magic number for the
+.Nm
+file format. This must always be
+.Li 0xcff1 .
+If another value is encountered, then the file should not be treated as
+a
+.Nm
+file. The
+.Em ctp_version
+member defines the version of the
+.Nm
+file. The current version is
+.Li 2 .
+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
+#define CTF_F_COMPRESS 0x01
+.Ed
+.Pp
+The flag
+.Sy CTF_F_COMPRESS
+indicates that the body of the
+.Nm
+file, all the data following the
+.Sy header ,
+has been compressed through the
+.Sy zlib
+library and its
+.Sy deflate
+algorithm. 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
+.Nm
+file format, the
+.Sy header
+denotes whether whether or not this
+.Nm
+file is the child of another
+.Nm
+file and also indicates the size of the remaining sections. The
+structure for the
+.Sy header ,
+logically contains a copy of the
+.Sy preamble
+and the two have a combined size of 36 bytes.
+.Bd -literal
+typedef struct ctf_header {
+ ctf_preamble_t cth_preamble;
+ uint_t cth_parlabel; /* ref to name of parent lbl uniq'd against */
+ uint_t cth_parname; /* ref to basename of parent */
+ uint_t cth_lbloff; /* offset of label section */
+ uint_t cth_objtoff; /* offset of object section */
+ uint_t cth_funcoff; /* offset of function section */
+ uint_t cth_typeoff; /* offset of type section */
+ uint_t cth_stroff; /* offset of string section */
+ uint_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
+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 .
+If the value of either is zero, then there is no entry for that
+member. If the member
+.Em cth_parlabel
+is set, then the
+.Em ctf_parname
+member must be set, otherwise it will not be possible to find the
+parent. If
+.Em ctf_parname
+is set, it is not necessary to define
+.Em cth_parlabel ,
+as the parent may not have a label. 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
+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
+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
+from
+.Em cth_typeoff .
+.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. 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.
+In this case, type identifiers 0x1 through 0x7fff are references to the
+parent.
+.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
+.Nm
+information may use larger or opaque identifiers.
+.Ss String Identifiers
+String identifiers are always encoded as four byte unsigned integers
+which are an offset into a string table. The
+.Nm
+format supports two different string tables which have an identifier of
+zero or one. This identifier is stored in the high-order bit of the
+unsigned four byte offset. Therefore, the maximum supported offset into
+one of these tables is 0x7ffffffff.
+.Lp
+Table identifier zero, always refers to the
+.Sy 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
+.Nm
+container.
+.Ss Type Encoding
+Every
+.Nm
+type begins with metadata encoded into a
+.Sy uint16_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
+five bits for the kind, one bit for indicating whether or not it is a
+root type, and 10 bits for the variable length. 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:
+.Bd -literal -offset indent
+#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
+.Ed
+.Lp
+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
+.Sy 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
+.Sy root
+type. If a type is a
+.Sy root
+type, then it will have bit 10 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_INFO_KIND(info) (((info) & 0xf800) >> 11)
+#define CTF_INFO_ISROOT(info) (((info) & 0x0400) >> 10)
+#define CTF_INFO_VLEN(info) (((info) & CTF_MAX_VLEN))
+
+#define CTF_TYPE_INFO(kind, isroot, vlen) \\
+ (((kind) << 11) | (((isroot) ? 1 : 0) << 10) | ((vlen) & CTF_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 used the type
+identifiers, if the wrong parent is used then the wrong type will be
+encountered.
+.Lp
+Each label is encoded in the file format using the following eight byte
+structure:
+.Bd -literal
+typedef struct ctf_lblent {
+ uint_t ctl_label; /* ref to name of label */
+ uint_t ctl_typeidx; /* last type associated with this label */
+} ctf_lblent_t;
+.Ed
+.Lp
+Each label has two different components, a name and a type identifier.
+The name is encoded in the
+.Em ctl_label
+member which is in the format defined in the section
+.Sx String Identifiers .
+Generally, the names of all labels are found in the internal string
+section.
+.Lp
+The type identifier encoded in the member
+.Em 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
+.Nm
+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 parents.
+.Lp
+It is also possible, though rather uncommon, for a
+.Nm
+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
+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
+.Nm
+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:
+.Lp
+.Bl -bullet -offset indent -compact
+.It
+The symbol type is not
+.Sy STT_OBJECT
+.It
+The symbol's section index is
+.Sy SHN_UNDEF
+.It
+The symbol's name offset is zero
+.It
+The symbol's section index is
+.Sy SHN_ABS
+and the value of the symbol is zero.
+.It
+The symbol's name is
+.Li _START_
+or
+.Li _END_ .
+These are skipped because they are used for scoping local symbols in
+ELF.
+.El
+.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,
+ * 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.
+ */
+static int
+walk_symbols(uint16_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 %d\n", i, *objtoff);
+ }
+
+ return (0);
+}
+.Ed
+.Ss The Function Section
+The function section of the
+.Nm
+file encodes the types of both the function's arguments and the function's
+return type. Similar to
+.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 .
+For functions which have no type information available, they are encoded as
+.Li CTF_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) .
+.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
+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
+Like
+.Sx 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:
+.Lp
+.Bl -bullet -offset indent -compact
+.It
+The symbol type is not
+.Sy STT_FUNCTION
+.It
+The symbol's section index is
+.Sy SHN_UNDEF
+.It
+The symbol's name offset is zero
+.It
+The symbol's name is
+.Li _START_
+or
+.Li _END_ .
+These are skipped because they are used for scoping local symbols in
+ELF.
+.El
+.Ss The Type Section
+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_LSIZE_SENT 0xffff /* sentinel for ctt_size */
+#define CTF_MAX_LSIZE UINT64_MAX
+
+typedef struct ctf_stype {
+ uint_t ctt_name; /* reference to name in string table */
+ ushort_t ctt_info; /* encoded kind, variant length */
+ union {
+ ushort_t _size; /* size of entire type in bytes */
+ ushort_t _type; /* reference to another type */
+ } _u;
+} ctf_stype_t;
+
+typedef struct ctf_type {
+ uint_t ctt_name; /* reference to name in string table */
+ ushort_t ctt_info; /* encoded kind, variant length */
+ union {
+ ushort_t _size; /* always CTF_LSIZE_SENT */
+ ushort_t _type; /* do not use */
+ } _u;
+ uint_t ctt_lsizehi; /* high 32 bits of type size in bytes */
+ uint_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 ushort_t
+to store the number of bytes. If the number of bytes in a structure would exceed
+0xfffe, then the alternate form, the
+.Sy ctf_type_t ,
+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
+(0xffff). In general, when going through the type section, consumers use the
+.Sy ctf_type_t
+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
+.Sy ctf_stype_t
+or
+.Sy ctf_type_t .
+Not all kinds of types use
+.Sy ctt_size .
+Those which do not, will always use the
+.Sy ctf_stype_t
+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 types kind tells us how to interpret the remaining data in the
+.Sy ctf_type_t
+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 four byte
+.Sy uint_t
+which describes their encoding. All integers must be encoded with a variable
+length of zero. The
+.Em ctt_size
+member describes the length of the integer in bytes. In general, integer sizes
+will be rounded up to the closest power of two.
+.Lp
+The integer encoding contains three different pieces of information:
+.Bl -bullet -offset indent -compact
+.It
+The encoding of the integer
+.It
+The offset in
+.Sy bits
+of the type
+.It
+The size in
+.Sy bits
+of the type
+.El
+.Pp
+This encoding can be expressed through the following macros:
+.Bd -literal -offset indent
+#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))
+.Ed
+.Pp
+The following flags are defined for the encoding at this time:
+.Bd -literal -offset indent
+#define CTF_INT_SIGNED 0x01
+#define CTF_INT_CHAR 0x02
+#define CTF_INT_BOOL 0x04
+#define CTF_INT_VARARGS 0x08
+.Ed
+.Lp
+By default, an integer is considered to be unsigned, unless it has the
+.Sy CTF_INT_SIGNED
+flag set. If the flag
+.Sy CTF_INT_CHAR
+is set, that indicates that the integer is of a type that stores character
+data, for example the intrinsic C type
+.Sy char
+would have the
+.Sy CTF_INT_CHAR
+flag set. If the flag
+.Sy CTF_INT_BOOL
+is set, that indicates that the integer represents a boolean type. For example,
+the intrinsic C type
+.Sy _Bool
+would have the
+.Sy CTF_INT_BOOL
+flag set. Finally, the flag
+.Sy CTF_INT_VARARGS
+indicates that the integer is used as part of a variable number of arguments.
+This encoding is rather uncommon.
+.Ss Encoding of Floats
+Floats, which are of type
+.Sy CTF_K_FLOAT ,
+are similar to their integer counterparts. They have no variable length
+arguments and are followed by a four byte encoding which describes the kind of
+float that exists. The
+.Em ctt_size
+member is the size, in bytes, of the float. The float encoding has three
+different pieces of information inside of it:
+.Lp
+.Bl -bullet -offset indent -compact
+.It
+The specific kind of float that exists
+.It
+The offset in
+.Sy bits
+of the float
+.It
+The size in
+.Sy bits
+of the float
+.El
+.Lp
+This encoding can be expressed through the following macros:
+.Bd -literal -offset indent
+#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))
+.Ed
+.Lp
+Where as the encoding for integers was 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:
+.Bd -literal -offset indent
+#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 */
+.Ed
+.Ss Encoding of Arrays
+Arrays, which are of type
+.Sy CTF_K_ARRAY ,
+have no variable length arguments. 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 {
+ ushort_t cta_contents; /* reference to type of array contents */
+ ushort_t cta_index; /* reference to type of array index */
+ uint_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
+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
+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.
+.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 every member of a structure follows 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, all members are encoded using
+the same structure. The structure for members is as follows:
+.Bd -literal
+typedef struct ctf_member {
+ uint_t ctm_name; /* reference to name in string table */
+ ushort_t ctm_type; /* reference to type of member */
+ ushort_t ctm_offset; /* offset of this member in bits */
+} ctf_member_t;
+
+typedef struct ctf_lmember {
+ uint_t ctlm_name; /* reference to name in string table */
+ ushort_t ctlm_type; /* reference to type of member */
+ ushort_t ctlm_pad; /* padding */
+ uint_t ctlm_offsethi; /* high 32 bits of member offset in bits */
+ uint_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 section
+.Sx String Identifiers .
+The members
+.Sy ctm_type
+and
+.Sy ctlm_type
+both refer to the type of the member. They are encoded as per the section
+.Sx Type Identifiers .
+.Lp
+The last piece of information that is present is the offset which describes the
+offset in memory that the member begins at. For unions, this value will always
+be zero because the start of unions in memory is always zero. For structures,
+this is the offset in
+.Sy bits
+that the member begins at. 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 normal structure,
+.Sy ctf_member_t ,
+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,
+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
+to the left by thirty two and then doing a binary or of
+.Em ctlm_offsetlo .
+.Ss Encoding of Enumerations
+Enumerations, noted by the type
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-src-all
mailing list