dtrace.h

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

 * structure.  This describes which CPU user-level is interested in, and
 * where user-level wishes the kernel to snapshot the buffer to (the
 * dtbd_data field).  The kernel uses the same structure to pass back some
 * information regarding the buffer:  the size of data actually copied out, the
 * number of drops, the number of errors, and the offset of the oldest record.
 * If the buffer policy is a "switch" policy, taking a snapshot of the
 * principal buffer has the additional effect of switching the active and
 * inactive buffers.  Taking a snapshot of the aggregation buffer _always_ has
 * the additional effect of switching the active and inactive buffers.
 */
typedef struct dtrace_bufdesc {
	uint64_t dtbd_size;			/* size of buffer */
	uint32_t dtbd_cpu;			/* CPU or DTRACE_CPUALL */
	uint32_t dtbd_errors;			/* number of errors */
	uint64_t dtbd_drops;			/* number of drops */
	DTRACE_PTR(char, dtbd_data);		/* data */
	uint64_t dtbd_oldest;			/* offset of oldest record */
} dtrace_bufdesc_t;

/*
 * DTrace Status
 *
 * The status of DTrace is relayed via the dtrace_status structure.  This
 * structure contains members to count drops other than the capacity drops
 * available via the buffer interface (see above).  This consists of dynamic
 * drops (including capacity dynamic drops, rinsing drops and dirty drops), and
 * speculative drops (including capacity speculative drops, drops due to busy
 * speculative buffers and drops due to unavailable speculative buffers).
 * Additionally, the status structure contains a field to indicate the number
 * of "fill"-policy buffers have been filled and a boolean field to indicate
 * that exit() has been called.  If the dtst_exiting field is non-zero, no
 * further data will be generated until tracing is stopped (at which time any
 * enablings of the END action will be processed); if user-level sees that
 * this field is non-zero, tracing should be stopped as soon as possible.
 */
typedef struct dtrace_status {
	uint64_t dtst_dyndrops;			/* dynamic drops */
	uint64_t dtst_dyndrops_rinsing;		/* dyn drops due to rinsing */
	uint64_t dtst_dyndrops_dirty;		/* dyn drops due to dirty */
	uint64_t dtst_specdrops;		/* speculative drops */
	uint64_t dtst_specdrops_busy;		/* spec drops due to busy */
	uint64_t dtst_specdrops_unavail;	/* spec drops due to unavail */
	uint64_t dtst_errors;			/* total errors */
	uint64_t dtst_filled;			/* number of filled bufs */
	char dtst_killed;			/* non-zero if killed */
	char dtst_exiting;			/* non-zero if exit() called */
	char dtst_pad[6];			/* pad out to 64-bit align */
} dtrace_status_t;

/*
 * DTrace Configuration
 *
 * User-level may need to understand some elements of the kernel DTrace
 * configuration in order to generate correct DIF.  This information is
 * conveyed via the dtrace_conf structure.
 */
typedef struct dtrace_conf {
	uint_t dtc_difversion;			/* supported DIF version */
	uint_t dtc_difintregs;			/* # of DIF integer registers */
	uint_t dtc_diftupregs;			/* # of DIF tuple registers */
	uint_t dtc_ctfmodel;			/* CTF data model */
	uint_t dtc_pad[8];			/* reserved for future use */
} dtrace_conf_t;

/*
 * DTrace Faults
 *
 * These constants are replicated in unistd.d so that users' ERROR probes
 * can decode the error condition using thse symbolic labels.
 */
#define	DTRACEFLT_UNKNOWN		0	/* Unknown fault */
#define	DTRACEFLT_BADADDR		1	/* Bad address */
#define	DTRACEFLT_BADALIGN		2	/* Bad alignment */
#define	DTRACEFLT_ILLOP			3	/* Illegal operation */
#define	DTRACEFLT_DIVZERO		4	/* Divide-by-zero */
#define	DTRACEFLT_NOSCRATCH		5	/* Out of scratch space */
#define	DTRACEFLT_KPRIV			6	/* Illegal kernel access */
#define	DTRACEFLT_UPRIV			7	/* Illegal user access */
#define	DTRACEFLT_TUPOFLOW		8	/* Tuple stack overflow */

