dr_defines.h File Reference

Basic defines and type definitions. More...

#include <windows.h>
#include <winbase.h>
#include <stdarg.h>
#include <sys/types.h>
#include "dr_mcxtx.h"

Data Structures
struct	opnd_t
struct	instr_t
union	_dr_xmm_t
union	_dr_ymm_t
union	_dr_zmm_t
union	_dr_svep_t
struct	_dr_mcontext_t
struct	dr_time_t
struct	_dr_stats_t

Macros
#define	MAXIMUM_PATH   260
#define	INVALID_FILE   INVALID_HANDLE_VALUE
#define	STDOUT   (dr_get_stdout_file())
#define	STDERR   (dr_get_stderr_file())
#define	STDIN   (dr_get_stdin_file())
#define	INVALID_FILE   -1
#define	STDOUT   our_stdout
#define	STDERR   our_stderr
#define	STDIN   our_stdin
#define	PFX   "%p"
#define	PIFX   "0x" PIFMT
#define	PIDFMT   SZFMT
#define	TIDFMT   SZFMT
#define	MCXT_NUM_SIMD_SVE_SLOTS   32
#define	MCXT_NUM_SVEP_SLOTS   16
#define	MCXT_NUM_FFR_SLOTS   1
#define	MCXT_NUM_SIMD_SLOTS   (MCXT_NUM_SIMD_SVE_SLOTS + MCXT_NUM_SVEP_SLOTS + MCXT_NUM_FFR_SLOTS)
#define	PRE_SIMD_PADDING   0
#define	MCXT_NUM_OPMASK_SLOTS   0
#define	DR_NOTE_FIRST_RESERVED   0xffffffffffff0000ULL

Typedefs
typedef size_t	app_rva_t
typedef uint	client_id_t
typedef union _dr_xmm_t	dr_xmm_t
typedef union _dr_ymm_t	dr_ymm_t
typedef union _dr_zmm_t	dr_zmm_t
typedef uint64	dr_opmask_t
typedef union _dr_svep_t	dr_svep_t
typedef dr_svep_t	dr_ffr_t
typedef struct _dr_mcontext_t	dr_mcontext_t
typedef struct _instrlist_t	instrlist_t
typedef struct _module_data_t	module_data_t
typedef struct _dr_stats_t	dr_stats_t

Enumerations
enum	dr_mcontext_flags_t {   DR_MC_INTEGER = 0x01,   DR_MC_CONTROL = 0x02,   DR_MC_MULTIMEDIA = 0x04,   DR_MC_ALL = (DR_MC_INTEGER | DR_MC_CONTROL | DR_MC_MULTIMEDIA) }
enum	{   DR_NOTE_ANNOTATION = DR_NOTE_FIRST_RESERVED + 1 ,   DR_NOTE_CLEAN_CALL_END,   DR_NOTE_REG_BARRIER,   DR_NOTE_CALL_SEQUENCE_START ,   DR_NOTE_RSEQ_ENTRY }
enum	dr_error_code_t {   DR_ERROR_INVALID_PARAMETER = 1,   DR_ERROR_INSUFFICIENT_SPACE = 2,   DR_ERROR_UNKNOWN_ENCODING = 3,   DR_ERROR_NOT_IMPLEMENTED = 4 }
enum	dr_where_am_i_t {   DR_WHERE_APP = 0,   DR_WHERE_INTERP,   DR_WHERE_DISPATCH,   DR_WHERE_MONITOR,   DR_WHERE_SYSCALL_HANDLER,   DR_WHERE_SIGNAL_HANDLER,   DR_WHERE_TRAMPOLINE,   DR_WHERE_CONTEXT_SWITCH,   DR_WHERE_IBL,   DR_WHERE_FCACHE,   DR_WHERE_CLEAN_CALLEE,   DR_WHERE_UNKNOWN,   DR_WHERE_LAST }
enum	dr_cleancall_save_t {   DR_CLEANCALL_SAVE_FLOAT = 0x0001,   DR_CLEANCALL_NOSAVE_FLAGS = 0x0002,   DR_CLEANCALL_NOSAVE_XMM = 0x0004,   DR_CLEANCALL_NOSAVE_XMM_NONPARAM = 0x0008,   DR_CLEANCALL_NOSAVE_XMM_NONRET = 0x0010,   DR_CLEANCALL_INDIRECT = 0x0020 ,   DR_CLEANCALL_ALWAYS_OUT_OF_LINE = 0x0080,   DR_CLEANCALL_READS_APP_CONTEXT = 0x0100,   DR_CLEANCALL_WRITES_APP_CONTEXT = 0x0200,   DR_CLEANCALL_MULTIPATH = 0x0400 }

