dtrace.h

Sun Solaris 10 中的 DTrace 组件的源代码。请参看: http://www.sun.com/software/solaris/observability.jsp

#define	DIF_TYPE_CTF		0	/* type is a CTF type */
#define	DIF_TYPE_STRING		1	/* type is a D string */

#define	DIF_TF_BYREF		0x1	/* type is passed by reference */

/*
 * A DTrace Intermediate Format variable record is used to describe each of the
 * variables referenced by a given DIF object.  It contains an integer variable
 * identifier along with variable scope and properties, as shown below.  The
 * size of this structure must be sizeof (int) aligned.
 */
typedef struct dtrace_difv {
	uint32_t dtdv_name;		/* variable name index in dtdo_strtab */
	uint32_t dtdv_id;		/* variable reference identifier */
	uint8_t dtdv_kind;		/* variable kind (see below) */
	uint8_t dtdv_scope;		/* variable scope (see below) */
	uint16_t dtdv_flags;		/* variable flags (see below) */
	dtrace_diftype_t dtdv_type;	/* variable type (see above) */
} dtrace_difv_t;

#define	DIFV_KIND_ARRAY		0	/* variable is an array of quantities */
#define	DIFV_KIND_SCALAR	1	/* variable is a scalar quantity */

#define	DIFV_SCOPE_GLOBAL	0	/* variable has global scope */
#define	DIFV_SCOPE_THREAD	1	/* variable has thread scope */
#define	DIFV_SCOPE_LOCAL	2	/* variable has local scope */

#define	DIFV_F_REF		0x1	/* variable is referenced by DIFO */
#define	DIFV_F_MOD		0x2	/* variable is written by DIFO */

/*
 * DTrace Actions
 *
 * The upper byte determines the class of the action; the low bytes determines
 * the specific action within that class.  The classes of actions are as
 * follows:
 *
 *   [ no class ]                  <= May record process- or kernel-related data
 *   DTRACEACT_PROC                <= Only records process-related data
 *   DTRACEACT_PROC_DESTRUCTIVE    <= Potentially destructive to processes
 *   DTRACEACT_KERNEL              <= Only records kernel-related data
 *   DTRACEACT_KERNEL_DESTRUCTIVE  <= Potentially destructive to the kernel
 *   DTRACEACT_SPECULATIVE         <= Speculation-related action
 *   DTRACEACT_AGGREGATION         <= Aggregating action
 */
#define	DTRACEACT_NONE			0	/* no action */
#define	DTRACEACT_DIFEXPR		1	/* action is DIF expression */
#define	DTRACEACT_EXIT			2	/* exit() action */
#define	DTRACEACT_PRINTF		3	/* printf() action */
#define	DTRACEACT_PRINTA		4	/* printa() action */
#define	DTRACEACT_LIBACT		5	/* library-controlled action */

#define	DTRACEACT_PROC			0x0100
#define	DTRACEACT_USTACK		(DTRACEACT_PROC + 1)
#define	DTRACEACT_JSTACK		(DTRACEACT_PROC + 2)

#define	DTRACEACT_PROC_DESTRUCTIVE	0x0200
#define	DTRACEACT_STOP			(DTRACEACT_PROC_DESTRUCTIVE + 1)
#define	DTRACEACT_RAISE			(DTRACEACT_PROC_DESTRUCTIVE + 2)
#define	DTRACEACT_SYSTEM		(DTRACEACT_PROC_DESTRUCTIVE + 3)

#define	DTRACEACT_PROC_CONTROL		0x0300

#define	DTRACEACT_KERNEL		0x0400
#define	DTRACEACT_STACK			(DTRACEACT_KERNEL + 1)

#define	DTRACEACT_KERNEL_DESTRUCTIVE	0x0500
#define	DTRACEACT_BREAKPOINT		(DTRACEACT_KERNEL_DESTRUCTIVE + 1)
#define	DTRACEACT_PANIC			(DTRACEACT_KERNEL_DESTRUCTIVE + 2)
#define	DTRACEACT_CHILL			(DTRACEACT_KERNEL_DESTRUCTIVE + 3)