/*
 * DTrace Argument Types
 *
 * Because it would waste both space and time, argument types do not reside
 * with the probe.  In order to determine argument types for args[X]
 * variables, the D compiler queries for argument types on a probe-by-probe
 * basis.  (This optimizes for the common case that arguments are either not
 * used or used in an untyped fashion.)  Typed arguments are specified with a
 * string of the type name in the dtragd_native member of the argument
 * description structure.  Typed arguments may be further translated to types
 * of greater stability; the provider indicates such a translated argument by
 * filling in the dtargd_xlate member with the string of the translated type.
 * Finally, the provider may indicate which argument value a given argument
 * maps to by setting the dtargd_mapping member -- allowing a single argument
 * to map to multiple args[X] variables.
 */
typedef struct dtrace_argdesc {
	dtrace_id_t dtargd_id;			/* probe identifier */
	int dtargd_ndx;				/* arg number (-1 iff none) */
	int dtargd_mapping;			/* value mapping */
	char dtargd_native[DTRACE_ARGTYPELEN];	/* native type name */
	char dtargd_xlate[DTRACE_ARGTYPELEN];	/* translated type name */
} dtrace_argdesc_t;

/*
 * DTrace Stability Attributes
 *
 * Each DTrace provider advertises the name and data stability of each of its
 * probe description components, as well as its architectural dependencies.
 * The D compiler can query the provider attributes (dtrace_pattr_t below) in
 * order to compute the properties of an input program and report them.
 */
typedef uint8_t dtrace_stability_t;	/* stability code (see attributes(5)) */
typedef uint8_t dtrace_class_t;		/* architectural dependency class */

#define	DTRACE_STABILITY_INTERNAL	0	/* private to DTrace itself */
#define	DTRACE_STABILITY_PRIVATE	1	/* private to Sun (see docs) */
#define	DTRACE_STABILITY_OBSOLETE	2	/* scheduled for removal */
#define	DTRACE_STABILITY_EXTERNAL	3	/* not controlled by Sun */
#define	DTRACE_STABILITY_UNSTABLE	4	/* new or rapidly changing */
#define	DTRACE_STABILITY_EVOLVING	5	/* less rapidly changing */
#define	DTRACE_STABILITY_STABLE		6	/* mature interface from Sun */
#define	DTRACE_STABILITY_STANDARD	7	/* industry standard */
#define	DTRACE_STABILITY_MAX		7	/* maximum valid stability */

#define	DTRACE_CLASS_UNKNOWN	0	/* unknown architectural dependency */
#define	DTRACE_CLASS_CPU	1	/* CPU-module-specific */
#define	DTRACE_CLASS_PLATFORM	2	/* platform-specific (uname -i) */
#define	DTRACE_CLASS_GROUP	3	/* hardware-group-specific (uname -m) */
#define	DTRACE_CLASS_ISA	4	/* ISA-specific (uname -p) */
#define	DTRACE_CLASS_COMMON	5	/* common to all systems */
#define	DTRACE_CLASS_MAX	5	/* maximum valid class */

#define	DTRACE_PRIV_NONE	0x0000
#define	DTRACE_PRIV_KERNEL	0x0001
#define	DTRACE_PRIV_USER	0x0002
#define	DTRACE_PRIV_PROC	0x0004
#define	DTRACE_PRIV_OWNER	0x0008

#define	DTRACE_PRIV_ALL	\
	(DTRACE_PRIV_KERNEL | DTRACE_PRIV_USER | \
	DTRACE_PRIV_PROC | DTRACE_PRIV_OWNER)

typedef struct dtrace_ppriv {
	uint32_t dtpp_flags;			/* privilege flags */
	uid_t dtpp_uid;				/* user ID */
} dtrace_ppriv_t;

typedef struct dtrace_attribute {
	dtrace_stability_t dtat_name;		/* entity name stability */
	dtrace_stability_t dtat_data;		/* entity data stability */
	dtrace_class_t dtat_class;		/* entity data dependency */
} dtrace_attribute_t;