Functions
union	ALIGN_VAR (16) _dr_simd_t

Variables
file_t	our_stdout
file_t	our_stderr
file_t	our_stdin

Detailed Description

Basic defines and type definitions.

Macro Definition Documentation

DR_NOTE_FIRST_RESERVED

#define DR_NOTE_FIRST_RESERVED   0xffffffffffff0000ULL

Upper note values are reserved for core DR.

INVALID_FILE [1/2]

#define INVALID_FILE   INVALID_HANDLE_VALUE

The sentinel value for an invalid file_t.

INVALID_FILE [2/2]

#define INVALID_FILE   -1

The sentinel value for an invalid file_t.

MAXIMUM_PATH

#define MAXIMUM_PATH   260

Maximum file path length define meant to replace platform-specific defines such as MAX_PATH and PATH_MAX. Currently, internal stack size limits prevent this from being much larger on UNIX.

MCXT_NUM_FFR_SLOTS

#define MCXT_NUM_FFR_SLOTS   1

Number of first-fault register slots in dr_mcontext_t.

MCXT_NUM_OPMASK_SLOTS

#define MCXT_NUM_OPMASK_SLOTS   0

Number of 16-64-bit OpMask Kn slots in dr_mcontext_t, \ if architecture supports. \

MCXT_NUM_SIMD_SLOTS

#define MCXT_NUM_SIMD_SLOTS   (MCXT_NUM_SIMD_SVE_SLOTS + MCXT_NUM_SVEP_SLOTS + MCXT_NUM_FFR_SLOTS)

Total number of SIMD register slots in dr_mcontext_t.

MCXT_NUM_SIMD_SVE_SLOTS

#define MCXT_NUM_SIMD_SVE_SLOTS   32

Number of 512-bit SIMD Vn/Zn slots in dr_mcontext_t. \

MCXT_NUM_SVEP_SLOTS

#define MCXT_NUM_SVEP_SLOTS   16

Number of SIMD Pn slots in dr_mcontext_t.

PFX

#define PFX   "%p"

printf format code for pointers

PIDFMT

#define PIDFMT   SZFMT

printf format code for process_id_t

PIFX

#define PIFX   "0x" PIFMT

printf format code for pointer-sized integers

PRE_SIMD_PADDING

#define PRE_SIMD_PADDING   0

Bytes of padding before xmm/ymm dr_mcontext_t slots. \

STDERR [1/2]

#define STDERR   (dr_get_stderr_file())

The file_t value for standard error.

STDERR [2/2]

#define STDERR   our_stderr

The file_t value for standard error.

STDIN [1/2]

#define STDIN   (dr_get_stdin_file())

The file_t value for standard input.

The file_t value for standard error.

STDIN [2/2]

#define STDIN   our_stdin

The file_t value for standard input.

The file_t value for standard error.

STDOUT [1/2]

#define STDOUT   (dr_get_stdout_file())

The file_t value for standard output.

STDOUT [2/2]

#define STDOUT   our_stdout

The file_t value for standard output.

TIDFMT

#define TIDFMT   SZFMT

printf format code for thread_id_t

Typedef Documentation

app_rva_t

typedef size_t app_rva_t

Application offset from module base. PE32+ modules are limited to 2GB, but not ELF x64 med/large code model.

client_id_t

typedef uint client_id_t

ID used to uniquely identify a client. This value is set at client registration and passed to the client in dr_client_main().

dr_ffr_t

typedef dr_svep_t dr_ffr_t

64-bit Arm Scalable Vector Extension (SVE) First Fault Register (FFR). FFR is a special purpose predicate register used by some SVE instructions.

dr_mcontext_t

typedef struct _dr_mcontext_t dr_mcontext_t

Machine context structure.

dr_opmask_t

typedef uint64 dr_opmask_t

AVX-512 OpMask (k-)register.

dr_stats_t

typedef struct _dr_stats_t dr_stats_t

Used by dr_get_stats() and dr_app_stop_and_cleanup_with_stats()

dr_svep_t

typedef union _dr_svep_t dr_svep_t