#define	DTRACEACT_SPECULATIVE		0x0600
#define	DTRACEACT_SPECULATE		(DTRACEACT_SPECULATIVE + 1)
#define	DTRACEACT_COMMIT		(DTRACEACT_SPECULATIVE + 2)
#define	DTRACEACT_DISCARD		(DTRACEACT_SPECULATIVE + 3)

#define	DTRACEACT_CLASS(x)		((x) & 0xff00)

#define	DTRACEACT_ISDESTRUCTIVE(x)	\
	(DTRACEACT_CLASS(x) == DTRACEACT_PROC_DESTRUCTIVE || \
	DTRACEACT_CLASS(x) == DTRACEACT_KERNEL_DESTRUCTIVE)

#define	DTRACEACT_ISSPECULATIVE(x)	\
	(DTRACEACT_CLASS(x) == DTRACEACT_SPECULATIVE)

#define	DTRACEACT_ISPRINTFLIKE(x)	\
	((x) == DTRACEACT_PRINTF || (x) == DTRACEACT_PRINTA || \
	(x) == DTRACEACT_SYSTEM)

/*
 * DTrace Aggregating Actions
 *
 * These are functions f(x) for which the following is true:
 *
 *    f(f(x_0) U f(x_1) U ... U f(x_n)) = f(x_0 U x_1 U ... U x_n)
 *
 * where x_n is a set of arbitrary data.  Aggregating actions are in their own
 * DTrace action class, DTTRACEACT_AGGREGATION.  The macros provided here allow
 * for easier processing of the aggregation argument and data payload for a few
 * aggregating actions (notably:  quantize(), lquantize(), and ustack()).
 */
#define	DTRACEACT_AGGREGATION		0x0700
#define	DTRACEAGG_COUNT			(DTRACEACT_AGGREGATION + 1)
#define	DTRACEAGG_MIN			(DTRACEACT_AGGREGATION + 2)
#define	DTRACEAGG_MAX			(DTRACEACT_AGGREGATION + 3)
#define	DTRACEAGG_AVG			(DTRACEACT_AGGREGATION + 4)
#define	DTRACEAGG_SUM			(DTRACEACT_AGGREGATION + 5)
#define	DTRACEAGG_STDDEV		(DTRACEACT_AGGREGATION + 6)
#define	DTRACEAGG_QUANTIZE		(DTRACEACT_AGGREGATION + 7)
#define	DTRACEAGG_LQUANTIZE		(DTRACEACT_AGGREGATION + 8)

#define	DTRACEACT_ISAGG(x)		\
	(DTRACEACT_CLASS(x) == DTRACEACT_AGGREGATION)

#define	DTRACE_QUANTIZE_NBUCKETS	\
	(((sizeof (uint64_t) * NBBY) - 1) * 2 + 1)

#define	DTRACE_QUANTIZE_ZEROBUCKET	((sizeof (uint64_t) * NBBY) - 1)

#define	DTRACE_QUANTIZE_BUCKETVAL(buck)					\
	(int64_t)((buck) < DTRACE_QUANTIZE_ZEROBUCKET ?			\
	-(1LL << (DTRACE_QUANTIZE_ZEROBUCKET - 1 - (buck))) :		\
	(buck) == DTRACE_QUANTIZE_ZEROBUCKET ? 0 :			\
	1LL << ((buck) - DTRACE_QUANTIZE_ZEROBUCKET - 1))

#define	DTRACE_LQUANTIZE_STEPSHIFT		48
#define	DTRACE_LQUANTIZE_STEPMASK		((uint64_t)UINT16_MAX << 48)
#define	DTRACE_LQUANTIZE_LEVELSHIFT		32
#define	DTRACE_LQUANTIZE_LEVELMASK		((uint64_t)UINT16_MAX << 32)
#define	DTRACE_LQUANTIZE_BASESHIFT		0
#define	DTRACE_LQUANTIZE_BASEMASK		UINT32_MAX

#define	DTRACE_LQUANTIZE_STEP(x)		\
	(uint16_t)(((x) & DTRACE_LQUANTIZE_STEPMASK) >> \
	DTRACE_LQUANTIZE_STEPSHIFT)