typedef struct dtrace_pattr {
	dtrace_attribute_t dtpa_provider;	/* provider attributes */
	dtrace_attribute_t dtpa_mod;		/* module attributes */
	dtrace_attribute_t dtpa_func;		/* function attributes */
	dtrace_attribute_t dtpa_name;		/* name attributes */
	dtrace_attribute_t dtpa_args;		/* args[] attributes */
} dtrace_pattr_t;

typedef struct dtrace_providerdesc {
	char dtvd_name[DTRACE_PROVNAMELEN];	/* provider name */
	dtrace_pattr_t dtvd_attr;		/* stability attributes */
	dtrace_ppriv_t dtvd_priv;		/* privileges required */
} dtrace_providerdesc_t;

/*
 * DTrace Pseudodevice Interface
 *
 * DTrace is controlled through ioctl(2)'s to the in-kernel dtrace:dtrace
 * pseudodevice driver.  These ioctls comprise the user-kernel interface to
 * DTrace.
 */
#define	DTRACEIOC		(('d' << 24) | ('t' << 16) | ('r' << 8))
#define	DTRACEIOC_PROVIDER	(DTRACEIOC | 1)		/* provider query */
#define	DTRACEIOC_PROBES	(DTRACEIOC | 2)		/* probe query */
#define	DTRACEIOC_BUFSNAP	(DTRACEIOC | 4)		/* snapshot buffer */
#define	DTRACEIOC_PROBEMATCH	(DTRACEIOC | 5)		/* match probes */
#define	DTRACEIOC_ENABLE	(DTRACEIOC | 6)		/* enable probes */
#define	DTRACEIOC_AGGSNAP	(DTRACEIOC | 7)		/* snapshot agg. */
#define	DTRACEIOC_EPROBE	(DTRACEIOC | 8)		/* get eprobe desc. */
#define	DTRACEIOC_PROBEARG	(DTRACEIOC | 9)		/* get probe arg */
#define	DTRACEIOC_CONF		(DTRACEIOC | 10)	/* get config. */
#define	DTRACEIOC_STATUS	(DTRACEIOC | 11)	/* get status */
#define	DTRACEIOC_GO		(DTRACEIOC | 12)	/* start tracing */
#define	DTRACEIOC_STOP		(DTRACEIOC | 13)	/* stop tracing */
#define	DTRACEIOC_AGGDESC	(DTRACEIOC | 15)	/* get agg. desc. */
#define	DTRACEIOC_FORMAT	(DTRACEIOC | 16)	/* get format str */
#define	DTRACEIOC_DOFGET	(DTRACEIOC | 17)	/* get DOF */