64-bit Arm Scalable Vector Extension (SVE) predicate register Pn. SVE Pn registers are used to hold mask values that control the operation of some SVE instructions. Pn registers have one bit for every byte of a Zn register to the size of a Pn register is always 1/8 the size of a Zn register. DynamoRIO currently supports up to 512-bit Zn registers and 64-bit Pn registers.

dr_xmm_t

typedef union _dr_xmm_t dr_xmm_t

128-bit XMM register.

dr_ymm_t

typedef union _dr_ymm_t dr_ymm_t

256-bit YMM register.

dr_zmm_t

typedef union _dr_zmm_t dr_zmm_t

512-bit ZMM register.

instrlist_t

typedef struct _instrlist_t instrlist_t

The opaque type used to represent linear lists of instr_t instructions.

module_data_t

typedef struct _module_data_t module_data_t

Alias for the _module_data_t structure holding library information.

Enumeration Type Documentation

anonymous enum

anonymous enum

Enumerator
DR_NOTE_ANNOTATION	Identifies an annotation point. This label will be replaced by a clean call to the registered annotation handler.
DR_NOTE_CLEAN_CALL_END	Identifies the end of a clean call.
DR_NOTE_REG_BARRIER	Identifies a point at which clients should restore all registers to their application values, as required for DR's internal block mangling.
DR_NOTE_CALL_SEQUENCE_START	Used for internal translation from an instruction list. These apply not only to client-inserted clean calls but all inserted calls whether inserted by clients or DR and whether fully clean or not. This is thus distinct from DR_NOTE_CLEAN_CALL_END.
DR_NOTE_RSEQ_ENTRY	Placed at the top of a basic block, this identifies the entry to an "rseq" (Linux restartable sequence) region. The first two label data fields (see instr_get_label_data_area()) are filled in with this rseq region's end PC and its abort handler PC, in that order.

dr_cleancall_save_t

enum dr_cleancall_save_t

Flags to request non-default preservation of state in a clean call as well as other call options. This is used with dr_insert_clean_call_ex(), dr_insert_clean_call_ex_varg(), and dr_register_clean_call_insertion_event().

Enumerator
DR_CLEANCALL_SAVE_FLOAT	Save legacy floating-point state (x86-specific; not saved by default). The last floating-point instruction address (FIP) in the saved state is left in an untranslated state (i.e., it may point into the code cache). This flag is orthogonal to the saving of SIMD registers and related flags below.
DR_CLEANCALL_NOSAVE_FLAGS	Skip saving the flags and skip clearing the flags (including DF) for client execution. Note that this can cause problems if dr_redirect_execution() is called from a clean call, as an uninitialized flags value can cause subtle errors.
DR_CLEANCALL_NOSAVE_XMM	Skip saving any XMM or YMM registers (saved by default).
DR_CLEANCALL_NOSAVE_XMM_NONPARAM	Skip saving any XMM or YMM registers that are never used as parameters.
DR_CLEANCALL_NOSAVE_XMM_NONRET	Skip saving any XMM or YMM registers that are never used as return values.
DR_CLEANCALL_INDIRECT	Requests that an indirect call be used to ensure reachability, both for reaching the callee and for any out-of-line helper routine calls. Only honored for 64-bit mode, where r11 will be used for the indirection.
DR_CLEANCALL_ALWAYS_OUT_OF_LINE	Requests that out-of-line state save and restore routines be used even when a subset of the state does not need to be preserved for this callee. Also disables inlining. This helps guarantee that the inserted code remains small.
DR_CLEANCALL_READS_APP_CONTEXT	Indicates that the callee will access the application context (either as passed parameters or by calling dr_get_mcontext()). This flag is passed to callbacks registered with dr_register_clean_call_insertion_event() requesting that register reservation code in clients and libraries restore application values to all registers. Without this flag, register values observed by the callee may be values written by instrumentation rather than application values. If the intent is to have a mixture of application and tool values in registers, manual restoration is required rather than passing this automation flag.
DR_CLEANCALL_WRITES_APP_CONTEXT	Indicates that the callee will modify the application context (by calling dr_set_mcontext()). This flag is passed to callbacks registered with dr_register_clean_call_insertion_event() requesting that register reservation code in clients and libraries update spilled application register values. Without this flag, changes made by dr_set_mcontext() may be undone by later restores of spilled values.
DR_CLEANCALL_MULTIPATH	Indicates that the clean call may be skipped by inserted tool control flow. This affects how register spilling and restoring occurs when combined with the DR_CLEANCALL_READS_APP_CONTEXT flag. Tool values may be clobbered when this flag is used. If control flow and clean call context access is used with registers holding tool values across the clean call, manual restoration may be required rather than passing any of these automated flags. Combining this flag with DR_CLEANCALL_WRITES_APP_CONTEXT is not supported. Manual updates are required for such a combination.

