#include <sys/dtrace.h>
sys/dtrace.h DTrace Dynamic Tracing Software: Kernel Interfaces
Note: The contents of this file are private to the implementation of the
Solaris system and DTrace subsystem and are subject to change at any time
without notice. Applications and drivers using these interfaces will fail
to run on future releases. These interfaces should not be used for any
purpose except those expressly outlined in dtrace(7D) and libdtrace(3LIB).
Please refer to the "Solaris Dynamic Tracing Guide" for more information.
535 macros · 70 typedefs · 41 structs · 2 enums
#define _LITTLE_ENDIAN Solaris vs. Darwin
#define NANOSEC 1000000000 #define S_ROUND(x, a) ((x) + (((a) ? (a) : 1) - 1) & ~(((a) ? (a) : 1) - 1)) #define P2ROUNDUP(x, align) (-(-(x) & -(align))) #define P2PHASEUP(x, align, phase) ((phase) - (((phase) - (x)) & -(align))) #define CTF_MODEL_ILP32 1 object data model is ILP32
#define CTF_MODEL_LP64 2 object data model is LP64
typedef uint16_t ushort_t typedef unsigned long ulong_t typedef uint64_t u_longlong_t typedef int processorid_t underlying type unsigned int
typedef uint8_t UUID[16] For modctl use in dtrace.h
In lieu of Solaris <sys/ctf_api.h>
typedef struct ctf_file ctf_file_t typedef uint32_t zoneid_t Solaris proc_t is the struct. Darwin's proc_t is a pointer to it.
#define proc_t struct proc Steer clear of the Darwin typedef for proc_t
DTrace Universal Constants and Typedefs
#define DTRACE_CPUALL -1 all CPUs
#define DTRACE_IDNONE 0 invalid probe identifier
#define DTRACE_EPIDNONE 0 invalid enabled probe identifier
#define DTRACE_AGGIDNONE 0 invalid aggregation identifier
#define DTRACE_AGGVARIDNONE 0 invalid aggregation variable ID
#define DTRACE_CACHEIDNONE 0 invalid predicate cache
#define DTRACE_PROVNONE 0 invalid provider identifier
#define DTRACE_ARGNONE -1 invalid argument index
#define DTRACE_PROVNAMELEN 64 #define DTRACE_MODNAMELEN 64 #define DTRACE_FUNCNAMELEN 128 #define DTRACE_NAMELEN 64 #define DTRACE_ARGTYPELEN 128 typedef uint32_t dtrace_id_t probe identifier
typedef uint32_t dtrace_epid_t enabled probe identifier
typedef uint32_t dtrace_aggid_t aggregation identifier
typedef int64_t dtrace_aggvarid_t aggregation variable identifier
typedef uint16_t dtrace_actkind_t action kind
typedef int64_t dtrace_optval_t option value
typedef uint32_t dtrace_cacheid_t predicate cache identifier
underlying type int
DTRACE_PROBESPEC_NONE -1 DTRACE_PROBESPEC_PROVIDER 0 DTRACE_PROBESPEC_MOD 1 DTRACE_PROBESPEC_FUNC 2 DTRACE_PROBESPEC_NAME 3
DTrace Intermediate Format (DIF)
The following definitions describe the DTrace Intermediate Format (DIF), a
a RISC-like instruction set and program encoding used to represent
predicates and actions that can be bound to DTrace probes. The constants
below defining the number of available registers are suggested minimums; the
compiler should use
DTRACEIOC_CONF to dynamically obtain the number of
registers provided by the current DTrace implementation.
#define DIF_VERSION_1 1 DIF version 1: Solaris 10 Beta
#define DIF_VERSION_2 2 DIF version 2: Solaris 10 FCS
#define DIF_VERSION DIF_VERSION_2 latest DIF instruction set version
#define DIF_DIR_NREGS 8 number of DIF integer registers
#define DIF_DTR_NREGS 8 number of DIF tuple registers
#define DIF_OP_OR 1 or r1, r2, rd
#define DIF_OP_XOR 2 xor r1, r2, rd
#define DIF_OP_AND 3 and r1, r2, rd
#define DIF_OP_SLL 4 sll r1, r2, rd
#define DIF_OP_SRL 5 srl r1, r2, rd
#define DIF_OP_SUB 6 sub r1, r2, rd
#define DIF_OP_ADD 7 add r1, r2, rd
#define DIF_OP_MUL 8 mul r1, r2, rd
#define DIF_OP_SDIV 9 sdiv r1, r2, rd
#define DIF_OP_UDIV 10 udiv r1, r2, rd
#define DIF_OP_SREM 11 srem r1, r2, rd
#define DIF_OP_UREM 12 urem r1, r2, rd
#define DIF_OP_NOT 13 not r1, rd
#define DIF_OP_MOV 14 mov r1, rd
#define DIF_OP_CMP 15 cmp r1, r2
#define DIF_OP_TST 16 tst r1
#define DIF_OP_BA 17 ba label
#define DIF_OP_BE 18 be label
#define DIF_OP_BNE 19 bne label
#define DIF_OP_BG 20 bg label
#define DIF_OP_BGU 21 bgu label
#define DIF_OP_BGE 22 bge label
#define DIF_OP_BGEU 23 bgeu label
#define DIF_OP_BL 24 bl label
#define DIF_OP_BLU 25 blu label
#define DIF_OP_BLE 26 ble label
#define DIF_OP_BLEU 27 bleu label
#define DIF_OP_LDSB 28 ldsb [r1], rd
#define DIF_OP_LDSH 29 ldsh [r1], rd
#define DIF_OP_LDSW 30 ldsw [r1], rd
#define DIF_OP_LDUB 31 ldub [r1], rd
#define DIF_OP_LDUH 32 lduh [r1], rd
#define DIF_OP_LDUW 33 lduw [r1], rd
#define DIF_OP_LDX 34 ldx [r1], rd
#define DIF_OP_RET 35 ret rd
#define DIF_OP_SETX 37 setx intindex, rd
#define DIF_OP_SETS 38 sets strindex, rd
#define DIF_OP_SCMP 39 scmp r1, r2
#define DIF_OP_LDGA 40 ldga var, ri, rd
#define DIF_OP_LDGS 41 ldgs var, rd
#define DIF_OP_STGS 42 stgs var, rs
#define DIF_OP_LDTA 43 ldta var, ri, rd
#define DIF_OP_LDTS 44 ldts var, rd
#define DIF_OP_STTS 45 stts var, rs
#define DIF_OP_SRA 46 sra r1, r2, rd
#define DIF_OP_CALL 47 call subr, rd
#define DIF_OP_PUSHTR 48 pushtr type, rs, rr
#define DIF_OP_PUSHTV 49 pushtv type, rs, rv
#define DIF_OP_POPTS 50 popts
#define DIF_OP_FLUSHTS 51 flushts
#define DIF_OP_LDGAA 52 ldgaa var, rd
#define DIF_OP_LDTAA 53 ldtaa var, rd
#define DIF_OP_STGAA 54 stgaa var, rs
#define DIF_OP_STTAA 55 sttaa var, rs
#define DIF_OP_LDLS 56 ldls var, rd
#define DIF_OP_STLS 57 stls var, rs
#define DIF_OP_ALLOCS 58 allocs r1, rd
#define DIF_OP_COPYS 59 copys r1, r2, rd
#define DIF_OP_STB 60 stb r1, [rd]
#define DIF_OP_STH 61 sth r1, [rd]
#define DIF_OP_STW 62 stw r1, [rd]
#define DIF_OP_STX 63 stx r1, [rd]
#define DIF_OP_ULDSB 64 uldsb [r1], rd
#define DIF_OP_ULDSH 65 uldsh [r1], rd
#define DIF_OP_ULDSW 66 uldsw [r1], rd
#define DIF_OP_ULDUB 67 uldub [r1], rd
#define DIF_OP_ULDUH 68 ulduh [r1], rd
#define DIF_OP_ULDUW 69 ulduw [r1], rd
#define DIF_OP_ULDX 70 uldx [r1], rd
#define DIF_OP_RLDSB 71 rldsb [r1], rd
#define DIF_OP_RLDSH 72 rldsh [r1], rd
#define DIF_OP_RLDSW 73 rldsw [r1], rd
#define DIF_OP_RLDUB 74 rldub [r1], rd
#define DIF_OP_RLDUH 75 rlduh [r1], rd
#define DIF_OP_RLDUW 76 rlduw [r1], rd
#define DIF_OP_RLDX 77 rldx [r1], rd
#define DIF_OP_XLATE 78 xlate xlrindex, rd
#define DIF_OP_XLARG 79 xlarg xlrindex, rd
#define DIF_OP_STRIP 80 strip r1, key, rd
#define DIF_INTOFF_MAX 0xffff highest integer table offset
#define DIF_STROFF_MAX 0xffff highest string table offset
#define DIF_REGISTER_MAX 0xff highest register number
#define DIF_VARIABLE_MAX 0xffff highest variable identifier
#define DIF_SUBROUTINE_MAX 0xffff highest subroutine code
#define DIF_VAR_ARRAY_MIN 0x0000 lowest numbered array variable
#define DIF_VAR_ARRAY_UBASE 0x0080 lowest user-defined array
#define DIF_VAR_ARRAY_MAX 0x00ff highest numbered array variable
#define DIF_VAR_OTHER_MIN 0x0100 lowest numbered scalar or assc
#define DIF_VAR_OTHER_UBASE 0x0500 lowest user-defined scalar or assc
#define DIF_VAR_OTHER_MAX 0xffff highest numbered scalar or assc
#define DIF_VAR_ARGS 0x0000 arguments array
#define DIF_VAR_REGS 0x0001 registers array
#define DIF_VAR_UREGS 0x0002 user registers array
#define DIF_VAR_VMREGS 0x0003 virtual machine registers array
#define DIF_VAR_CURTHREAD 0x0100 thread pointer
#define DIF_VAR_TIMESTAMP 0x0101 timestamp
#define DIF_VAR_VTIMESTAMP 0x0102 virtual timestamp
#define DIF_VAR_IPL 0x0103 interrupt priority level
#define DIF_VAR_EPID 0x0104 enabled probe ID
#define DIF_VAR_ID 0x0105 probe ID
#define DIF_VAR_ARG0 0x0106 first argument
#define DIF_VAR_ARG1 0x0107 second argument
#define DIF_VAR_ARG2 0x0108 third argument
#define DIF_VAR_ARG3 0x0109 fourth argument
#define DIF_VAR_ARG4 0x010a fifth argument
#define DIF_VAR_ARG5 0x010b sixth argument
#define DIF_VAR_ARG6 0x010c seventh argument
#define DIF_VAR_ARG7 0x010d eighth argument
#define DIF_VAR_ARG8 0x010e ninth argument
#define DIF_VAR_ARG9 0x010f tenth argument
#define DIF_VAR_STACKDEPTH 0x0110 stack depth
#define DIF_VAR_CALLER 0x0111 caller
#define DIF_VAR_PROBEPROV 0x0112 probe provider
#define DIF_VAR_PROBEMOD 0x0113 probe module
#define DIF_VAR_PROBEFUNC 0x0114 probe function
#define DIF_VAR_PROBENAME 0x0115 probe name
#define DIF_VAR_PID 0x0116 process ID
#define DIF_VAR_TID 0x0117 (per-process) thread ID
#define DIF_VAR_EXECNAME 0x0118 name of executable
#define DIF_VAR_ZONENAME 0x0119 zone name associated with process
#define DIF_VAR_WALLTIMESTAMP 0x011a wall-clock timestamp
#define DIF_VAR_USTACKDEPTH 0x011b user-land stack depth
#define DIF_VAR_UCALLER 0x011c user-level caller
#define DIF_VAR_PPID 0x011d parent process ID
#define DIF_VAR_UID 0x011e process user ID
#define DIF_VAR_GID 0x011f process group ID
#define DIF_VAR_ERRNO 0x0120 thread errno
#define DIF_VAR_PTHREAD_SELF 0x0200 Apple specific PTHREAD_SELF (Not currently supported!)
#define DIF_VAR_DISPATCHQADDR 0x0201 Apple specific dispatch queue addr
#define DIF_VAR_MACHTIMESTAMP 0x0202 #define DIF_VAR_CPU 0x0203 cpu number
#define DIF_VAR_CPUINSTRS 0x0204 cpu instructions
#define DIF_VAR_CPUCYCLES 0x0205 cpu cycles
#define DIF_VAR_VINSTRS 0x0206 virtual instructions
#define DIF_VAR_VCYCLES 0x0207 virtual cycles
#define DIF_VAR_MACHCTIMESTAMP 0x0208 #define DIF_SUBR_MUTEX_OWNED 1 #define DIF_SUBR_MUTEX_OWNER 2 #define DIF_SUBR_MUTEX_TYPE_ADAPTIVE 3 #define DIF_SUBR_MUTEX_TYPE_SPIN 4 #define DIF_SUBR_RW_READ_HELD 5 #define DIF_SUBR_RW_WRITE_HELD 6 #define DIF_SUBR_RW_ISWRITER 7 #define DIF_SUBR_COPYIN 8 #define DIF_SUBR_COPYINSTR 9 #define DIF_SUBR_SPECULATION 10 #define DIF_SUBR_PROGENYOF 11 #define DIF_SUBR_STRLEN 12 #define DIF_SUBR_COPYOUT 13 #define DIF_SUBR_COPYOUTSTR 14 #define DIF_SUBR_ALLOCA 15 #define DIF_SUBR_BCOPY 16 #define DIF_SUBR_COPYINTO 17 #define DIF_SUBR_MSGDSIZE 18 #define DIF_SUBR_MSGSIZE 19 #define DIF_SUBR_GETMAJOR 20 #define DIF_SUBR_GETMINOR 21 #define DIF_SUBR_DDI_PATHNAME 22 #define DIF_SUBR_STRJOIN 23 #define DIF_SUBR_LLTOSTR 24 #define DIF_SUBR_BASENAME 25 #define DIF_SUBR_DIRNAME 26 #define DIF_SUBR_CLEANPATH 27 #define DIF_SUBR_STRCHR 28 #define DIF_SUBR_STRRCHR 29 #define DIF_SUBR_STRSTR 30 #define DIF_SUBR_STRTOK 31 #define DIF_SUBR_SUBSTR 32 #define DIF_SUBR_INDEX 33 #define DIF_SUBR_RINDEX 34 #define DIF_SUBR_HTONS 35 #define DIF_SUBR_HTONL 36 #define DIF_SUBR_HTONLL 37 #define DIF_SUBR_NTOHS 38 #define DIF_SUBR_NTOHL 39 #define DIF_SUBR_NTOHLL 40 #define DIF_SUBR_INET_NTOP 41 #define DIF_SUBR_INET_NTOA 42 #define DIF_SUBR_INET_NTOA6 43 #define DIF_SUBR_TOUPPER 44 #define DIF_SUBR_TOLOWER 45 #define DIF_SUBR_STRTOLL 47 #define DIF_SUBR_STRIP 48 #define DIF_SUBR_MAX 48 max subroutine value
Apple-specific subroutines
#define DIF_SUBR_APPLE_MIN 200 min apple-specific subroutine value
#define DIF_SUBR_VM_KERNEL_ADDRPERM 200 #define DIF_SUBR_KDEBUG_TRACE 201 #define DIF_SUBR_KDEBUG_TRACE_STRING 202 #define DIF_SUBR_MTONS 203 #define DIF_SUBR_PHYSMEM_READ 204 #define DIF_SUBR_PHYSMEM_WRITE 205 #define DIF_SUBR_KVTOPHYS 206 #define DIF_SUBR_LIVEDUMP 207 #define DIF_SUBR_APPLE_MAX 207 max apple-specific subroutine value
typedef uint32_t dif_instr_t #define DIF_INSTR_OP(i) (((i) >> 24) & 0xff) #define DIF_INSTR_R1(i) (((i) >> 16) & 0xff) #define DIF_INSTR_R2(i) (((i) >> 8) & 0xff) #define DIF_INSTR_RD(i) ((i) & 0xff) #define DIF_INSTR_RS(i) ((i) & 0xff) #define DIF_INSTR_IMM2(i) (((i) >> 8) & 0xff) #define DIF_INSTR_LABEL(i) ((i) & 0xffffff) #define DIF_INSTR_VAR(i) (((i) >> 8) & 0xffff) #define DIF_INSTR_INTEGER(i) (((i) >> 8) & 0xffff) #define DIF_INSTR_STRING(i) (((i) >> 8) & 0xffff) #define DIF_INSTR_SUBR(i) (((i) >> 8) & 0xffff) #define DIF_INSTR_TYPE(i) (((i) >> 16) & 0xff) #define DIF_INSTR_XLREF(i) (((i) >> 8) & 0xffff) #define DIF_INSTR_FMT(op, r1, r2, d) (((op) << 24) | ((r1) << 16) | ((r2) << 8) | (d)) #define DIF_INSTR_BRANCH(op, label) (((op) << 24) | (label)) #define DIF_INSTR_SETX(i, d) ((DIF_OP_SETX << 24) | ((i) << 8) | (d)) #define DIF_INSTR_SETS(s, d) ((DIF_OP_SETS << 24) | ((s) << 8) | (d)) #define DIF_INSTR_LDV(op, v, d) (((op) << 24) | ((v) << 8) | (d)) #define DIF_INSTR_STV(op, v, rs) (((op) << 24) | ((v) << 8) | (rs)) #define DIF_INSTR_CALL(s, d) ((DIF_OP_CALL << 24) | ((s) << 8) | (d)) #define DIF_INSTR_PUSHTS(op, t, r2, rs) (DIF_INSTR_FMT (op, t, r2, rs)) #define DIF_INSTR_XLATE(op, r, d) (((op) << 24) | ((r) << 8) | (d)) #define DIF_REG_R0 0 %r0 is always set to zero
A DTrace Intermediate Format Type (DIF Type) is used to represent the types
of variables, function and associative array arguments, and the return type
for each DIF object (shown below). It contains a description of the type,
its size in bytes, and a module identifier.
size 8, align 4
uint8_t dtdt_kind type kind (see below) uint8_t dtdt_ckind type kind in CTF uint8_t dtdt_flags type flags (see below) uint8_t dtdt_pad reserved for future use uint32_t dtdt_size type size in bytes (unless string)
#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
#define DIF_TF_BYUREF 0x2 user 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.
size 20, align 4
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)
#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
#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_TRACEMEM 6 tracemem() action
#define DTRACEACT_TRACEMEM_DYNSIZE 7 dynamic tracemem() size
#define DTRACEACT_APPLEBINARY 50 Apple DT perf. tool action
#define DTRACEACT_PROC 0x0100 #define DTRACEACT_PROC_DESTRUCTIVE 0x0200 #define DTRACEACT_PROC_CONTROL 0x0300 #define DTRACEACT_KERNEL 0x0400 #define DTRACEACT_KERNEL_DESTRUCTIVE 0x0500 #define DTRACEACT_SPECULATIVE 0x0600 #define DTRACEACT_CLASS(x) ((x) & 0xff00) 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 DTRACE_QUANTIZE_NBUCKETS (int)(((sizeof (uint64_t) * NBBY ) - 1) * 2 + 1) #define DTRACE_QUANTIZE_ZEROBUCKET (int64_t )((sizeof (uint64_t) * NBBY ) - 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_LLQUANTIZE_FACTORSHIFT 48 #define DTRACE_LLQUANTIZE_FACTORMASK ((uint64_t)UINT16_MAX << 48) #define DTRACE_LLQUANTIZE_LOWSHIFT 32 #define DTRACE_LLQUANTIZE_LOWMASK ((uint64_t)UINT16_MAX << 32) #define DTRACE_LLQUANTIZE_HIGHSHIFT 16 #define DTRACE_LLQUANTIZE_HIGHMASK ((uint64_t)UINT16_MAX << 16) #define DTRACE_LLQUANTIZE_NSTEPSHIFT 0 #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 )) #define DTRACE_PTR(type, name) type *name #define DOF_ID_SIZE 16 total size of dofh_ident[] in bytes
size 64, align 8
uint8_t[16] dofh_ident 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
#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_STRING "\177DOF" #define DOF_MODEL_ILP32 1 #define DOF_ENCODE_NONE 0 #define DOF_VERSION_1 1 DOF version 1: Solaris 10 FCS
#define DOF_VERSION_2 2 DOF version 2: Solaris Express 6/06
#define DOF_VERSION_3 3 DOF version 3: Minimum version for Leopard
#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
size 32, align 8
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
#define DOF_SECT_NONE 0 null section
#define DOF_SECT_SOURCE 2 D program source code
#define DOF_SECT_ECBDESC 3 #define DOF_SECT_PROBEDESC 4 #define DOF_SECT_ACTDESC 5 #define DOF_SECT_DIFOHDR 6 #define DOF_SECT_DIF 7 uint32_t array of byte code
#define DOF_SECT_STRTAB 8 string table
#define DOF_SECT_VARTAB 9 #define DOF_SECT_RELTAB 10 #define DOF_SECT_TYPTAB 11 #define DOF_SECT_URELHDR 12 #define DOF_SECT_KRELHDR 13 #define DOF_SECT_OPTDESC 14 #define DOF_SECT_PROVIDER 15 #define DOF_SECT_PROBES 16 #define DOF_SECT_PRARGS 17 uint8_t array (probe arg mappings)
#define DOF_SECT_PROFFS 18 uint32_t array (probe arg offsets)
#define DOF_SECT_INTTAB 19 uint64_t array
#define DOF_SECT_UTSNAME 20 struct utsname
#define DOF_SECT_XLTAB 21 #define DOF_SECT_XLMEMBERS 22 #define DOF_SECT_XLIMPORT 23 #define DOF_SECT_XLEXPORT 24 #define DOF_SECT_PREXPORT 25 #define DOF_SECT_PRENOFFS 26 uint32_t array (enabled offsets)
#define DOF_SECF_LOAD 1 section should be loaded
size 32, align 8
dof_secidx_t dofa_difo link to DOF_SECT_DIFOHDR dof_secidx_t dofa_strtab link to DOF_SECT_STRTAB section uint32_t dofa_kind action kind (DTRACEACT_* constant) uint32_t dofa_ntuple number of subsequent tuple actions uint64_t dofa_arg kind-specific argument uint64_t dofa_uarg user-supplied argument
size 24, align 8
dof_stridx_t dofr_name string name of relocation symbol uint32_t dofr_type relo type (DOF_RELO_* constant) uint64_t dofr_offset byte offset for relocation uint64_t dofr_data additional type-specific data
#define DOF_RELO_NONE 0 empty relocation entry
#define DOF_RELO_SETX 1 relocate setx value
size 16, align 8
uint32_t dofo_option option identifier dof_secidx_t dofo_strtab string table, if string option uint64_t dofo_value option value or string index
typedef uint32_t dof_attr_t encoded stability attributes
#define DOF_ATTR(n, d, c) (((n) << 24) | ((d) << 16) | ((c) << 8)) #define DOF_ATTR_NAME(a) (((a) >> 24) & 0xff) #define DOF_ATTR_DATA(a) (((a) >> 16) & 0xff) #define DOF_ATTR_CLASS(a) (((a) >> 8) & 0xff) size 48, align 8
uint64_t dofpr_addr probe base address or offset dof_stridx_t dofpr_func probe function string dof_stridx_t dofpr_name probe name string dof_stridx_t dofpr_nargv native argument type strings dof_stridx_t dofpr_xargv translated argument type strings uint32_t dofpr_argidx index of first argument mapping uint32_t dofpr_offidx index of first offset entry uint8_t dofpr_nargc native argument count uint8_t dofpr_xargc translated argument count uint16_t dofpr_noffs number of offset entries for probe uint32_t dofpr_enoffidx index of first is-enabled offset uint16_t dofpr_nenoffs number of is-enabled offsets uint16_t dofpr_pad1 reserved for future use uint32_t dofpr_pad2 reserved for future use
DTrace Intermediate Format Object (DIFO)
A DIFO is used to store the compiled DIF for a D expression, its return
type, and its string and variable tables. The string table is a single
buffer of character data into which sets instructions and variable
references can reference strings using a byte offset. The variable table
is an array of
dtrace_difv_t structures that describe the name and type of
each variable and the id used in the DIF code. This structure is described
above in the DIF section of this header file. The DIFO is used at both
user-level (in the library) and in the kernel, but the structure is never
passed between the two: the DOF structures form the only interface. As a
result, the definition can change depending on the presence of _KERNEL.
size 104, align 8
dif_instr_t *dtdo_buf instruction buffer uint64_t * dtdo_inttab integer table (optional) char * dtdo_strtab string table (optional) dtrace_difv_t *dtdo_vartab variable table (optional) uint_t dtdo_len length of instruction buffer uint_t dtdo_intlen length of integer table uint_t dtdo_strlen length of string table uint_t dtdo_varlen length of variable table dtrace_diftype_t dtdo_rtype return type uint_t dtdo_refcnt owner reference count uint_t dtdo_destructive invokes destructive subroutines dof_relodesc_t *dtdo_kreltab kernel relocations dof_relodesc_t *dtdo_ureltab user relocations struct dt_node ** dtdo_xlmtab translator references uint_t dtdo_krelen length of krelo table uint_t dtdo_urelen length of urelo table uint_t dtdo_xlmlen length of translator table
size 324, align 4
dtrace_id_t dtpd_id probe identifier char[64] dtpd_provider probe provider name char[64] dtpd_mod probe module name char[128] dtpd_func probe function name char[64] dtpd_name probe name
size 16, align 8
dtrace_difo_t *dtpdd_difo pointer to DIF object struct dtrace_predicate * dtpdd_predicate pointer to predicate
size 48, align 8
dtrace_difo_t *dtad_difo pointer to DIF object struct dtrace_actdesc * dtad_next next action dtrace_actkind_t dtad_kind kind of action uint32_t dtad_ntuple number in tuple uint64_t dtad_arg action argument uint64_t dtad_uarg user argument int dtad_refcnt reference count
DTrace Metadata Description Structures
DTrace separates the trace data stream from the metadata stream. The only
metadata tokens placed in the data stream are the
dtrace_rechdr_t (EPID +
timestamp) or (in the case of aggregations) aggregation identifiers. To
determine the structure of the data, DTrace consumers pass the token to the
kernel, and receive in return a corresponding description of the enabled
probe (via the
dtrace_eprobedesc structure) or the aggregation (via the
dtrace_aggdesc structure). Both of these structures are expressed in terms
of record descriptions (via the dtrace_recdesc structure) that describe the
exact structure of the data. Some record descriptions may also contain a
format identifier; this additional bit of metadata can be retrieved from the
kernel, for which a format description is returned via the
dtrace_fmtdesc
structure. Note that all four of these structures must be bitness-neutral
to allow for a 32-bit DTrace consumer on a 64-bit kernel.
size 32, align 8
dtrace_actkind_t dtrd_action kind of action uint32_t dtrd_size size of record uint32_t dtrd_offset offset in ECB's data uint16_t dtrd_alignment required alignment uint16_t dtrd_format format, if any uint64_t dtrd_arg action argument uint64_t dtrd_uarg user argument
size 56, align 8
dtrace_epid_t dtepd_epid enabled probe ID dtrace_id_t dtepd_probeid probe ID uint64_t dtepd_uarg library argument uint32_t dtepd_size total size int dtepd_nrecs number of records dtrace_recdesc_t [1]dtepd_rec records themselves
size 72, align 8
char * dtagd_name not filled in by kernel dtrace_aggvarid_t dtagd_varid not filled in by kernel int dtagd_flags not filled in by kernel dtrace_aggid_t dtagd_id aggregation ID dtrace_epid_t dtagd_epid enabled probe ID uint32_t dtagd_size size in bytes int dtagd_nrecs number of records uint32_t dtagd_pad explicit padding dtrace_recdesc_t [1]dtagd_rec record descriptions
size 16, align 8
char * dtfd_string format string int dtfd_length length of format string uint16_t dtfd_format format identifier
DTrace Option Interface
Run-time DTrace options are set and retrieved via
DOF_SECT_OPTDESC sections
in a DOF image. The
dof_optdesc structure contains an option identifier and
an option value. The valid option identifiers are found below; the mapping
between option identifiers and option identifying strings is maintained at
user-level. Note that the value of
DTRACEOPT_UNSET is such that all of the
following are potentially valid option values: all positive integers, zero
and negative one. Some options (notably "bufpolicy" and "bufresize") take
predefined tokens as their values; these are defined with
DTRACEOPT_{option}_{token}.
#define DTRACEOPT_BUFSIZE 0 buffer size
#define DTRACEOPT_BUFPOLICY 1 buffer policy
#define DTRACEOPT_DYNVARSIZE 2 dynamic variable size
#define DTRACEOPT_AGGSIZE 3 aggregation size
#define DTRACEOPT_SPECSIZE 4 speculation size
#define DTRACEOPT_NSPEC 5 number of speculations
#define DTRACEOPT_STRSIZE 6 string size
#define DTRACEOPT_CLEANRATE 7 dynvar cleaning rate
#define DTRACEOPT_CPU 8 CPU to trace
#define DTRACEOPT_BUFRESIZE 9 buffer resizing policy
#define DTRACEOPT_GRABANON 10 grab anonymous state, if any
#define DTRACEOPT_FLOWINDENT 11 indent function entry/return
#define DTRACEOPT_QUIET 12 only output explicitly traced data
#define DTRACEOPT_STACKFRAMES 13 number of stack frames
#define DTRACEOPT_USTACKFRAMES 14 number of user stack frames
#define DTRACEOPT_AGGRATE 15 aggregation snapshot rate
#define DTRACEOPT_SWITCHRATE 16 buffer switching rate
#define DTRACEOPT_STATUSRATE 17 status rate
#define DTRACEOPT_DESTRUCTIVE 18 destructive actions allowed
#define DTRACEOPT_STACKINDENT 19 output indent for stack traces
#define DTRACEOPT_RAWBYTES 20 always print bytes in raw form
#define DTRACEOPT_JSTACKFRAMES 21 number of jstack() frames
#define DTRACEOPT_JSTACKSTRSIZE 22 size of jstack() string table
#define DTRACEOPT_AGGSORTKEY 23 sort aggregations by key
#define DTRACEOPT_AGGSORTREV 24 reverse-sort aggregations
#define DTRACEOPT_AGGSORTPOS 25 agg. position to sort on
#define DTRACEOPT_AGGSORTKEYPOS 26 agg. key position to sort on
#define DTRACEOPT_AGGHIST 27 histogram aggregation output
#define DTRACEOPT_AGGPACK 28 packed aggregation output
#define DTRACEOPT_AGGZOOM 29 zoomed aggregation scaling
#define DTRACEOPT_TEMPORAL 30 temporally ordered output
#define DTRACEOPT_STACKSYMBOLS 31 clear to prevent stack symbolication
#define DTRACEOPT_BUFLIMIT 32 buffer signaling limit in % of the size
#define DTRACEOPT_MAX 33 number of options
#define DTRACEOPT_BUFPOLICY_RING 0 ring buffer
#define DTRACEOPT_BUFPOLICY_FILL 1 fill buffer, then stop
#define DTRACEOPT_BUFPOLICY_SWITCH 2 switch buffers
#define DTRACEOPT_BUFRESIZE_AUTO 0 automatic resizing
#define DTRACEOPT_BUFRESIZE_MANUAL 1 manual resizing
DTrace Buffer Interface
In order to get a snapshot of the principal or aggregation buffer,
user-level passes a buffer description to the kernel with the dtrace_bufdesc
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, the offset of the oldest record,
and the time of the snapshot.
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.
size 48, align 8
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 char * dtbd_data data uint64_t dtbd_oldest offset of oldest record uint64_t dtbd_timestamp hrtime of snapshot
Each record in the buffer (dtbd_data) begins with a header that includes
the epid and a timestamp. The timestamp is split into two 4-byte parts
so that we do not require 8-byte alignment.
size 12, align 4
#define DTRACE_RECORD_LOAD_TIMESTAMP(dtrh) ((dtrh)->dtrh_timestamp_lo +
((uint64_t)(dtrh)->dtrh_timestamp_hi << 32)) #define DTRACE_RECORD_STORE_TIMESTAMP(dtrh, hrtime) {
(dtrh)->dtrh_timestamp_lo = (uint32_t)hrtime;
(dtrh)->dtrh_timestamp_hi = hrtime >> 32;
} 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.
size 88, align 8
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 uint64_t dtst_stkstroverflows stack string tab overflows uint64_t dtst_dblerrors errors in ERROR probes char dtst_killed non-zero if killed char dtst_exiting non-zero if exit() called char[6] dtst_pad pad out to 64-bit align
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.
size 48, align 4
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 [8]dtc_pad reserved for future use
DTrace Faults
The constants below
DTRACEFLT_LIBRARY indicate probe processing faults;
constants at or above
DTRACEFLT_LIBRARY indicate faults in probe
postprocessing at user-level. Probe processing faults induce an
ERROR
probe and are replicated in unistd.d to allow users'
ERROR probes to 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
#define DTRACEFLT_BADSTACK 9 Bad stack
#define DTRACEFLT_LIBRARY 1000 Library-level fault
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.
size 268, align 4
dtrace_id_t dtargd_id probe identifier int dtargd_ndx arg number (-1 iff none) int dtargd_mapping value mapping char[128] dtargd_native native type name char[128] dtargd_xlate translated type name
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_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_ZONEOWNER 0x0010 size 12, align 4
uint32_t dtpp_flags privilege flags uid_t dtpp_uid user ID zoneid_t dtpp_zoneid zone ID
coding this as
IOC_VOID allows this driver to handle its own copyin/copuout
#define DTRACEIOC _IO ('d',0) #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_DOFGET (DTRACEIOC | 17) get DOF
#define DTRACEIOC_REPLICATE (DTRACEIOC | 18) replicate enab
#define DTRACEIOC_MODUUIDSLIST (DTRACEIOC | 30) APPLE ONLY, query for modules with missing symbols
#define DTRACEIOC_PROVMODSYMS (DTRACEIOC | 31) APPLE ONLY, provide missing symbols for a given module
#define DTRACEIOC_PROCWAITFOR (DTRACEIOC | 32) APPLE ONLY, wait for process exec
#define DTRACEIOC_SLEEP (DTRACEIOC | 33) APPLE ONLY, sleep
#define DTRACEIOC_SIGNAL (DTRACEIOC | 34) APPLE ONLY, signal sleeping process
size 144, align 8
uint64_t dtsym_addr address of the symbol uint64_t dtsym_size size of the symbol, must be uint64_t to maintain alignment when called by 64b uproc in i386 kernel char[128] dtsym_name symbol name
Safely compute the size in bytes of space we need to copyin module's symbols from userspace.
Assumes that count has been checked to be at least 1.
#define DTRACE_MODULE_SYMBOLS_SIZE(count) ({
size_t _sym_count = (size_t )(count - 1);
size_t _buf_size = 0;
if (os_mul_and_add_overflow (_sym_count,
sizeof(dtrace_symbol_t ),
sizeof(dtrace_module_symbols_t ),
&_buf_size)) {
_buf_size = 0;
}
_buf_size; }) size 24, align 8
uint64_t dtmul_count UUID [1]dtmul_uuid
size 136, align 4
char[128] p_name Must be specified by user-space int p_name_length Set or modified by the Kernel pid_t p_pid
DTrace wake reasons.
This is used in userspace to determine what's the reason why it woke up,
to start aggregating / switching buffer right away if it is because a buffer
got over its limit
#define DTRACE_WAKE_TIMEOUT 0 dtrace client woke up because of a timeout
#define DTRACE_WAKE_BUF_LIMIT 1 dtrace client woke up because of a over limit buffer
#define DTRACEHIOC_REMOVE _IO ('h', 2) remove helper
size 80, align 8
char[64] dofhp_mod executable or library name uint64_t dofhp_addr base address of object uint64_t dofhp_dof address of helper DOF
This structure is used to register one or more
dof_helper_t (s).
For counts greater than one, malloc the structure as if the
dofiod_helpers field was "count" sized. The kernel will copyin
data of size:
sizeof(
dof_ioctl_data_t ) + ((count - 1) * sizeof(
dof_helper_t ))
size 88, align 8
uint64_t dofiod_count This field must be 64 bits to keep the alignment the same
when 64 bit user procs are sending data to 32 bit xnu dof_helper_t [1]dofiod_helpers
#define DTRACEMNR_DTRACE "dtrace" node for DTrace ops
#define DTRACEMNR_HELPER "dtracehelper" 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
#define DTRACE_INVOP_NOP 4 #define DTRACE_INVOP_RET 5 Generated 2026-09-08 from the headers of one specific machine (macOS 26.4.1, SDK 26.4, arm64) — not official documentation. About & caveats