#define	DTRACE_LQUANTIZE_LEVELS(x)		\
	(uint16_t)(((x) & DTRACE_LQUANTIZE_LEVELMASK) >> \
	DTRACE_LQUANTIZE_LEVELSHIFT)

#define	DTRACE_LQUANTIZE_BASE(x)		\
	(int32_t)(((x) & DTRACE_LQUANTIZE_BASEMASK) >> \
	DTRACE_LQUANTIZE_BASESHIFT)

#define	DTRACE_USTACK_NFRAMES(x)	(uint32_t)((x) & UINT32_MAX)
#define	DTRACE_USTACK_STRSIZE(x)	(uint32_t)((x) >> 32)
#define	DTRACE_USTACK_ARG(x, y)		\
	((((uint64_t)(y)) << 32) | ((x) & UINT32_MAX))

#ifndef _LP64
#ifndef _LITTLE_ENDIAN
#define	DTRACE_PTR(type, name)	uint32_t name##pad; type *name
#else
#define	DTRACE_PTR(type, name)	type *name; uint32_t name##pad
#endif
#else
#define	DTRACE_PTR(type, name)	type *name
#endif

/*
 * DTrace Object Format (DOF)
 *
 * DTrace programs can be persistently encoded in the DOF format so that they
 * may be embedded in other programs (for example, in an ELF file) or in the
 * dtrace driver configuration file for use in anonymous tracing.  The DOF
 * format is versioned and extensible so that it can be revised and so that
 * internal data structures can be modified or extended compatibly.  All DOF
 * structures use fixed-size types, so the 32-bit and 64-bit representations
 * are identical and consumers can use either data model transparently.
 *
 * The file layout is structured as follows:
 *
 * +---------------+-------------------+----- ... ----+---- ... ------+
 * |   dof_hdr_t   |  dof_sec_t[ ... ] |   loadable   | non-loadable  |
 * | (file header) | (section headers) | section data | section data  |
 * +---------------+-------------------+----- ... ----+---- ... ------+
 * |<------------ dof_hdr.dofh_loadsz --------------->|               |
 * |<------------ dof_hdr.dofh_filesz ------------------------------->|
 *
 * The file header stores meta-data including a magic number, data model for
 * the instrumentation, data encoding, and properties of the DIF code within.
 * The header describes its own size and the size of the section headers.  By
 * convention, an array of section headers follows the file header, and then
 * the data for all loadable sections and unloadable sections.  This permits
 * consumer code to easily download the headers and all loadable data into the
 * DTrace driver in one contiguous chunk, omitting other extraneous sections.
 *
 * The section headers describe the size, offset, alignment, and section type
 * for each section.  Sections are described using a set of #defines that tell
 * the consumer what kind of data is expected.  Sections can contain links to
 * other sections by storing a dof_secidx_t, an index into the section header
 * array, inside of the section data structures.  The section header includes
 * an entry size so that sections with data arrays can grow their structures.
 *
 * The DOF data itself can contain many snippets of DIF (i.e. >1 DIFOs), which
 * are represented themselves as a collection of related DOF sections.  This
 * permits us to change the set of sections associated with a DIFO over time,
 * and also permits us to encode DIFOs that contain different sets of sections.
 * When a DOF section wants to refer to a DIFO, it stores the dof_secidx_t of a
 * section of type DOF_SECT_DIFOHDR.  This section's data is then an array of
 * dof_secidx_t's which in turn denote the sections associated with this DIFO.
 *
 * This loose coupling of the file structure (header and sections) to the
 * structure of the DTrace program itself (ECB descriptions, action
 * descriptions, and DIFOs) permits activities such as relocation processing
 * to occur in a single pass without having to understand D program structure.
 *
 * Finally, strings are always stored in ELF-style string tables along with a
 * string table section index and string table offset.  Therefore strings in
 * DOF are always arbitrary-length and not bound to the current implementation.
 */

#define	DOF_ID_SIZE	16	/* total size of dofh_ident[] in bytes */