dr_error_code_t

enum dr_error_code_t

Error codes of DR API routines.

Enumerator
DR_ERROR_INVALID_PARAMETER	Invalid parameter passed to the API routine.
DR_ERROR_INSUFFICIENT_SPACE	Insufficient size of passed buffer.
DR_ERROR_UNKNOWN_ENCODING	String encoding is unknown.
DR_ERROR_NOT_IMPLEMENTED	Feature of API routine not yet implemented.

dr_mcontext_flags_t

enum dr_mcontext_flags_t

Values for the flags field of dr_mcontext_t

Enumerator
DR_MC_INTEGER	On x86, selects the xdi, xsi, xbp, xbx, xdx, xcx, xax, and r8-r15 fields (i.e., all of the general-purpose registers excluding xsp, xip, and xflags). On ARM, selects r0-r12 and r14. On AArch64, selects r0-r30.
DR_MC_CONTROL	On x86, selects the xsp, xflags, and xip fields. On ARM, selects the sp, pc, and cpsr fields. On AArch64, selects the sp, pc, and nzcv fields. On RISC-V, selects the sp, pc and fcsr fields. Note : The xip/pc field is only honored as an input for dr_redirect_execution(), and as an output for system call events.
DR_MC_MULTIMEDIA	Selects the simd fields. This flag is ignored unless dr_mcontext_xmm_fields_valid() returns true. If dr_mcontext_xmm_fields_valid() returns false, the application values of the multimedia registers remain in the registers themselves.
DR_MC_ALL	Selects all fields

dr_where_am_i_t

enum dr_where_am_i_t

Identifies where a thread's control is at any one point. Used with client PC sampling using dr_set_itimer().

Enumerator
DR_WHERE_APP	Control is in native application code.
DR_WHERE_INTERP	Control is in basic block building.
DR_WHERE_DISPATCH	Control is in d_r_dispatch.
DR_WHERE_MONITOR	Control is in trace building.
DR_WHERE_SYSCALL_HANDLER	Control is in system call handling.
DR_WHERE_SIGNAL_HANDLER	Control is in signal handling.
DR_WHERE_TRAMPOLINE	Control is in trampoline hooks.
DR_WHERE_CONTEXT_SWITCH	Control is in context switching.
DR_WHERE_IBL	Control is in inlined indirect branch lookup.
DR_WHERE_FCACHE	Control is in the code cache.
DR_WHERE_CLEAN_CALLEE	Control is in a clean call.
DR_WHERE_UNKNOWN	Control is in an unknown location.
DR_WHERE_LAST	Equals the count of DR_WHERE_xxx locations.

Function Documentation

ALIGN_VAR()

union ALIGN_VAR

(

16

)

512-bit ARM Scalable Vector Extension (SVE) vector registers Zn. Low 128 bits of Zn overlap with existing ARM Advanced SIMD (NEON) Vn registers. The SVE specification defines the following valid vector lengths: 128 256 384 512 640 768 896 1024 1152 1280 1408 1536 1664 1792 1920 2048 We currently support 512-bit maximum due to DR's stack size limitation, (machine context stored in the stack). In AArch64, align to 16 bytes for better performance. In AArch32, we're not using any uint64 fields here to avoid alignment padding in sensitive structs. We could alternatively use pragma pack.

< Byte (8 bit, Bn) scalar element of Vn, Zn, or Pn.

< Halfword (16 bit, Hn) scalar element of Vn, Zn and Pn.

< Singleword (32 bit, Sn) scalar element of Vn, Zn and Pn.

< Doubleword (64 bit, Dn) scalar element of Vn, Zn and Pn.

< The full 128 bit Vn register, Qn as q[3]:q[2]:q[1]:q[0].

< The full 512 bit Zn register as Singleword (32-bit) elements.

< The full 512 bit Zn register as Doubleword (64-bit) elements.

Variable Documentation

our_stderr

file_t our_stderr

Allow use of stderr after the application closes it.

our_stdin

file_t our_stdin

Allow use of stdin after the application closes it.

our_stdout

file_t our_stdout

Allow use of stdout after the application closes it.