[src/trunk]: src/external/cddl/osnet/dist/lib/libctf/common Sync with FreeBSD

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6725bf1aa210
branches:  trunk
changeset: 340665:6725bf1aa210
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Sep 24 14:20:18 2015 +0000

description:
Sync with FreeBSD

diffstat:

 external/cddl/osnet/dist/lib/libctf/common/ctf.5      |  1140 +++++++++++++++++
 external/cddl/osnet/dist/lib/libctf/common/ctf_lib.c  |    71 +-
 external/cddl/osnet/dist/lib/libctf/common/ctf_subr.c |     4 +
 3 files changed, 1193 insertions(+), 22 deletions(-)

diffs (truncated from 1340 to 300 lines):

diff -r 4dea61acf877 -r 6725bf1aa210 external/cddl/osnet/dist/lib/libctf/common/ctf.5
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/external/cddl/osnet/dist/lib/libctf/common/ctf.5  Thu Sep 24 14:20:18 2015 +0000
@@ -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 5
+.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