typedef struct dof_hdr {
	uint8_t dofh_ident[DOF_ID_SIZE]; /* identification bytes (see below) */
	uint32_t dofh_flags;		/* file attribute flags (if any) */
	uint32_t dofh_hdrsize;		/* size of file header in bytes */
	uint32_t dofh_secsize;		/* size of section header in bytes */
	uint32_t dofh_secnum;		/* number of section headers */
	uint64_t dofh_secoff;		/* file offset of section headers */
	uint64_t dofh_loadsz;		/* file size of loadable portion */
	uint64_t dofh_filesz;		/* file size of entire DOF file */
	uint64_t dofh_pad;		/* reserved for future use */
} dof_hdr_t;

#define	DOF_ID_MAG0	0	/* first byte of magic number */
#define	DOF_ID_MAG1	1	/* second byte of magic number */
#define	DOF_ID_MAG2	2	/* third byte of magic number */
#define	DOF_ID_MAG3	3	/* fourth byte of magic number */
#define	DOF_ID_MODEL	4	/* DOF data model (see below) */
#define	DOF_ID_ENCODING	5	/* DOF data encoding (see below) */
#define	DOF_ID_VERSION	6	/* DOF file format major version (see below) */
#define	DOF_ID_DIFVERS	7	/* DIF instruction set version */
#define	DOF_ID_DIFIREG	8	/* DIF integer registers used by compiler */
#define	DOF_ID_DIFTREG	9	/* DIF tuple registers used by compiler */
#define	DOF_ID_PAD	10	/* start of padding bytes (all zeroes) */

#define	DOF_MAG_MAG0	0x7F	/* DOF_ID_MAG[0-3] */
#define	DOF_MAG_MAG1	'D'
#define	DOF_MAG_MAG2	'O'
#define	DOF_MAG_MAG3	'F'

#define	DOF_MAG_STRING	"\177DOF"
#define	DOF_MAG_STRLEN	4

#define	DOF_MODEL_NONE	0	/* DOF_ID_MODEL */
#define	DOF_MODEL_ILP32	1
#define	DOF_MODEL_LP64	2

#ifdef _LP64
#define	DOF_MODEL_NATIVE	DOF_MODEL_LP64
#else
#define	DOF_MODEL_NATIVE	DOF_MODEL_ILP32
#endif

#define	DOF_ENCODE_NONE	0	/* DOF_ID_ENCODING */
#define	DOF_ENCODE_LSB	1
#define	DOF_ENCODE_MSB	2

#ifdef _BIG_ENDIAN
#define	DOF_ENCODE_NATIVE	DOF_ENCODE_MSB
#else
#define	DOF_ENCODE_NATIVE	DOF_ENCODE_LSB
#endif

#define	DOF_VERSION_1	1	/* DOF_ID_VERSION */
#define	DOF_VERSION	DOF_VERSION_1

#define	DOF_FL_VALID	0	/* mask of all valid dofh_flags bits */

typedef uint32_t dof_secidx_t;	/* section header table index type */
typedef uint32_t dof_stridx_t;	/* string table index type */

#define	DOF_SECIDX_NONE	(-1U)	/* null value for section indices */
#define	DOF_STRIDX_NONE	(-1U)	/* null value for string indices */

typedef struct dof_sec {
	uint32_t dofs_type;	/* section type (see below) */
	uint32_t dofs_align;	/* section data memory alignment */
	uint32_t dofs_flags;	/* section flags (if any) */
	uint32_t dofs_entsize;	/* size of section entry (if table) */
	uint64_t dofs_offset;	/* offset of section data within file */
	uint64_t dofs_size;	/* size of section data in bytes */
} dof_sec_t;

#define	DOF_SECT_NONE		0	/* null section */
#define	DOF_SECT_COMMENTS	1	/* compiler comments */
#define	DOF_SECT_SOURCE		2	/* D program source code */
#define	DOF_SECT_ECBDESC	3	/* dof_ecbdesc_t */
#define	DOF_SECT_PROBEDESC	4	/* dof_probedesc_t */
#define	DOF_SECT_ACTDESC	5	/* dof_actdesc_t array */
#define	DOF_SECT_DIFOHDR	6	/* dof_difohdr_t (variable length) */
#define	DOF_SECT_DIF		7	/* uint32_t array of byte code */
#define	DOF_SECT_STRTAB		8	/* string table */
#define	DOF_SECT_VARTAB		9	/* dtrace_difv_t array */