/*
 * DTrace Helpers
 *
 * In general, DTrace establishes probes in processes and takes actions on
 * processes without knowing their specific user-level structures.  Instead of
 * existing in the framework, process-specific knowledge is contained by the
 * enabling D program -- which can apply process-specific knowledge by making
 * appropriate use of DTrace primitives like copyin() and copyinstr() to
 * operate on user-level data.  However, there may exist some specific probes
 * of particular semantic relevance that the application developer may wish to
 * explicitly export.  For example, an application may wish to export a probe
 * at the point that it begins and ends certain well-defined transactions.  In
 * addition to providing probes, programs may wish to offer assistance for
 * certain actions.  For example, in highly dynamic environments (e.g., Java),
 * it may be difficult to obtain a stack trace in terms of meaningful symbol
 * names (the translation from instruction addresses to corresponding symbol
 * names may only be possible in situ); these environments may wish to define
 * a series of actions to be applied in situ to obtain a meaningful stack
 * trace.
 *
 * These two mechanisms -- user-level statically defined tracing and assisting
 * DTrace actions -- are provided via DTrace _helpers_.  Helpers are specified
 * via DOF, but unlike enabling DOF, helper DOF may contain definitions of
 * providers, probes and their arguments.  If a helper wishes to provide
 * action assistance, probe descriptions and corresponding DIF actions may be
 * specified in the helper DOF.  For such helper actions, however, the probe
 * description describes the specific helper:  all DTrace helpers have the
 * provider name "dtrace" and the module name "helper", and the name of the
 * helper is contained in the function name (for example, the ustack() helper
 * is named "ustack").  Any helper-specific name may be contained in the name
 * (for example, if a helper were to have a constructor, it might be named
 * "dtrace:helper:<helper>:init").  Helper actions are only called when the
 * action that they are helping is taken.  Helper actions may only return DIF
 * expressions, and may only call the following subroutines:
 *
 *    alloca()      <= Allocates memory out of the consumer's scratch space
 *    bcopy()       <= Copies memory to scratch space
 *    copyin()      <= Copies memory from user-level into consumer's scratch
 *    copyinto()    <= Copies memory into a specific location in scratch
 *    copyinstr()   <= Copies a string into a specific location in scratch
 *
 * Helper actions may only access the following built-in variables:
 *
 *    curthread     <= Current kthread_t pointer
 *    tid           <= Current thread identifier
 *    pid           <= Current process identifier
 *    execname      <= Current executable name
 *
 * Helper actions may not manipulate or allocate dynamic variables, but they
 * may have clause-local and statically-allocated global variables.  The
 * helper action variable state is specific to the helper action -- variables
 * used by the helper action may not be accessed outside of the helper
 * action, and the helper action may not access variables that like outside
 * of it.  Helper actions may not load from kernel memory at-large; they are
 * restricting to loading current user state (via copyin() and variants) and
 * scratch space.  As with probe enablings, helper actions are executed in
 * program order.  The result of the helper action is the result of the last
 * executing helper expression.
 *
 * Helpers -- composed of either providers/probes or probes/actions (or both)
 * -- are added by opening the "helper" minor node, and issuing an ioctl(2)
 * (DTRACEHIOC_ADDDOF) that specifies the dof_helper_t structure. This
 * encapsulates the name and base address of the user-level library or
 * executable publishing the helpers and probes as well as the DOF that
 * contains the definitions of those helpers and probes.
 *
 * The DTRACEHIOC_ADD and DTRACEHIOC_REMOVE are left in place for legacy
 * helpers and should no longer be used.  No other ioctls are valid on the
 * helper minor node.
 */
#define	DTRACEHIOC		(('d' << 24) | ('t' << 16) | ('h' << 8))
#define	DTRACEHIOC_ADD		(DTRACEHIOC | 1)	/* add helper */
#define	DTRACEHIOC_REMOVE	(DTRACEHIOC | 2)	/* remove helper */
#define	DTRACEHIOC_ADDDOF	(DTRACEHIOC | 3)	/* add helper DOF */

typedef struct dof_helper {
	char dofhp_mod[DTRACE_MODNAMELEN];	/* executable or library name */
	uint64_t dofhp_addr;			/* base address of object */
	uint64_t dofhp_dof;			/* address of helper DOF */
} dof_helper_t;

#define	DTRACEMNR_DTRACE	"dtrace"	/* node for DTrace ops */
#define	DTRACEMNR_HELPER	"helper"	/* node for helpers */
#define	DTRACEMNRN_DTRACE	0		/* minor for DTrace ops */
#define	DTRACEMNRN_HELPER	1		/* minor for helpers */
#define	DTRACEMNRN_CLONE	2		/* first clone minor */

#ifdef _KERNEL

/*
 * DTrace Provider API
 *
 * The following functions are implemented by the DTrace framework and are
 * used to implement separate in-kernel DTrace providers.  Common functions
 * are provided in uts/common/os/dtrace.c.  ISA-dependent subroutines are
 * defined in uts/<isa>/dtrace/dtrace_asm.s or uts/<isa>/dtrace/dtrace_isa.c.
 *
 * The provider API has two halves:  the API that the providers consume from
 * DTrace, and the API that providers make available to DTrace.
 *
 * 1 Framework-to-Provider API
 *
 * 1.1  Overview
 *
 * The Framework-to-Provider API is represented by the dtrace_pops structure