Data structure passed within dr_exception_t, dr_siginfo_t, and
dr_restore_state_info_t.
Contains information about the code fragment inside the code cache
at the exception/signal/translation interruption point.
Iterator over the list of modules that a given module imports from. Created
by calling dr_module_import_iterator_start() and must be freed by calling
dr_module_import_iterator_stop().
Data structure passed to a restore_state_ex event handler (see
dr_register_restore_state_ex_event()). Contains the machine
context at the translation point and other translation
information.
Symbol export iterator data type. Can be created by calling
dr_symbol_export_iterator_start() and must be freed by calling
dr_symbol_export_iterator_stop().
Symbol import iterator data type. Can be created by calling
dr_symbol_import_iterator_start() and must be freed by calling
dr_symbol_import_iterator_stop().
Defines the Valgrind client request object, which is constructed by each instance of
a Valgrind annotation in the target app. An instance is passed to Valgrind annotation
callback functions to make the arguments available. Some arguments may be
undefined for some Valgrind client requests; see the Valgrind documentation for each
specific Valgrind client request for details about the arguments.
Holds information about a loaded module. \note On Linux the start address can be
cast to an Elf32_Ehdr or Elf64_Ehdr. \note On Windows the start address can be cast to
an IMAGE_DOS_HEADER for use in finding the IMAGE_NT_HEADER and its OptionalHeader.
The OptionalHeader can be used to walk the module sections (among other things).
See WINNT.H. \note On MacOS the start address can be cast to mach_header or
mach_header_64.
\note When accessing any memory inside the module (including header fields)
user is responsible for guarding against corruption and the possibility of the module
being unmapped.
Type used for dr_get_proc_address(). This can be obtained from the
#_module_data_t structure. It is equivalent to the base address of
the module on both Windows and Linux.
Holds the names of a module. This structure contains multiple
fields corresponding to different sources of a module name. Note
that some of these names may not exist for certain modules. It is
highly likely, however, that at least one name is available. Use
dr_module_preferred_name() on the parent _module_data_t to get the
preferred name of the module.
Flags controlling the behavior of basic blocks and traces when emitted
into the code cache. These flags are bitmasks that can be combined by
or-ing together. For multiple clients, the flags returned by each
client are or-ed together.
A version of #instr_t which guarantees to not use heap allocation for regular
decoding and encoding. It inlines all the possible operands and encoding space
inside the structure. Some operations could still use heap if custom label data is
used to point at heap-allocated structures through extension libraries or custom
code.
Internal structure of instr_t is below abstraction layer, but we
provide its size so that it can be used in stack variables
instead of always allocated on the heap.
An enum of spill slots to use with dr_save_reg(), dr_restore_reg(),
dr_save_arith_flags(), dr_restore_arith_flags() and
dr_insert_mbr_instrumentation(). Values stored in spill slots remain
valid only until the next non-meta (i.e. application) instruction. Spill slots
can be accessed/modifed during clean calls and restore_state_events (see
dr_register_restore_state_event()) with dr_read_saved_reg() and
dr_write_saved_reg().
If set, loads the specified file at a location that is reachable from
the code cache and client libraries by a 32-bit displacement. If not
set, the mapped file is not guaranteed to be reachable from the cache.
If set, indicates that the passed-in start address is required rather than a
hint. On Linux, this has the same semantics as mmap with MAP_FIXED: i.e.,
any existing mapping in [addr,addr+size) will be unmapped. This flag is not
supported on Windows.
If set, changes to mapped memory are private to the mapping process and
are not reflected in the underlying file. If not set, changes are visible
to other processes that map the same file, and will be propagated
to the file itself.
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.
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.
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.
Defines the maximum number of arguments that can be passed to a Valgrind
annotation, and accordingly specifies the length of the array
vg_client_request_t.args.
< Intel ‘c’: 2/1 bytes (“2/1” means 2 bytes normally, but if
another operand requests a short size then this size can
accommodate by shifting to its short size, which is 1
byte).
< Intel ‘v’/‘d64’ for stack operations.
Also 64-bit address-size specified operands, which are
short4 rather than short2 in 64-bit mode (but short2 in
32-bit mode).
Note that this IR does not distinguish extra stack
operations performed by OP_enter w/ non-zero immed.
< Intel ‘p’: On Intel processors this is 10/6/4 bytes for
segment selector + address. On AMD processors this is
6/4 bytes for segment selector + address (rex is ignored).
This register’s value is extended prior to use in the containing instruction.
This flag is for informational purposes only and is not guaranteed to
be consistent with the shift type of an index register or displacement
if the latter are set without using opnd_set_index_extend() or if an
instruction is created without using high-level API routines.
This flag is also ignored for encoding and will not apply a shift
on its own.
This operand should be combined with an adjacent operand to create a
single value. This flag is typically used on immediates: e.g., for ARM’s
OP_vbic_i64, two 32-bit immediate operands should be interpreted as the
low and high parts of a 64-bit value.
This register’s value is shifted prior to use in the containing instruction.
This flag is for informational purposes only and is not guaranteed to
be consistent with the shift type of an index register or displacement
if the latter are set without using opnd_set_index_shift() or if an
instruction is created without using high-level API routines.
This flag is also ignored for encoding and will not apply a shift
on its own.
By default, routines that take in these flags will only consider
destinations that are always written. Thus, all destinations are skipped
for an instruction that is predicated and executes conditionally (see
instr_is_predicated()). If this flag is set, a conditionally executed
instruction’s destinations are included just like any other
instruction’s. As a special case, the addressing registers inside a
destination memory operand are covered by DR_QUERY_INCLUDE_COND_SRCS
rather than this flag.
By default, routines that take in these flags will only consider sources
that are always read. Thus, all sources are skipped for an instruction
that is predicated and executes conditionally (see
instr_is_predicated()), except for predication conditions that involve
the source operand values. If this flag is set, a conditionally executed
instruction’s sources are included just like any other instruction’s.
As a special case, the addressing registers inside a destination memory
operand are covered by this flag rather than DR_QUERY_INCLUDE_COND_DSTS.
x86 condition: special opcode-specific condition that depends on the
values of the source operands. Thus, unlike all of the other conditions,
the source operands will be accessed even if the condition then fails
and the destinations are not touched. Any written eflags are
unconditionally written, unlike regular destination operands.
The register is rotated right by 1 bit, with the carry flag (rather than
bit 0) being shifted in to the most-significant bit. (For shifts of
general source registers, if the instruction writes the condition codes,
bit 0 is then shifted into the carry flag: but for memory references bit
0 is simply dropped.)
Only valid for shifts whose amount is stored in an immediate, not a register.
Request that DynamoRIO discard all fragments in the code cache that were
translated from the specified range of addresses. The request takes 2 args,
start and length. It is implemented in core DR with JIT optimization enabled,
though clients may implement additional functionality.
Allocate memory that is 32-bit-displacement reachable from the
code caches and from the client library. Memory allocated
through dr_thread_alloc(), dr_global_alloc(), and
dr_nonheap_alloc() is also reachable, but for
dr_custom_alloc(), the resulting memory is not reachable unless
this flag is specified. If this flag is passed, the requested
location (\p addr parameter) must be NULL. This flag is not
compatible with #DR_ALLOC_LOW_2GB, #DR_ALLOC_FIXED_LOCATION, or
#DR_ALLOC_NON_DR.
This flag only applies to non-heap memory (i.e., when
#DR_ALLOC_NON_HEAP is specified). The flag requests that
memory be allocated at a specific address, given in the \p addr
parameter. Without this flag, the \p addr parameter is not
honored. This flag is not compatible with #DR_ALLOC_LOW_2GB or
#DR_ALLOC_CACHE_REACHABLE.
This flag only applies to non-heap memory (i.e., when
#DR_ALLOC_NON_HEAP is specified) in 64-bit mode. The flag
requests that memory be allocated in the low 2GB of the address
space. If this flag is passed, the requested location (\p addr
parameter) must be NULL. This flag is not compatible with
#DR_ALLOC_FIXED_LOCATION.
This flag only applies to non-heap memory (i.e., when
#DR_ALLOC_NON_HEAP is specified). When this flag is specified,
the allocated memory is not considered to be DynamoRIO or tool
memory and thus is not kept separate from the application.
This is similar to dr_raw_mem_alloc(). Use of this memory is
at the client’s own risk. This flag is not compatible with
#DR_ALLOC_CACHE_REACHABLE.
If this flag is not specified, dr_custom_alloc() uses a managed
heap to allocate the memory, just like dr_thread_alloc() or
dr_global_alloc(). In that case, it ignores any requested
protection bits (\p prot parameter), and the location (\p addr
parameter) must be NULL. If this flag is specified, a
page-aligned, separate block of memory is allocated, in a
similar fashion to dr_nonheap_alloc().
This flag only applies to heap memory (i.e., when
#DR_ALLOC_NON_HEAP is not specified). If this flag is not
specified, global heap is used (just like dr_global_alloc())
and the \p drcontext parameter is ignored. If it is specified,
thread-private heap specific to \p drcontext is used, just like
dr_thread_alloc().
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.
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.
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.
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.
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.
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.
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.
Requests standard ARM (32-bit) assembler syntax for disassembly. This
sets the same option that is controlled by the runtime option
\p -syntax_arm. Implicit operands are not displayed.
Requests AT&T syntax for disassembly. This sets the same option that is
controlled by the runtime option \p -syntax_att. Implicit operands
are not displayed.
Requests Intel syntax for disassembly. This sets the same option that is
controlled by the runtime option \p -syntax_intel. Implicit operands
are not displayed.
This flag only applies to the default DR style (i.e., it does not apply
when DR_DISASM_INTEL or DR_DISASM_ATT is selected). That style by
default displays the size of memory or sub-register operands via a
suffix “[Nbytes]”. Setting this flag removes that suffix.
Requests RISC-V assembler syntax for disassembly. This set the same option that
is controlled by the runtime option \p -syntax_riscv. Implicit oprands are not
displayed.
Certain reserved or unspecified opcodes are in a gray area where they
could be decoded with their length and operands understood, but they are
not fully defined and in fact they may raise an illegal instruction fault
when executed. By default, DR does not treat them as invalid. If this
option is set, DR tightens up its decoding and does treat them as
invalid.
A Linux restartable sequence was aborted. The interrupted PC for a signal in
the execution instrumentation points to the precise interrupted
instruction; but for an abort in the native exeuction, the PC always points
to the abort handler, rather than the precise instruction that was aborted.
This aligns with kernel behavior: the interrupted PC is not saved anywhere.
Requests that writable segments are not mapped, to save address space.
This may be ignored on some platforms and may only be honored for
a writable segment that is at the very end of the loaded module.
A “livedump”, or “ldmp”, DynamoRIO’s own custom memory dump format.
The ldmp format does not currently support specifying a context
for the calling thread, so it will always include the call frames
to dr_create_memory_dump(). The \p ldmp.exe tool can be used to
create a dummy process (using the \p dummy.exe executable) which
can then be attached to by the debugger (use a non-invasive attach)
in order to view the memory dump contents.
Do not deliver the signal. Instead, redirect control to the
application state specified in dr_siginfo_t.mcontext.
Clients may modify dr_siginfo_t.mcontext.pc to redirect control to
a desired pc, but beware that it is important to set the app state
(like the register values) as expected by the transfer point.
On Linux, DR’s own TLS can optionally be swapped, but this is risky
and not recommended as incoming signals are not properly handled when in
such a state. Thus DR_STATE_ALL does not swap it.
By default, native threads are not suspended by
dr_suspend_all_other_threads_ex(). This flag requests that native
threads (including those temporarily-native due to actions such as
#DR_EMIT_GO_NATIVE) be suspended as well.
Allocates memory from DR’s global memory pool, but mimics the
behavior of calloc. Memory must be freed with __wrap_free(). The
__wrap routines are intended to be used with ld’s -wrap option; see
__wrap_malloc() for more information.
The returned address is guaranteed to be double-pointer-aligned:
aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.
Frees memory from DR’s global memory pool. Memory must have been
allocated with __wrap_malloc(). The __wrap routines are intended to
be used with ld’s -wrap option; see __wrap_malloc() for more
information.
Allocates memory from DR’s global memory pool, but mimics the
behavior of malloc. Memory must be freed with __wrap_free(). The
__wrap routines are intended to be used with ld’s -wrap option to
replace a client’s use of malloc, realloc, and free with internal
versions that allocate memory from DR’s private pool. With -wrap,
clients can link to libraries that allocate heap memory without
interfering with application allocations.
The returned address is guaranteed to be double-pointer-aligned:
aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.
Reallocates memory from DR’s global memory pool, but mimics the
behavior of realloc. Memory must be freed with __wrap_free(). The
__wrap routines are intended to be used with ld’s -wrap option; see
__wrap_malloc() for more information.
The returned address is guaranteed to be double-pointer-aligned:
aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.
Allocates memory for a new string identical to ‘str’ and copies the
contents of ‘str’ into the new string, including a terminating
null. Memory must be freed with __wrap_free(). The __wrap
routines are intended to be used with ld’s -wrap option; see
__wrap_malloc() for more information.
The returned address is guaranteed to be double-pointer-aligned:
aligned to 16 bytes for 64-bit; aligned to 8 bytes for 32-bit.
The #DR_DISALLOW_UNSAFE_STATIC declaration requests that DR perform sanity
checks to ensure that client libraries will also operate safely when linked
statically into an application. This overrides that request, facilitating
having runtime options that are not supported in a static context.
Can only be called on an annotation already registered with
dr_annotation_register_call(). When the annotation is encountered, the PC of
the annotation interruption point will be available in DR scratch slot #SPILL_SLOT_2,
which can be read with dr_read_saved_reg().
Register a handler for a DR annotation. When the annotation is encountered, it will
be replaced with a clean call to the specified callee, which must have the specified
number of arguments. Returns true on successful registration.
Register a return value substitution for a DR annotation. When the annotation is
encountered, it will be replaced with the specified return value. This function
returns true on successful registration.
Register a callback for a Valgrind client request id. When the request is encountered,
the specified callback will be invoked by an internal routing function. Returns true
on successful registration.
Unregister the specified handler from a DR annotation. Instances of the annotation that
have already been substituted with a clean call to the registered callee will remain in
the code cache, but any newly encountered instances of the annotation will no longer be
substituted with this callee. This function does nothing in the case that the
specified callee was never registered for this annotation (or has already been
unregistered). Returns true if the registration was successfully unregistered.
Unregister the (universal) return value from a DR annotation. Instances of the
annotation that have already been substituted with the return value will remain in the
code cache, but any newly encountered instances of the annotation will no longer be
substituted. This function does nothing in the case that no return value is currently
registered for the specified annotation (or has already been unregistered). Note that
if another client has registered a return value, this function will remove that other
client’s registration. Returns true if the registration was successfully unregistered.
Unregister the specified callback from a Valgrind client request. The registered
callback will not be invoked in association with this client request again (though if
the same callback function is also registered for other Valgrind client requests, it
will still be invoked in association with those client requests). This function does
nothing in the case that no handler was ever registered for this callback function.
Returns true if the registration was found and successfully unregistered.
Returns the passed argument \p app_arg as a string. \p buf is used only if needed, and
therefore the caller should not assume that the string is in the \p buf. In other
words, always use the returned value to refer to the string. Returns NULL on error
such as when \p buf is needed as storage and the size of the buffer \p buf_size
is not sufficient.
Application-wide cleanup. Prints statistics. Returns zero on success.
Once this is invoked, calling dr_app_start() or dr_app_setup() is not supported.
This should be invoked at application exit, after joining with
application threads. If the application wants to continue
executing significant code or executing additional threads after
cleanup, it should use dr_app_stop_and_cleanup() instead.
DynamoRIO’s (experimental) native execution mode supports running
some modules natively while the others run under DynamoRIO.
When a module is running natively, it may jump to a module that should be
executed under DynamoRIO directly without going through DynamoRIO.
To handle this situation, the application code should call this routine and
use the returned stub pc as the branch target instead.
\note Linux only.
\note Native execution mode only.
\note Experimental support.
Given an application program counter value, returns the
corresponding value to use as an indirect branch target for the
given \p isa_mode. For ARM’s Thumb mode (#DR_ISA_ARM_THUMB), this
involves setting the least significant bit of the address.
Given an application program counter value, returns the
corresponding value to use as a memory load target for the given \p
isa_mode, or for comparing to the application address inside a
basic block or trace. For ARM’s Thumb mode (#DR_ISA_ARM_THUMB),
this involves clearing the least significant bit of the address.
Given an application PC, returns a PC that contains the application code
corresponding to the original PC. In some circumstances on Windows DR
inserts a jump on top of the original code, which the client will not
see in the bb and trace hooks due to DR replacing it there with the
displaced original application code in order to present the client with
an unmodified view of the application code. A client should use this
routine when attempting to decode the original application instruction
that caused a fault from the translated fault address, as the translated
address may actually point in the middle of DR’s jump.
Given a code cache pc, returns the corresponding application pc.
This involves translating the state and thus may incur calls to
the basic block and trace events (see dr_register_bb_event()).
If translation fails, returns NULL.
This routine may not be called from a thread exit event.
Acquires \p reclock, or increments the ownership count if already owned.
Calls to this method which block (i.e. when the lock is already held) are
marked safe to suspend AND transfer; in that case the provided mcontext \p mc
will overwrite the current thread’s mcontext. \p mc must have a valid PC
and its flags must be DR_MC_ALL.
Indicates whether the current thread is running within the DynamoRIO code
cache. Returns \p true only if the current thread is running within the
DynamoRIO code cache and returns false othrewise.
Calls dr_app_setup() and, if it succeeds, calls dr_app_start(). Returns the
result of dr_app_setup(), which returns zero on success. This routine is
intended as a convenient single point of entry for callers who are using
dlsym() or GetProcAddress() to access the app API.
Causes all of the application’s threads to run directly on the machine upon
return from this call; no effect if the application is not currently running
under DR control.
Causes all of the application’s threads to run directly on the machine upon
return from this call, and additionally frees the resources used by DR.
Once this is invoked, calling dr_app_start() is not supported until
dr_app_setup() or dr_app_setup_and_start() is called for a re-attach.
Same as dr_app_stop_and_cleanup, additionally filling in the provided
dr_stats_t object, after all threads have been detached and
right before clearing stats. The parameter may be NULL, in which case
stats are not collected, the API behaving identically to
dr_app_stop_and_cleanup().
Causes application to run under DR control upon return from
this call. DR never releases control. Useful for overriding
dr_app_start/dr_app_stop calls in the rest of a program.
Calls the specified function \p func after switching to the DR stack
for the thread corresponding to \p drcontext.
Passes in 8 arguments. Uses the C calling convention, so \p func will work
just fine even if if takes fewer than 8 args.
Swaps the stack back upon return and returns the value returned by \p func.
When registering a process, users must provide a list of paths to
client libraries and their associated client-specific options. DR
looks up “dr_client_main” in each client library and calls that function
when the process starts. Clients can register to receive callbacks
for the various events within dr_client_main(). Note that client paths and
options cannot include semicolons.
Causes DynamoRIO to insert code that stores \p value into the
return address slot on the stack immediately after the original
value is read by the return instruction \p instr.
\p instr must be a return instruction or this routine will fail.
Makes a copy of \p data. Copy must be freed with dr_free_module_data().
Useful for making persistent copies of module_data_t’s received as part of
image load and unload event callbacks.
Creates a new thread that is marked as a non-application thread (i.e., DR
will let it run natively and not execute its code from the code cache). The
thread will terminate automatically simply by returning from \p func; if
running when the application terminates its last thread, the client thread
will also terminate when DR shuts the process down.
Creates a new directory. Fails if the directory already exists
or if it can’t be created.
Relative path support on Windows is identical to that described in dr_open_file().
Request a flush of all fragments containing code from the region
[\p start, \p start + \p size). The flush will be performed at the next safe
point in time (usually before any new code is added to the cache after this
routine is called). If \p flush_completion_callback is non-NULL, it will be
called with the \p flush_id provided to this routine when the flush completes,
after which no execution will occur out of the fragments flushed. Returns true
if the flush was successfully queued.
Deletes the file referred to by \p filename.
Returns true if successful.
On both Linux and Windows, if filename refers to a symlink, the symlink will
be deleted and not the target of the symlink.
On Windows, this will fail to delete any file that was not opened with
FILE_SHARE_DELETE and is still open.
Relative path support on Windows is identical to that described in dr_open_file().
Deletes the fragment with tag \p tag. This routine is only valid
with the -thread_private option; it deletes the fragment in the
current thread only. After deletion, the existing fragment is
allowed to complete execution. For example, a clean call deleting
the currently executing fragment will safely return to the existing
code. Subsequent executions will cause DynamoRIO to reconstruct
the fragment, and therefore call the appropriate fragment-creation
event hook, if registered.
Exits the process, first performing a full cleanup that will
trigger the exit event (dr_register_exit_event()). The process
exit code is set to \p exit_code.
Sets the current file position for file \p f to \p offset bytes
from the specified origin, where \p origin is one of the DR_SEEK_*
values. Returns true if successful.
Flush all fragments containing any code from the region [\p start, \p start + \p size).
Once this routine returns no execution will occur out of the fragments flushed.
This routine may only be called during a clean call from the cache, from a nudge
event handler, or from a pre- or post-system call event handler.
It may not be called from any other event callback. No locks can
held when calling this routine. If called from a clean call, caller can NOT return
to the cache (the fragment that was called out of may have been flushed even if it
doesn’t apparently overlap the flushed region). Instead the caller must redirect
execution via dr_redirect_execution() (or DR_SIGNAL_REDIRECT from a signal callback)
after this routine to continue execution. Returns true if successful.
Printing to a file that won’t interfere with the
application’s own printing.
It is not buffered, which means that it should not be used for
very frequent, small print amounts: for that the client should either
do its own buffering or it should use printf from the C library
via DR’s private loader.
\note On Windows 7 and earlier, this routine is not able to print to STDOUT or
STDERR in the \p cmd window unless dr_enable_console_printing() is
called ahead of time, and even then there are limitations: see
dr_enable_console_printing().
\note This routine supports printing wide characters via the ls
or S format specifiers. On Windows, they are assumed to be UTF-16,
and are converted to UTF-8. On Linux, they are converted by simply
dropping the high-order bytes.
\note If the data to be printed is large it will be truncated to
an internal buffer size. Use dr_snprintf() and dr_write_file() for
large output.
\note On Linux this routine does not check for errors like EINTR. Use
dr_write_file() if that is a concern.
\note When printing floating-point values, the caller’s code should
use proc_save_fpstate() or be inside a clean call that
has requested to preserve the floating-point state, unless it can prove
that its compiler will not use x87 operations.
On success, the number of bytes written is returned.
On error, -1 is returned.
Takes in the \p perscxt opaque parameter passed to various
persistence events and returns whether the fragment identified by
\p tag is being persisted. This routine can be called outside of a
persistence event, in which case the \p perscxt parameter should be
NULL.
Frees a module_data_t returned by dr_module_iterator_next(), dr_lookup_module(),
dr_lookup_module_by_name(), or dr_copy_module_data(). \note Should NOT be used with
a module_data_t obtained as part of a module load or unload event.
Provides information about the app’s arguments by setting \p args_array up to
the count denoted by \p args_count. Therefore, \p args_count is not the size of the
buffer in bytes but the number of #dr_app_arg_t values that \p args_array can store.
Returns the number of args set or -1 on error.
Retrieve client registration information for a particular process for the current
user. If multiple clients are registered (alternative bitwidth clients are
considered separate), information on the highest-priority client is returned.
Retrieve client registration information for a particular process for the current
user. If multiple clients are registered (alternative bitwidth clients are
considered separate), information on the highest-priority client is returned.
Returns the client library name and path that were originally specified
to load the library. If the resulting string is longer than #MAXIMUM_PATH
it will be truncated. \p client_id is the client ID passed to a client’s
dr_client_main() function.
Returns in \p config_dir the configuration directory used to store config
files. In order to use local config files when the normal interactive user
home directory environment variable (HOME on Linux or MacOS; USERPROFILE on Windows)
is not set and when using one-step configure-and-run, call this routine prior
to creating the child process and pass true for \p alternative_local. For
multi-step, the caller must set the DYNAMORIO_CONFIGDIR environment variable
(in the child process) to point at the resulting \p config_dir.
Returns the current directory for this process in \p buf.
On Windows, reading the current directory is considered unsafe
except during initialization, as it is stored in user memory and
access is not controlled via any standard synchronization.
Get DR’s thread local storage segment base pointed at by \p tls_register.
It can be used to get the base of the thread-local storage segment
used by #dr_raw_tls_calloc.
Returns the error code of the last failed API routine. Users should check whether or
not the API routine that they just called has failed prior to calling this function.
Read the value of an integer DynamoRIO runtime option named \p option_name
into \p val. This includes boolean options. Options are listed in \ref
sec_options. DynamoRIO has many other undocumented options which may be
queried through this API, but they are not officially supported.
\warning Always pass a full uint64 for \p val even if the option is a smaller
integer to avoid overwriting nearby data.
\return false if no option named \p option_name exists, and true otherwise.
The decode and encode routines use a per-thread persistent flag that
indicates which processor mode to use. This routine returns the value of
that flag.
Returns the client-specific option string specified at client
registration, parsed into an array of \p argc separate option tokens
stored in \p argv. This is the same array of arguments passed
to the dr_client_main() routine.
Returns information in \p info about the symbol \p name exported
by the module \p lib. Returns false if the symbol is not found.
See the information in dr_get_proc_address() about what an
“exported” function is on Linux.
Returns the process id of the process associated with drcontext \p drcontext.
The returned value may be different from dr_get_process_id() if the passed context
was created in a different process, which may happen in thread exit callbacks.
Returns a pseudo-random number in the range [0..max).
The pseudo-random sequence can be repeated by passing the seed
used during a run to the next run via the -prng_seed runtime option.
Retrieves various statistics exported by DR as global, process-wide values.
The API is not thread-safe.
The caller is expected to pass a pointer to a valid, initialized #dr_stats_t
value, with the size field set (see #dr_stats_t).
Returns false if stats are not enabled.
Read the value of a string DynamoRIO runtime option named \p option_name into
\p buf. Options are listed in \ref sec_options. DynamoRIO has many other
undocumented options which may be queried through this API, but they are not
officially supported. The option value is truncated to \p len bytes and
null-terminated.
\return false if no option named \p option_name exists, and true otherwise.
Returns the user-controlled thread-local-storage field. To
generate an instruction sequence that reads the drcontext field
inline in the code cache, use dr_insert_read_tls_field().
Utility function that aids in tokenizing a string, such as a client
options string from dr_get_options(). The function scans \p str
until a non-whitespace character is found. It then starts copying
into \p buf until a whitespace character is found denoting the end
of the token. If the token begins with a quote, the token
continues (including across whitespace) until the matching end
quote is found. Characters considered whitespace are ’ ’, ‘\t’,
‘\r’, and ‘\n’; characters considered quotes are ‘\’’, ‘\“’, and
‘`’.
Allocates \p size bytes of memory from DR’s global memory pool.
This memory is only guaranteed to be aligned to the pointer size:
8 byte alignment for 64-bit; 4-byte alignment for 32-bit.
(The wrapped malloc() guarantees the more standard double-pointer-size.)
Identical to dr_insert_call() except it takes in \p encode_pc
indicating roughly where the call sequence will be encoded. If \p
callee is not reachable from \p encode_pc plus or minus one page,
an indirect call will be used instead of the direct call used by
dr_insert_call(). The indirect call overwrites the r11 register.
Assumes that \p instr is a near call.
Inserts into \p ilist prior to \p instr instruction(s) to call callee passing
two arguments:
-# address of call instruction (caller)
-# target address of call (callee)
\note Sets #DR_CLEANCALL_READS_APP_CONTEXT and #DR_CLEANCALL_WRITES_APP_CONTEXT.
Conditionally skipping the instrumentation inserted by this routine is not
supported (i.e., #DR_CLEANCALL_MULTIPATH is not supported here).
Assumes that \p instr is a conditional branch
Inserts into \p ilist prior to \p instr instruction(s) to call callee passing
three arguments:
-# address of branch instruction
-# target address of branch
-# 0 if the branch is not taken, 1 if it is taken
\note Sets #DR_CLEANCALL_READS_APP_CONTEXT and #DR_CLEANCALL_WRITES_APP_CONTEXT.
Conditionally skipping the instrumentation inserted by this routine is not
supported (i.e., #DR_CLEANCALL_MULTIPATH is not supported here).
Assumes that \p instr is a conditional branch
Inserts into \p ilist prior to \p instr instruction(s) to call callee passing
four arguments:
-# address of branch instruction
-# target address of branch
-# fall-through address of branch
-# 0 if the branch is not taken, 1 if it is taken
-# user defined operand (e.g., TLS slot, immed value, register, etc.)
\note The user defined operand cannot use register ebx!
\note Sets #DR_CLEANCALL_READS_APP_CONTEXT and #DR_CLEANCALL_WRITES_APP_CONTEXT.
Conditionally skipping the instrumentation inserted by this routine is not
supported (i.e., #DR_CLEANCALL_MULTIPATH is not supported here).
Inserts into \p ilist prior to \p where meta-instruction(s) to save state
for a call, switch to this thread’s DR stack, set up the passed-in
parameters, make a call to \p callee, clean up the parameters, and
then restore the saved state.
Identical to dr_insert_clean_call() except it takes in \p
save_flags which allows requests to not save certain state. This
is intended for use at application call entry points or other
contexts where a client is comfortable making assumptions. Keep in
mind that any register that is not saved will not be present in a
context obtained from dr_get_mcontext().
Insert code to get the segment base address pointed to by seg into
register reg. In Linux, it is only supported with -mangle_app_seg option.
In Windows, it only supports getting base address of the TLS segment.
Inserts enough OP_it instructions with proper parameters into \p
ilist to make all predicated instructions in \p ilist legal in
Thumb mode (#DR_ISA_ARM_THUMB). Treats predicated app and tool
instructions identically, but marks inserted OP_it instructions as
app instructions (see instr_set_app()).
Assumes that \p instr is an indirect branch.
Inserts into \p ilist prior to \p instr instruction(s) to call callee passing
two arguments:
-# address of branch instruction
-# target address of branch
\note Only the address portion of a far indirect branch is considered.
\note \p scratch_slot must be <= dr_max_opnd_accessible_spill_slot(). \p
scratch_slot is used internally to this routine and will be clobbered.
\note Sets #DR_CLEANCALL_READS_APP_CONTEXT and #DR_CLEANCALL_WRITES_APP_CONTEXT.
Conditionally skipping the instrumentation inserted by this routine is not
supported (i.e., #DR_CLEANCALL_MULTIPATH is not supported here).
Inserts into ilist prior to “where” instruction(s) to read into the
general-purpose full-size register \p reg from the raw TLS slot with offset
\p tls_offs from the TLS base \p tls_register.
Inserts into \p ilist prior to \p where meta-instruction(s) to read into the
general-purpose full-size register \p reg from the user-controlled drcontext
field for this thread. Reads from the same field as dr_get_tls_field().
Inserts into \p ilist prior to \p where meta-instruction(s) to restore the
x87 floating point state from the 16-byte-aligned buffer referred to by
buf, which must be 512 bytes for processors with the FXSR feature,
and 108 bytes for those without (where this routine does not
support 16-bit operand sizing). \p buf should have size of
OPSZ_512; this routine will automatically adjust it to OPSZ_108 if
necessary. \note proc_fpstate_save_size() can be used to determine
the particular size needed.
Inserts into \p ilist prior to \p where meta-instruction(s) to save the
x87 floating point state into the 16-byte-aligned buffer referred to by
\p buf, which must be 512 bytes for processors with the FXSR
feature, and 108 bytes for those without (where this routine does
not support 16-bit operand sizing). \p buf should have size of
OPSZ_512; this routine will automatically adjust it to OPSZ_108 if
necessary. \note proc_fpstate_save_size() can be used to determine
the particular size needed.
Insert code to set the value of register \p reg as the application value of
the register stolen by DynamoRIO
Reference \ref sec_reg_stolen for more information.
Assumes that \p instr is a direct, near, unconditional branch.
Inserts into \p ilist prior to \p instr instruction(s) to call callee passing
two arguments:
-# address of branch instruction
-# target address of branch
Inserts into ilist prior to “where” instruction(s) to store the value in the
general-purpose full-size register \p reg into the raw TLS slot with offset
\p tls_offs from the TLS base \p tls_register.
Inserts into \p ilist prior to \p where meta-instruction(s) to write the
general-purpose full-size register \p reg to the user-controlled drcontext field
for this thread. Writes to the same field as dr_set_tls_field().
Query whether detach is in progress. This is useful for clients that want to
avoid the cost of resetting their global state on exit if there is no
detaching and thus no chance of re-attaching.
Loads the library with the given path as an auxiliary client
library. The library is not treated as an application module but
as an extension of DR. The library will be included in
dr_memory_is_in_client() and any faults in the library will be
considered client faults. The bounds of the loaded library are
returned in the optional out variables. On failure, returns NULL.
Writes to DR’s log file for the thread with drcontext \p drcontext if the current
loglevel is >= \p level and the current \p logmask & \p mask != 0.
The mask constants are the DR_LOG_* defines below.
Logging is disabled for the release build.
If \p drcontext is NULL, writes to the main log file.
Looks up the module containing \p pc. If a module containing \p pc is found
returns a module_data_t describing that module. Returns NULL if \p pc is
outside all known modules, which is the case for most dynamically generated
code. Can be used to obtain a module_handle_t for dr_lookup_module_section()
or dr_get_proc_address() via the \p handle field inside module_data_t.
Looks up the module with name \p name ignoring case. If an exact name match is found
returns a module_data_t describing that module else returns NULL. User must call
dr_free_module_data() on the returned module_data_t once finished. Can be used to
obtain a module_handle_t for dr_get_proc_address().
\note Returned module_data_t must be freed with dr_free_module_data().
Loads \p filename as an executable file for examination, rather
than for execution. No entry point, initialization, or constructor
code is executed, nor is any thread-local storage or other
resources set up. Returns the size (which may include unmappped
gaps) in \p size. The return value of the function is the base
address at which the file is mapped.
Use this function to mark a region of code as safe for DR to suspend
the client while inside the region. DR will not relocate the client
from the region and will resume it at precisely the suspend point.
Returns true if the simd fields in dr_mcontext_t are valid xmm, ymm, or zmm values
(i.e., whether the underlying processor supports SSE).
\note If #DR_MC_MULTIMEDIA is not specified when calling dr_get_mcontext(),
the simd fields will not be filled in regardless of the return value
of this routine.
Returns true if the simd fields in dr_mcontext_t are valid zmm values
(i.e., whether the underlying processor and OS support AVX-512 and AVX-512 code
is present).
\note If #DR_MC_MULTIMEDIA is not specified when calling dr_get_mcontext(),
the simd fields will not be filled in regardless of the return value
of this routine.
Returns true iff pc is located inside a client library, an Extension
library used by a client, or an auxiliary client library (see
dr_load_aux_library()).
Checks to see that all bytes with addresses in the range [\p pc, \p pc + \p size - 1]
are readable and that reading from that range won’t generate an exception (see also
dr_safe_read() and DR_TRY_EXCEPT()).
\note Nothing guarantees that the memory will stay readable for any length of time.
\note On Linux, especially if the app is in the middle of loading a library
and has not properly set up the .bss yet, a page that seems readable can still
generate SIGBUS if beyond the end of an mmapped file. Use dr_safe_read() or
DR_TRY_EXCEPT() to avoid such problems.
Modifies the memory protections of the region from \p start through
\p start + \p size. Modification of memory allocated by DR or of
the DR or client libraries themselves is allowed under the
assumption that the client knows what it is doing. Modification of
the ntdll.dll library on Windows is not allowed. Returns true if
successful.
A convenience routine to aid restoring the arith flags done by outlined code,
such as when handling restore state events. The routine takes the current value of
the flags register \p cur_xflags, as well as the saved value \p saved_xflag, in order
to return the original app value.
Returns whether \p addr is contained inside any segment of the module \p data.
We recommend using this routine rather than checking against the \p start
and \p end fields of \p data, as modules are not always contiguous.
Advances the passed-in iterator and returns the current module import in the
iterator. The pointer returned is only valid until the next call to
dr_module_import_iterator_next() or dr_module_import_iterator_stop().
Retrieves the module_data_t for the next loaded module in the iterator. User must call
dr_free_module_data() on the returned module_data_t once finished.
\note Returned module_data_t must be freed with dr_free_module_data().
Initialize a new module iterator. The returned module iterator contains a snapshot
of the modules loaded at the time it was created. Use dr_module_iterator_hasnext()
and dr_module_iterator_next() to walk the loaded modules. Call
dr_module_iterator_stop() when finished to release the iterator. \note The iterator
does not prevent modules from being loaded or unloaded while the iterator is being
walked.
Set whether or not the module referred to by \p handle should be
instrumented. If \p should_instrument is false, code from the module will
not be passed to the basic block event. If traces are enabled, code from the
module will still reach the trace event. Must be called from the module load
event for the module referred to by \p handle.
\return whether successful.
Instructs DR to treat this lock as an application lock. Primarily
this avoids debug-build checks that no DR locks are held in situations
where locks are disallowed.
Allocates \p size bytes of memory as a separate allocation from DR’s
heap, allowing for separate protection.
The \p prot protection should use the DR_MEMPROT_READ,
DR_MEMPROT_WRITE, and DR_MEMPROT_EXEC bits.
When creating a region to hold dynamically generated code, use
this routine in order to create executable memory.
Triggers an asynchronous nudge event in the current process. The callback
function registered with dr_register_nudge_event() will be called with the
supplied \p argument (in a new non-application thread on Windows).
Triggers an asynchronous nudge event in a target process. The callback
function registered with dr_register_nudge_event() for the
specified client in the specified process will be called with the
supplied \p argument (in a new non-application thread on Windows).
Provides a mechanism for an external entity on the guest OS to
communicate with a client. Requires administrative privileges. A
process ‘nudge’ causes a client event handler to be invoked (use
dr_register_nudge_event() to register the handler function). A
nudge is ignored if the process is not running under DynamoRIO,
the specified client is not loaded, or if the client does not
provide a handler.
Opens the file \p fname. If no such file exists then one is created.
The file access mode is set by the \p mode_flags argument which is drawn from
the DR_FILE_* defines ORed together. Returns INVALID_FILE if unsuccessful.
Inserts into \p ilist prior to \p where meta-instruction(s) to save state for a call.
Stores the application state information on the DR stack.
Returns the size of the data stored on the DR stack (in case the caller
needs to align the stack pointer).
Intended to be called between dr_app_setup() and dr_app_start() to
pre-create code cache fragments for each basic block address in the
\p tags array. This speeds up the subsequent attach when
dr_app_start() is called.
If any code in the passed-in tags array is not readable, it is up to the
caller to handle any fault, as DR’s own signal handlers are not enabled
at this point.
Returns whether successful.
Intended to augment dr_prepopulate_cache() by populating DR’s indirect branch
tables, avoiding trips back to the dispatcher during initial execution. This is only
effective when one of the the runtime options -shared_trace_ibt_tables and
-shared_bb_ibt_tables (depending on whether traces are enabled) is turned on, as
this routine does not try to populate tables belonging to threads other than the
calling thread.
Stdout printing that won’t interfere with the
application’s own printing.
It is not buffered, which means that it should not be used for
very frequent, small print amounts: for that the client should either
do its own buffering or it should use printf from the C library
via DR’s private loader.
\note On Windows 7 and earlier, this routine is not able to print
to the \p cmd window
unless dr_enable_console_printing() is called ahead of time, and
even then there are limitations: see dr_enable_console_printing().
\note This routine supports printing wide characters via the ls
or S format specifiers. On Windows, they are assumed to be UTF-16,
and are converted to UTF-8. On Linux, they are converted by simply
dropping the high-order bytes.
\note If the data to be printed is large it will be truncated to
an internal buffer size. Use dr_snprintf() and dr_write_file() for
large output.
\note When printing floating-point values on x86, the caller’s code should
use proc_save_fpstate() or be inside a clean call that
has requested to preserve the floating-point state, unless it can prove
that its compiler will not use x87 operations.
An os neutral method for querying a memory address. Returns true
iff a memory region containing \p pc is found. If found additional
information about the memory region is returned in the optional out
arguments \p base_pc, \p size, and \p prot where \p base_pc is the
start address of the memory region continaing \p pc, \p size is the
size of said memory region and \p prot is an ORed combination of
DR_MEMPROT_* flags describing its current protection.
Provides additional information beyond dr_query_memory().
Returns true if it was able to obtain information (including about
free regions) and sets the fields of \p info. This routine can be
used to iterate over the entire address space. Such an iteration
should stop on reaching the top of the address space, or on
reaching kernel memory (look for #DR_MEMTYPE_ERROR_WINKERNEL) on
Windows.
Sets the program break to the specified value. Invokes the SYS_brk
system call and returns the result. This is the application’s
program break, so use this system call only when deliberately
changing the application’s behavior.
\note Linux-only.
Calls mremap with the specified parameters and returns the result.
The old memory must be non-DR memory, and the new memory is also
considered to be non-DR memory (see #DR_ALLOC_NON_DR).
\note Linux-only.
Allocates \p num_slots contiguous thread-local storage (TLS) slots that
can be directly accessed via an offset from \p tls_register.
If \p alignment is non-zero, the slots will be aligned to \p alignment.
These slots will be initialized to 0 for each new thread.
The slot offsets are [\p offset .. \p offset + (num_slots - 1)].
These slots are disjoint from the #dr_spill_slot_t register spill slots
and the client tls field (dr_get_tls_field()).
Returns whether or not the slots were successfully obtained.
The linear address of the TLS base pointed at by \p tls_register can be obtained
using #dr_get_dr_segment_base.
Raw TLs slots can be read directly using dr_insert_read_raw_tls() and written
using dr_insert_write_raw_tls().
Frees \p num_slots raw thread-local storage slots starting at
offset \p offset that were allocated with dr_raw_tls_calloc().
Returns whether or not the slots were successfully freed.
Can be used from a clean call or a restore_state_event (see
dr_register_restore_state_event()) to see the value saved in spill slot
\p slot by dr_save_reg().
Creates and initializes a recursive lock. A recursive lock allows
the same thread to acquire it multiple times. The lock
restrictions for mutexes apply (see dr_mutex_create()).
Instructs DR to treat this lock as an application lock. Primarily
this avoids debug-build checks that no DR locks are held in situations
where locks are disallowed.
Immediately resumes application execution from a clean call out of the cache (see
dr_insert_clean_call() or dr_prepare_for_call()) or an exception event with the
state specified in \p mcontext (including pc, and including the xmm fields
that are valid according to dr_mcontext_xmm_fields_valid()).
The flags field of \p context must contain DR_MC_ALL; using a partial set
of fields is not suported.
Returns an opnd_t that directly accesses the spill slot \p slot. Only slots
<= dr_max_opnd_accessible_spill_slot() can be used with this routine.
\note \p slot must be <= dr_max_opnd_accessible_spill_slot()
Registers a callback function for the basic block event. DR calls
\p func before inserting a new basic block into the code cache.
When adding a basic block to a new trace, DR calls \p func again
with \p for_trace set to true, giving the client the opportunity to
keep its same instrumentation in the trace, or to change it. The
original basic block’s instrumentation is unchanged by whatever
action is taken in the \p for_trace call.
Registers a callback function that is invoked whenever a clean call is inserted
in instrumentation, such as by dr_insert_clean_call(), dr_insert_clean_call_ex(),
or dr_insert_clean_call_ex_varg().
‘where’ is a label with note value #DR_NOTE_CLEAN_CALL_END; the clean call
sequence will be inserted prior to the label after all clean call callbacks
are finished (so the clean call sequence is not yet visible at the time this
callback is invoked).
Register a client for a particular process. Note that the process must first
be registered via dr_register_process() before calling this routine.
The #dr_config_client_t structure allows specifying additional options beyond
what dr_register_client() supports, such as an alternate bitwidth client.
For an alternate bitwidth client, the main client must first be
registered by an earlier call. Unregistering a client with
dr_unregister_client() will also unregister the alternate bitwidth
client.
Registers a callback function for the fragment deletion event. DR
calls \p func whenever it removes a fragment from the code cache.
Due to DR’s high-performance non-precise flushing, a fragment
can be made inaccessible but not actually freed for some time.
A new fragment can thus be created before the deletion event
for the old fragment is raised. We recommended using a counter
to ignore subsequent deletion events when using per-fragment
data structures and duplicate fragments are seen.
Registers a callback function for the end-trace event. DR calls \p
func before extending a trace with a new basic block. The \p func
should return one of the #dr_custom_trace_action_t enum values.
Registers a callback function for the process exit event. DR calls \p
func when the process exits. By default, the process exit event will be
executed with only a single live thread. dr_set_process_exit_behavior()
can provide superior exit performance for clients that have flexible
exit event requirements.
Registers a callback function for the syscall filter event. DR
calls \p func to decide whether to invoke the syscall events for
each system call site encountered with a statically-determinable
system call number. If \p func returns true, the pre-syscall
(dr_register_pre_syscall_event()) and post-syscall
(dr_register_post_syscall_event()) events will be invoked.
Otherwise, the events may or may not occur, depending on whether DR
itself needs to intercept them and whether the system call number
is statically determinable. System call number determination can
depend on whether the -opt_speed option is enabled. If a system
call number is not determinable, the filter event will not be
called, but the pre and post events will be called.
Sets the paths to the DynamoRIO library and the alternate-bitwidth DynamoRIO
library for a process that has already been registered via dr_register_process().
If this routine is not called, default library paths will be used which assume
a default path layout within the \p dr_root_dir passed to dr_register_process().
Registers a callback function for the kernel transfer event. DR
calls \p func whenever the kernel is about to directly transfer control
without an explicit user-mode control transfer instruction.
This includes the following scenarios, which are distinguished by \p type:
Registers a callback function for the low on memory event. DR calls \p func
whenever virtual memory is tight and enables the client to help free space.
Registers a callback function for the module load event. DR calls
\p func whenever the application loads a module (typically a
library but this term includes the executable). The \p loaded
parameter indicates whether the module is fully initialized by the
loader or in the process of being loaded. This parameter is present
only for backward compatibility: current versions of DR always pass true,
and the client can assume that relocating, rebinding, and (on Linux) segment
remapping have already occurred.
Registers a callback function for the module unload event. DR
calls \p func whenever the application unloads a module.
\note The module_data_t \p *info passed to
the callback routine is valid only for the duration of the callback
and should not be freed; a persistent copy can be made with
dr_copy_module_data().
Registers a callback function for nudge events. External entities
can nudge a process through the dr_nudge_process() or
dr_nudge_pid() drconfig API routines on Windows or using the \p
drnudgeunix tool on Linux. A client in this process can use
dr_nudge_client() to raise a nudge, while a client in another
process can use dr_nudge_client_ex().
Registers callback functions for storing read-only data in each persisted
cache file. When generating a new persisted cache file, DR first calls \p
func_size to obtain the size required for read-only data in each persisted
cache file. DR subsequently calls \p func_persist to write the actual data.
DR ensures that no other thread will execute in between the calls
to \p func_size and \p func_persist.
Registers callback functions for storing writable data in each persisted
cache file. When generating a new persisted cache file, DR first calls \p
func_size to obtain the size required for writable data in each persisted
cache file. DR subsequently calls \p func_persist to write the actual data.
DR ensures that no other thread will execute in between the calls
to \p func_size and \p func_persist.
Registers callback functions for storing executable code (outside of normal
code blocks) in each persisted cache file. When generating a new persisted
cache file, DR first calls \p func_size to obtain the size required for
executable code in each persisted cache file. DR subsequently calls \p
func_persist to write the actual code.
DR ensures that no other thread will execute in between the calls
to \p func_size and \p func_persist.
Registers a function which is called after all other threads have been taken over
during a process attach event, whether externally triggered or internally triggered
(via dr_app_start() or related functions). If this process instance was not
initiated by an attach or takeover methodology where multiple application threads may
exist at the time of takeover (such as a process newly created on Linux), this
registration function returns false.
Registers a callback function for the post-syscall event. DR calls
\p func whenever the application just finished invoking a system
call, if any client asked for that system call number to be
intercepted via the filter event
(dr_register_filter_syscall_event()) or if DR itself needs to
intercept the system call.
Any client registering a pre- or post-syscall event should also
register a filter event.
Registers a function which is called at the start of a full detach of DR from the
current process, whether externally triggered or internally triggered (via
dr_app_stop_and_cleanup() or related functions), as well as at the start of DR
sending all threads native but not cleaning up its own state (through dr_app_stop()).
Registers a callback function for the pre-syscall event. DR calls
\p func whenever the application is about to invoke a system call,
if any client asked for that system call number to be intercepted
via the filter event (dr_register_filter_syscall_event()).
Any client registering a pre- or post-syscall event should also
register a filter event.
Register a process to run under DynamoRIO.
Note that this routine only sets the base options to run a process
under DynamoRIO. To register one or more clients, call
dr_register_client() subsequently.
Registers a callback function for the machine state restoration event.
DR calls \p func whenever it needs to translate a code cache machine
context from the code cache to its corresponding original application
context. DR needs to translate when instructions fault in the cache as
well as when a suspended thread is examined or relocated for internal
purposes.
Requests that DR call the provided callback function \p func whenever a
signal is received by any application thread. The return value of \p
func determines whether DR delivers the signal to the application.
To redirect execution return DR_SIGNAL_REDIRECT (do not call
dr_redirect_execution() from a signal callback). The callback function
will be called even if the application has no handler or has registered
a SIG_IGN or SIG_DFL handler. If multiple callbacks are registered,
the first one that returns other than DR_SIGNAL_DELIVER will short-circuit
event delivery to later callbacks.
Registers a callback function for the thread exit event. DR calls
\p func whenever an application thread exits. The passed-in
drcontext should be used instead of calling
dr_get_current_drcontext(), as the thread exit event may be invoked
from other threads, and using dr_get_current_drcontext() can result
in failure to clean up the right resources, and at process exit
time it may return NULL.
Registers a callback function for the trace event. DR calls \p func
before inserting a new trace into the code cache. DR may call \p func
again if it needs to translate from code cache addresses back to
application addresses, which happens on faulting instructions as well as
in certain situations involving suspended threads or forcibly relocated
threads. The \p translating parameter distinguishes the two types of
calls and behaves identically to the same parameter in the basic
block callback: see #dr_register_bb_event() for further details.
Removes all OP_it instructions from \p ilist without changing the
instructions that were inside each IT block. This is intended to
be paired with dr_insert_it_instrs(), where a client’s examination
of the application instruction list and insertion of
instrumentation occurs in between the two calls and thus does not
have to worry about groups of instructions that cannot be separated
or changed. The resulting predicated instructions are not
encodable in Thumb mode (#DR_ISA_ARM_THUMB): dr_insert_it_instrs()
must be called before encoding.
Renames the file \p src to \p dst, replacing an existing file named \p dst if
\p replace is true.
Atomic if \p src and \p dst are on the same filesystem.
Returns true if successful.
Replaces the fragment with tag \p tag with the instructions in \p
ilist. This routine is only valid with the -thread_private option;
it replaces the fragment for the current thread only. After
replacement, the existing fragment is allowed to complete if
currently executing. For example, a clean call replacing the
currently executing fragment will safely return to the existing
code. Subsequent executions will use the new instructions.
Inserts into \p ilist prior to \p where meta-instruction(s) to restore the 6
arithmetic flags, assuming they were saved using dr_save_arith_flags() with
slot \p slot and that xax holds the same value it did after the save.
Inserts into \p ilist prior to \p where meta-instruction(s) to restore
the arithmetic flags (6 arithmetic flags on X86 or APSR on ARM) from \p reg.
The caller must ensure that \p reg contains the program status flags,
most likely from dr_save_arith_flags_to_reg().
Inserts into \p ilist prior to \p where meta-instruction(s) to restore the 6
arithmetic flags from xax. This currently uses DynamoRIO’s “add $0x7f %al ;
sahf” code sequence, which is faster and easier than popf. The caller must
ensure that xax contains the arithmetic flags, most likely from
dr_save_arith_flags_to_xax().
\note X86-only
Inserts into \p ilist prior to \p where meta-instruction(s) to restore the
register \p reg from the spill slot \p slot. See dr_save_reg() for notes on
lifetime and alternative access to spill slots.
May only be used after invoking dr_suspend_all_other_threads(). This
routine resumes the threads that were suspended by
dr_suspend_all_other_threads() and must be passed the same array and
count of suspended threads that were returned by
dr_suspend_all_other_threads(). It also frees the \p drcontexts array
and releases the locks acquired by dr_suspend_all_other_threads(). The
return value indicates whether all resumption attempts were successful.
Causes the thread owning \p drcontext to begin executing in the
code cache again once it is resumed. The thread must currently be
suspended (typically by dr_suspend_all_other_threads_ex() with
#DR_SUSPEND_NATIVE) and must be currently native (typically from
#DR_EMIT_GO_NATIVE). \return whether successful.
Returns false if DynamoRIO is being used as a “regular” standalone library
(see dr_standalone_init() and \ref page_standalone).
Returns true if DynamoRIO is controlling the application by running
its code through a software code cache.
Creates and initializes a read-write lock. A read-write lock allows
multiple readers or alternatively a single writer. The lock
restrictions for mutexes apply (see dr_mutex_create()).
Instructs DR to treat this lock as an application lock. Primarily
this avoids debug-build checks that no DR locks are held in situations
where locks are disallowed.
Safely reads \p size bytes from address \p base into buffer \p
out_buf. Reading is done without the possibility of an exception
occurring. Returns true if the entire \p size bytes were read;
otherwise returns false and if \p bytes_read is non-NULL returns the
partial number of bytes read in \p bytes_read.
\note See also DR_TRY_EXCEPT().
Safely writes \p size bytes from buffer \p in_buf to address \p
base. Writing is done without the possibility of an exception
occurring. Returns true if the entire \p size bytes were written;
otherwise returns false and if \p bytes_written is non-NULL returns the
partial number of bytes written in \p bytes_written.
\note See also DR_TRY_EXCEPT().
Inserts into \p ilist prior to \p where meta-instruction(s) to save the 6
arithmetic flags into xax after first saving xax to the spill slot \p slot.
This is equivalent to dr_save_reg() of xax to \p slot followed by lahf and
seto al instructions. See dr_restore_arith_flags().
Inserts into \p ilist prior to \p where meta-instruction(s) to save the
arithmetic flags (6 arithmetic flags on X86 or APSR on ARM) into \p reg.
If the caller wishes to use \p reg between saving and restoring these flags,
they must save and restore \p reg, potentially using dr_save_reg()/dr_restore_reg().
If the caller needs to save both the current value of \p reg and the flags stored
to \p reg by this routine, they must use separate spill slots, or they will
overwrite the original \p reg value in memory.
Inserts into \p ilist prior to \p where meta-instruction(s) to save the 6
arithmetic flags into xax. This currently uses DynamoRIO’s “lahf ; seto al”
code sequence, which is faster and easier than pushf. If the caller wishes
to use xax between saving and restoring these flags, they must save and
restore xax, potentially using dr_save_reg()/dr_restore_reg(). If the caller
needs to save both the current value of xax and the flags stored to xax by
this routine, they must use separate spill slots, or they will overwrite the
original xax value in memory.
\note X86-only
Inserts into \p ilist prior to \p where meta-instruction(s) to save the
register \p reg in the spill slot \p slot. See dr_restore_reg(). Use
dr_read_saved_reg() and dr_write_saved_reg() to access spill slots from clean
calls and restore_state_events (see dr_register_restore_state_event()).
\note The stored value remains available only until the next non-meta (i.e.
application) instruction. Use dr_insert_write_tls_field() and
dr_insert_read_tls_field() for a persistent (but more costly to access)
thread-local-storage location. See also dr_raw_tls_calloc().
Sets information presented to users in diagnostic messages.
Only one name is supported, regardless of how many clients are in use.
If this routine is called a second time, the new values supersede
the original.
The \p report_URL is meant to be a bug tracker location where users
should go to report errors in the client end-user tool.
Sets the version string presented to users in diagnostic messages.
This has a maximum length of 96 characters; anything beyond that is
silently truncated.
The decode and encode routines use a per-thread persistent flag that
indicates which processor mode to use. This routine sets that flag to the
indicated value and optionally returns the old value. Be sure to restore the
old value prior to any further application execution to avoid problems in
mis-interpreting application code.
Specifies how process exit should be handled with respect to thread exit
events and thread synchronization in release build. In debug build, and
in release build by default, all threads are always synchronized at exit
time, resulting in a single-threaded process exit event, and all thread
exit event callbacks are always called. This routine can provide more
performant exits in release build by avoiding the synchronization if the
client is willing to skip thread exit events at process exit and is
willing to execute its process exit event with multiple live threads.
Sets the user-controlled thread-local-storage field. To
generate an instruction sequence that reads the drcontext field
inline in the code cache, use dr_insert_write_tls_field().
AArch64 Scalable Vector Extension’s vector length in bits is one of:
128 256 384 512 640 768 896 1024 1152 1280 1408 1536 1664 1792 1920 2048RISC-V Vector Extension’s vector length in bit is from 64 to 65536 in the
power of 2.
Returns whether successful.
TODO i#3044: This function will only allow setting vector length if not
running on SVE or RVV.
Utility routine to print a formatted message to a string. Will not
print more than max characters. If successful, returns the number
of characters printed, not including the terminating null
character. If the number of characters to write equals max, then
the caller is responsible for supplying a terminating null
character. If the number of characters to write exceeds max, then
max characters are written and -1 is returned. If an error
occurs, a negative value is returned.
\note This routine supports printing wide characters via the ls
or S format specifiers. On Windows, they are assumed to be UTF-16,
and are converted to UTF-8. On Linux, they are converted by simply
dropping the high-order bytes.
\note When printing floating-point values, the caller’s code should
use proc_save_fpstate() or be inside a clean call that
has requested to preserve the floating-point state, unless it can prove
that its compiler will not use x87 operations..
Wide character version of dr_snprintf(). All of the comments for
dr_snprintf() apply, except for the hs or S format specifiers.
On Windows, these will assume that the input is UTF-8, and will
convert to UTF-16. On Linux, they will widen a single-byte
character string into a wchar_t character string with zero as the
high-order bytes.
Suspends all other threads in the process and returns an array of
contexts in \p drcontexts with one context per successfully suspended
thread. The contexts can be passed to routines like dr_get_thread_id()
or dr_get_mcontext(). However, the contexts may not be modified:
dr_set_mcontext() is not supported. dr_get_mcontext() can be called on
the caller of this routine, unless in a Windows nudge callback.
Inserts into \p ilist prior to \p where meta-instruction(s) to save the current
esp and switch to this thread’s DR stack.
\note The DR stack is limited to 20KB by default; this can be changed with
the -stack_size DR runtime parameter. This stack cannot be used to store
state that persists beyond a single clean call, code cache execution,
or probe callback function execution.
Swaps to the application version of any system state for the given
thread. This is meant to be used prior to examining application
memory, when private libraries are in use and there are two
versions of system state. Invoking non-DR library routines while
the application state is in place can lead to unpredictable
results: call dr_switch_to_dr_state() (or the _ex version) before
doing so.
Should only be called after calling dr_switch_to_app_state() (or
the _ex version), or in certain cases where a client is running its
own code in an application state. Swaps from the application
version of system state for the given thread back to the DR and
client version.
Returns the next exported symbol. The returned pointer is valid until the
next call to dr_symbol_export_iterator_next() or
dr_symbol_export_iterator_stop().
Creates an iterator over symbols exported by a module.
The iterator returned is invalid until after the first call to
dr_symbol_export_iterator_next().
Returns the next imported symbol. The returned pointer is valid until the
next call to dr_symbol_import_iterator_next() or
dr_symbol_import_iterator_stop().
Creates an iterator over symbols imported by a module. If \p from_module is
NULL, all imported symbols are yielded, regardless of which module they were
imported from.
Usable only from a post-syscall (dr_register_post_syscall_event())
event. Returns the return value of the system call that will be
presented to the application.
Usable only from a post-syscall (dr_register_post_syscall_event())
event. Returns whether it successfully retrieved the results
of the system call into \p info.
Usable only from a post-syscall (dr_register_post_syscall_event())
event. An additional system call will be invoked immediately,
using the current values of the parameters, which can be set with
dr_syscall_set_param(). The system call to be invoked should be
specified with dr_syscall_set_sysnum().
Usable only from a pre-syscall (dr_register_pre_syscall_event())
event, or from a post-syscall (dr_register_post_syscall_event())
event when also using dr_syscall_invoke_another(). Sets the value
of system call parameter number \p param_num to \p new_value.
Usable only from a pre-syscall (dr_register_pre_syscall_event()) or
post-syscall (dr_register_post_syscall_event()) event.
For pre-syscall, should only be used when skipping the system call.
This sets the return value of the system call that the application sees
to \p value.
Usable only from a pre-syscall (dr_register_pre_syscall_event()) or
post-syscall (dr_register_post_syscall_event()) event.
For pre-syscall, should only be used when skipping the system call.
Usable only from a pre-syscall (dr_register_pre_syscall_event())
event, or from a post-syscall (dr_register_post_syscall_event())
event when also using dr_syscall_invoke_another(). Sets the system
call number of the system call about to be invoked to \p new_num.
Allocates \p size bytes of memory from DR’s memory pool specific to the
thread associated with \p drcontext.
This memory is only guaranteed to be aligned to the pointer size:
8 byte alignment for 64-bit; 4-byte alignment for 32-bit.
(The wrapped malloc() guarantees the more standard double-pointer-size.)
Should be called during process initialization. Requests more accurate
tracking of the #dr_where_am_i_t value for use with dr_where_am_i(). By
default, if this routine is not called, DR avoids some updates to the value
that incur extra overhead, such as identifying clean callees.
Flush all fragments containing any code from the region [\p start, \p start + \p size).
Control will not enter a fragment containing code from the region after this returns,
but a thread already in such a fragment will finish out the fragment. This includes
the current thread if this is called from a clean call that returns to the cache.
This routine may only be called during a clean call from the cache, from a nudge
event handler, or from a pre- or post-system call event handler.
It may not be called from any other event callback. No locks can be
held when calling this routine. Returns true if successful.
Unregister a callback function for the basic block event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the fragment deletion event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the end-trace event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the process exit event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the syscall filter event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the fork event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the kernel transfer event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for low on memory events.
\return true if unregistration is successful and false if it is not
(e.g., the function was not registered).
Unregister a callback for the module load event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the module unload event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the nudge event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for patching persisted code.
\return true if unregistration is successful and false if it is not
(e.g., the function was not registered).
Unregister callback functions for storing read-only data in a persisted cache file.
\return true if unregistration is successful and false if it is not
(e.g., one of the functions was not registered).
Unregister callback functions for storing writable data in a persisted cache file.
\return true if unregistration is successful and false if it is not
(e.g., one of the functions was not registered).
Unregister callback functions for storing executable code in a persisted cache file.
\return true if unregistration is successful and false if it is not
(e.g., one of the functions was not registered).
Unregister a callback function for the post-attach event (see
dr_register_post_attach_event()). \return true if unregistration is successful and
false if it is not (e.g., \p func was not registered).
Unregister a callback function for the post-syscall event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the post-attach event (see
dr_register_pre_detach_event()). \return true if unregistration is successful and
false if it is not (e.g., \p func was not registered).
Unregister a callback function for the pre-syscall event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the machine state restoration event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the machine state restoration
event with extended ifnormation. \return true if unregistration is
successful and false if it is not (e.g., \p func was not
registered).
Unregister a callback function for the signal event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the thread exit event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the thread initialization event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Unregister a callback function for the trace event.
\return true if unregistration is successful and false if it is not
(e.g., \p func was not registered).
Returns whether the given thread indicated by \p drcontext
is currently using the application version of its system state.
\sa dr_switch_to_dr_state(), dr_switch_to_app_state().
Returns the #dr_where_am_i_t value indicating in which area of code \p pc
resides. This is meant for use with dr_set_itimer() for PC sampling for
profiling purposes. If the optional \p tag is non-NULL and \p pc is inside a
fragment in the code cache, the fragment’s tag is returned in \p tag. It is
recommended that the user of this routine also call dr_track_where_am_i()
during process initialization for more accurate results.
Can be used from a clean call to modify the value saved in the spill slot
\p slot by dr_save_reg() such that a later dr_restore_reg() will see the
new value.
Checks \p fname for the permssions specified by \p mode for the
current effective user. If \p fname is a directory and \p mode includes \p
DRFRONT_WRITE, this function additionally attempts to create a
temporary file (by calling drfront_dir_try_writable()) to ensure
that the filesystem is not mounted read-only.
On Linux or Mac, if the current effective user is 0, this routine assumes
that the user has read and write access to every file and has execute
access to any file with at least one execute bit set.
If a tool is installed into a “Program Files” directory on Windows,
or into “/usr/…” on Linux, it needs to store its log files
elsewhere. This utility function helps to select that alternative
location. First, it checks whether \p root is in a location where
log files should not be created, and returns that result in \p
use_root. If \p use_root is false, this function returns a
suggested alternative directory for log files in \p buf. It looks
in standard locations such as “$APPDATA” or
“$USERPROFILE/Application Data” on Windows or in temp directories
if those fail or if on Linux. It appends \p subdir to the base
application data or temp directory. It is up to the caller to
create the returned directory if it does not exist.
This routine tries to fetch all missed symbols for module specified in \p modpath
using _NT_SYMBOL_PATH environment var. User should call \p drfront_sym_init,
drfront_sym_set_search_path() and drfront_sym_set_search_path() before calling
this routine. If success function returns full path to fetched symbol file in
\p symbol_path.
Sets the environment variable _NT_SYMBOL_PATH and the dbghelp
search path for symbol lookup in a client, without any network
symbol server component (such components are unsafe in a client).
Sets the symbol search path for this frontend process to the specified value.
Typically this would be used with the output value from
drfront_set_client_symbol_search_path().
Sets the verbosity level for additional diagnostics from the drfrontendlib
library. The default level is 0 which is quiet. Diagnostics are printed
to stderr.
This routine initializes the symbol handler for the current process. Should be called
before drfront_set_symbol_search_path() and drfront_fetch_module_symbols().
Allocates \p num_bytes of memory for \p instr’s raw bits.
If \p instr currently points to raw bits, the allocated memory is
initialized with the bytes pointed to.
\p instr is then set to point to the allocated memory.
Returns a copy of \p orig with separately allocated memory for
operands and raw bytes if they were present in \p orig.
Only a shallow copy of the \p note field is made. The \p label_cb
field will not be copied at all if \p orig is a label instruction.
Given \p eflags, returns whether or not the conditional move
instruction \p instr would execute the move. The conditional move
can be an OP_cmovcc or an OP_fcmovcc instruction.
Returns NULL if none of \p instr’s operands is a memory reference.
Otherwise, returns the effective address of the first memory operand
when the operands are considered in this order: destinations and then
sources. The address is computed using the passed-in registers.
\p mc->flags must include DR_MC_CONTROL and DR_MC_INTEGER.
For instructions that use vector addressing (VSIB, introduced in AVX2),
mc->flags must additionally include DR_MC_MULTIMEDIA.
Performs address calculation in the same manner as
instr_compute_address() but handles multiple memory operands. The
\p index parameter should be initially set to 0 and then
incremented with each successive call until this routine returns
false, which indicates that there are no more memory operands. The
address of each is computed in the same manner as
instr_compute_address() and returned in \p addr; whether it is a
write is returned in \p is_write. Either or both OUT variables can
be NULL.
\p mc->flags must include DR_MC_CONTROL and DR_MC_INTEGER.
For instructions that use vector addressing (x86 VSIB, introduced in AVX2, or
AArch64 scatter/gather instructions introduced in SVE/SVE2),
mc->flags must additionally include DR_MC_MULTIMEDIA.
Performs address calculation in the same manner as
instr_compute_address_ex() with additional information
of which opnd is used for address computation returned
in \p pos. If \p pos is NULL, it is the same as
instr_compute_address_ex().
Assumes that instr is a meta instruction (instr_is_meta())
and an instr_is_cti_short() (<=8-bit reach). Converts instr’s opcode
to a long form (32-bit reach for x86). If instr’s opcode is OP_loop* or
OP_jecxz for x86 or OP_cbnz or OP_cbz for ARM, converts it to a sequence of
multiple instructions (which is different from instr_is_cti_short_rewrite()).
Each added instruction is marked instr_is_meta().
Returns the long form of the instruction, which is identical to \p instr
unless \p instr is OP_{loop*,jecxz,cbnz,cbz}, in which case the return value
is the final instruction in the sequence, the one that has long reach.
\note DR automatically converts app short ctis to long form.
Converts a real ISA (e.g., #DR_ISA_AMD64) instruction \p instr_real_isa into a
#DR_ISA_REGDEPS instruction and stores it into \p instr_regdeps_isa.
Assumes \p instr_regdeps_isa has been allocated by the caller (e.g., using
instr_create()).
Assumes \p instr_real_isa is a fully-decoded or synthesized instruction of a real ISA
with valid operand information.
\note \p instr_regdeps_isa will contain only the information of a #DR_ISA_REGDEPS
synthetic instruction.
Returns an initialized instr_t allocated on the thread-local heap.
Sets the x86/x64 mode of the returned instr_t to the mode of dcontext.
The instruction should be de-allocated with instr_destroy(), which
will be called automatically if this instruction is added to the instruction
list passed to the basic block or trace events.
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode and three sources
(\p src1, \p src2, \p src3).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode and four sources
(\p src1, \p src2, \p src3, \p src4).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, one destination(\p dst),
and one source (\p src).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, one destination (\p dst),
and two sources (\p src1, \p src2).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, one destination (\p dst),
and three sources (\p src1, \p src2, \p src3).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, one destination (\p dst),
and four sources (\p src1, \p src2, \p src3, \p src4).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, one destination (\p dst),
and five sources (\p src1, \p src2, \p src3, \p src4, \p src5).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, one destination (\p dst),
and six sources (\p src1, \p src2, \p src3, \p src4, \p src5, \p src6).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, two destinations (\p dst1, \p dst2)
and no sources.
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, two destinations (\p dst1, \p dst2)
and one source (\p src).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, two destinations (\p dst1, \p dst2)
and two sources (\p src1, \p src2).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, two destinations (\p dst1, \p dst2)
and three sources (\p src1, \p src2, \p src3).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, two destinations (\p dst1, \p dst2)
and four sources (\p src1, \p src2, \p src3, \p src4).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, two destinations (\p dst1, \p dst2)
and five sources (\p src1, \p src2, \p src3, \p src4, \p src5).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, three destinations
(\p dst1, \p dst2, \p dst3) and no sources.
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, three destinations
(\p dst1, \p dst2, \p dst3) and two sources
(\p src1, \p src2).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, three destinations
(\p dst1, \p dst2, \p dst3) and three sources
(\p src1, \p src2, \p src3).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, three destinations
(\p dst1, \p dst2, \p dst3) and four sources
(\p src1, \p src2, \p src3, \p src4).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, three destinations
(\p dst1, \p dst2, \p dst3) and five sources
(\p src1, \p src2, \p src3, \p src4, \p src5).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, three destinations
(\p dst1, \p dst2, \p dst3) and six sources
(\p src1, \p src2, \p src3, \p src4, \p src5, \p src6).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, four destinations
(\p dst1, \p dst2, \p dst3, \p dst4) and 1 source (\p src).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, four destinations
(\p dst1, \p dst2, \p dst3, \p dst4) and 2 sources (\p src1 and \p src2).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, four destinations
(\p dst1, \p dst2, \p dst3, \p dst4) and 3 sources
(\p src1, \p src2 and \p src3).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, four destinations
(\p dst1, \p dst2, \p dst3, \p dst4) and four sources
(\p src1, \p src2, \p src3, \p src4).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, four destinations
(\p dst1, \p dst2, \p dst3, \p dst4) and five sources
(\p src1, \p src2, \p src3, \p src4, \p src5).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, five destinations
(\p dst1, \p dst2, \p dst3, \p dst4, \p dst5) and five sources
(\p src1, \p src2, \p src3).
Convenience routine that returns an initialized instr_t allocated
on the thread-local heap with opcode \p opcode, five destinations
(\p dst1, \p dst2, \p dst3, \p dst4, \p dst5) and five sources
(\p src1, \p src2, \p src3, \p src4).
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, \p fixed_dsts plus \p var_dsts
destination operands, and \p fixed_srcs source operands. The variable
arguments must start with the fixed destinations, followed by the (fixed)
sources, followed by the variable destinations. The \p var_ord parameter
specifies the (0-based) ordinal position within the resulting instruction’s
destination array at which the variable destinations should be placed,
allowing them to be inserted in the middle of the fixed destinations.
Convenience routine that returns an initialized instr_t allocated on the
thread-local heap with opcode \p opcode, \p fixed_dsts destination operands,
and \p fixed_srcs plus \p var_srcs source operands. The variable arguments
must start with the (fixed) destinations, followed by the fixed sources,
followed by the variable sources. The \p var_ord parameter specifies the
(0-based) ordinal position within the resulting instruction’s source array
at which the variable sources should be placed, allowing them to be inserted
in the middle of the fixed sources.
Prints the instruction \p instr to file \p outfile.
Does not print address-size or data-size prefixes for other than
just-decoded instrs, and does not check that the instruction has a
valid encoding. Prints each operand with leading zeros indicating
the size.
The default is to use DR’s custom syntax (see disassemble_set_syntax()).
Prints the instruction \p instr to the buffer \p buf.
Always null-terminates, and will not print more than \p bufsz characters,
which includes the final null character.
Returns the number of characters printed, not including the final null.
Encodes \p instr into the memory at \p pc.
Uses the x86/x64 mode stored in instr, not the mode of the current thread.
Returns the pc after the encoded instr, or NULL if the encoding failed.
If instr is a cti with an instr_t target, the offset fields of instr and
of the target must be set with the respective offsets of each instr_t!
(instrlist_encode does this automatically, if the target is in the list).
x86 instructions can occupy up to 17 bytes, so the caller should ensure
the target location has enough room to avoid overflow.
\note: In Thumb mode, some instructions have different behavior depending
on whether they are in an IT block. To correctly encode such instructions,
they should be encoded within an instruction list with the corresponding
IT instruction using instrlist_encode().
Encodes \p instr into the memory at \p copy_pc in preparation for copying
to \p final_pc. Any pc-relative component is encoded as though the
instruction were located at \p final_pc. This allows for direct copying
of the encoded bytes to \p final_pc without re-relativization.
Deallocates all memory that was allocated by \p instr. This
includes raw bytes allocated by instr_allocate_raw_bits() and
operands allocated by instr_set_num_opnds(). Does not deallocate
the storage for \p instr itself (use instr_destroy() instead if
\p instr was created with instr_create()).
Given an #instr_noalloc_t where all operands are included, returns
an #instr_t pointer corresponding to that no-alloc structure suitable for
passing to instruction API functions.
Returns \p instr’s arithmetic flags (bottom 6 eflags) use as EFLAGS_
constants (e.g., EFLAGS_READ_CF, EFLAGS_WRITE_OF, etc.) or’ed together.
If \p instr’s eflags behavior has not been calculated yet or is
invalid, the entire eflags use is calculated and returned (not
just the arithmetic flags).
Which eflags are considered to be accessed for conditionally executed
instructions are controlled by \p flags.
Returns \p instr’s set of categories (set of DR_INSTR_CATEGORY_ constants).
See #dr_instr_category_t.
This API is only supported for decoded instructions, not for synthetic ones.
Currently this is only supported for AArch64.
Returns \p instr’s eflags use as EFLAGS_ constants (e.g., EFLAGS_READ_CF,
EFLAGS_WRITE_OF, etc.) or’ed together.
Which eflags are considered to be accessed for conditionally executed
instructions are controlled by \p flags.
Assumes that \p instr’s opcode is OP_int and that either \p instr’s
operands or its raw bits are valid.
Returns the first source operand if \p instr’s operands are valid,
else if \p instr’s raw bits are valid returns the first raw byte.
\return a pointer to user-controlled data fields in a label instruction.
These fields are available for use by clients for their own purposes.
Returns NULL if \p instr is not a label instruction.
\note These data fields are copied (shallowly) across instr_clone().
Returns the next instr_t in the instrlist_t that contains \p instr.
\note The next pointer for an instr_t is inside the instr_t data
structure itself, making it impossible to have on instr_t in
two different InstrLists (but removing the need for an extra data
structure for each element of the instrlist_t).
Returns the eflags usage of instructions with opcode \p opcode,
as EFLAGS_ constants (e.g., EFLAGS_READ_CF, EFLAGS_WRITE_OF, etc.) or’ed
together.
If \p opcode is predicated (see instr_is_predicated()) or if the set
of flags read or written varies with an operand value, this routine
returns the maximal set that might be accessed or written.
Assumes that \p instr’s raw bits are valid.
Returns a pointer to \p instr’s raw bits.
\note A freshly-decoded instruction has valid raw bits that point to the
address from which it was decoded. However, for instructions presented
in the basic block or trace events, use instr_get_app_pc() to retrieve
the corresponding application address, as the raw bits will not be set
for instructions added after decoding, and may point to a different location
for insructions that have been modified.
If any of \p instr’s destination operands is a rip-relative data memory
reference, returns the operand position. If there is no such
destination operand, returns -1.
If any of \p instr’s operands is a rip-relative data or instruction
memory reference, returns the address that reference targets. Else
returns false. For instruction references, only PC operands are
considered: not instruction pointer operands.
Each instruction may store a hint for how the instruction should be encoded if
redundant encodings are available. This presumes that the user knows that a
redundant encoding is available. This routine returns whether the \p hint is set
for \p instr.
Initializes \p instr.
Sets the x86/x64 mode of \p instr to the mode of dcontext.
When finished with it, the instruction’s internal memory should be freed
with instr_free(), or instr_reset() for reuse.
Assumes that \p instr is a conditional branch instruction
Reverses the logic of \p instr’s conditional
e.g., changes OP_jb to OP_jnb.
Works on cti_short_rewrite as well.
Returns true iff \p instr is a conditional branch: OP_jcc, OP_jcc_short,
OP_loop*, or OP_jecxz on x86; OP_cbnz, OP_cbz, or when a predicate is present
any of OP_b, OP_b_short, OP_bx, OP_bxj, OP_bl, OP_blx, OP_blx_ind on ARM.
Returns true iff \p instr is a control transfer instruction that takes an
8-bit offset on x86 (OP_loop*, OP_jecxz, OP_jmp_short, or OP_jcc_short) or
a small offset on ARM (OP_cbz, OP_cbnz, OP_b_short).
/
/**
This routine does NOT try to decode an opcode in a Level 1 or Level
0 routine, and can thus be called on Level 0 routines. Levels are not exposed
in the API anymore, however.
Returns true iff \p instr’s opcode is OP_loop* or OP_jecxz on x86
or OP_cbz or OP_cbnz on ARM and instr has
been transformed to a sequence of instruction that will allow a larger
offset.
If \p pc != NULL, \p pc is expected to point to the beginning of the encoding of
\p instr, and the following instructions are assumed to be encoded in sequence
after \p instr.
Otherwise, the encoding is expected to be found in \p instr’s allocated bits.
/
/**
This routine does NOT try to decode an opcode in a Level 1 or Level
0 routine, and can thus be called on Level 0 routines. Levels are not exposed
in the API anymore, however.
Returns true iff \p instr is a conditional branch, unconditional branch,
or indirect branch with a program address target (NOT an instr_t address target)
and \p instr is ok to mangle.
Returns true iff \p instr is a far control transfer instruction: OP_jmp_far,
OP_call_far, OP_jmp_far_ind, OP_call_far_ind, OP_ret_far, or OP_iret, on x86.
Returns true iff \p instr is a floating point instruction.
@param[in] instr The instruction to query
@param[out] type If the return value is true and \p type is
non-NULL, the type of the floating point operation is written to \p type.
\deprecated Prefer instr_is_floating_type() which uses the more general
#dr_instr_category_t.
Returns true iff \p instr is a floating point instruction.
@param[in] instr The instruction to query
@param[out] type If the return value is true and \p type is
non-NULL, the type of the floating point operation is written to \p type.
Returns true iff \p instr is a multi-way (indirect) branch: OP_jmp_ind,
OP_call_ind, OP_ret, OP_jmp_far_ind, OP_call_far_ind, OP_ret_far, or
OP_iret on x86; OP_bx, OP_bxj, OP_blx_ind, or any instruction with a
destination register operand of DR_REG_PC on ARM.
Tries to identify common cases of moving a constant into either a
register or a memory address.
Returns true and sets \p *value to the constant being moved for the following
cases: OP_mov_imm, OP_mov_st, and OP_xor where the source equals the
destination, for x86; OP_mov, OP_movs, OP_movw, OP_mvn, OP_mvns, or OP_eor
where the sources equal the destination and there is no shift, for ARM.
If \p store_instr is not a store (instr_writes_memory() returns false), returns
false. If \p store_instr is a store (instr_writes_memory() returns true), returns
whether its source operand with index \p source_ordinal (as passed to
instr_get_src()) is a source for the value that is stored. (If not, it may be an
address register that is updated for pre-index or post-index writeback forms, or
some other source that does not directly affect the value written to memory.)
Returns whether \p instr is a register spill or restore, whether it was
created by dr_save_reg(), dr_restore_reg(), dr_insert_read_raw_tls(),
dr_insert_write_raw_tls(), routines that call the aforementioned routines
(e.g., dr_save_arith_flags()), or DR’s own internal spills and restores.
Returns information about the spill/restore in the OUT parameters.
The returned \p offs is the raw offset in bytes from the TLS segment base,
the stolen register base, or the thread-private context area.
Returns true iff \p instr is used to implement system calls: OP_int with a
source operand of 0x80 on linux or 0x2e on windows, or OP_sysenter,
or OP_syscall, or #instr_is_wow64_syscall() for WOW64.
Returns the length of \p instr.
As a side effect, if instr_is_app(instr) and \p instr’s raw bits
are invalid, encodes \p instr into bytes allocated with
instr_allocate_raw_bits(), after which instr is marked as having
valid raw bits.
Calling this function with \p instr makes it safe to keep the
instruction around indefinitely when its raw bits point into the
cache. The function allocates memory local to \p instr to hold a
copy of the raw bits. If this was not done, the original raw bits
could be deleted at some point. Making an instruction persistent
is necessary if you want to keep it beyond returning from the call
that produced the instruction.
Calculates the size, in bytes, of the memory read or write of \p instr.
If \p instr does not reference memory, or is invalid, returns 0.
If \p instr is a repeated string instruction, considers only one iteration.
If \p instr uses vector addressing (VSIB, introduced in AVX2), considers
only the size of each separate memory access.
Returns true iff \p instr’s opcode is valid.
If the opcode is ever set to other than OP_INVALID or OP_UNDECODED it is assumed
to be valid. However, calling instr_get_opcode() will attempt to
decode a valid opcode, hence the purpose of this routine.
Returns true iff \p pred denotes a truly conditional predicate: on all
architectures, this excludes #DR_PRED_NONE. On ARM it also excludes
#DR_PRED_AL and #DR_PRED_OP; on AArch64, it also excludes #DR_PRED_AL
and #DR_PRED_NV.
Given the machine context \p mc, returns whether or not the predicated
instruction \p instr will execute.
Currently condition-code predicates are supported and OP_bsf and
OP_bsr from #DR_PRED_COMPLEX; other instances of #DR_PRED_COMPLEX
are not supported.
\p mc->flags must include #DR_MC_CONTROL for condition-code predicates,
and additionally #DR_MC_INTEGER for OP_bsf and OP_bsr.
Assumes that \p reg is a DR_REG_ constant.
Returns true iff at least one of \p instr’s source operands is
the same register (not enough to just overlap) as \p reg.
Assumes that reg is a DR_REG_ constant.
Returns true iff at least one of instr’s operands reads
from a register that overlaps reg (checks both source operands
and addressing registers used in destination operands).
Removes \p instr’s destination operands from position \p start up to
but not including position \p end (so pass n,n+1 to remove just position n).
Shifts all subsequent destination operands (if any) down in the operand array.
Also calls instr_set_raw_bits_valid(\p instr, false) and
instr_set_operands_valid(\p instr, true).
Removes \p instr’s source operands from position \p start up to
but not including position \p end (so pass n,n+1 to remove just position n).
Shifts all subsequent source operands (if any) down in the operand array.
Also calls instr_set_raw_bits_valid(\p instr, false) and
instr_set_operands_valid(\p instr, true).
Replaces all instances of \p old_reg (or any size variant) in \p instr’s operands
with \p new_reg. Resizes \p new_reg to match sub-full-size uses of \p old_reg.
Returns whether it replaced anything.
Replaces all instances of \p old_opnd in \p instr’s source operands with
\p new_opnd (uses opnd_same() to detect sameness).
Returns whether it replaced anything.
Frees all dynamically allocated storage that was allocated by \p instr,
except for allocated bits.
Also zeroes out \p instr’s fields, except for raw bit fields,
whether \p instr is instr_is_meta(), and the x86 mode of \p instr.
\p instr must have been initialized.
Returns true iff \p instr1 and \p instr2 have the same opcode, prefixes,
and source and destination operands (uses opnd_same() to compare the operands).
Sets \p instr as an application (non-meta) instruction.
An application instruction might be mangled by DR if necessary,
e.g., to create an exit stub for a branch instruction.
All application instructions that are added to basic blocks or
traces should have their translation fields set (via
#instr_set_translation()).
Sets \p instr’s destination operand at position \p pos to be \p opnd.
Also calls instr_set_raw_bits_valid(\p instr, false) and
instr_set_operands_valid(\p instr, true).
Each instruction may store a hint for how the instruction should be encoded if
redundant encodings are available. This presumes that the user knows that a
redundant encoding is available. This routine sets the \p hint for \p instr.
Returns \p instr (for easy chaining).
Set a function \p func which is called when the label instruction is freed.
\p instr is the label instruction allowing \p func to free the label’s
auxiliary data.
\note This data field is not copied across instr_clone(). Instead, the
clone’s field will be NULL (xref i#3962).
Sets \p instr as a meta instruction.
A meta instruction will not be mangled by DR in any way, which is necessary
to have DR not create an exit stub for a branch instruction.
Meta instructions should not fault (unless such faults are handled
by the client) and are not considered
application instructions but rather added instrumentation code (see
#dr_register_bb_event() for further information).
\deprecated Any meta instruction can fault if it has a non-NULL
translation field and the client fully handles all of its faults,
so this routine is no longer needed.
Assumes that \p instr has been initialized but does not have any
operands yet. Allocates storage for \p num_srcs source operands
and \p num_dsts destination operands.
Set \p instr to “ok to emit” if \p val is true and “not ok to emit”
if \p val is false. An instruction that should not be emitted is
treated normally by DR for purposes of exits but is not placed into
the cache. It is used for final jumps that are to be elided.
Assumes that \p instr does not currently have any raw bits allocated.
Sets \p instr’s raw bits to be \p length bytes starting at \p addr.
Does not set the operands invalid.
Assumes that \p instr’s raw bits are valid and allocated by \p instr
and have > \p pos bytes.
Sets instr’s raw byte at position \p pos (beginning with 0) to the value \p byte.
Assumes that \p instr’s raw bits are valid and allocated by \p instr
and have >= num_bytes bytes.
Copies the \p num_bytes beginning at start to \p instr’s raw bits.
Assumes that \p instr’s raw bits are valid and allocated by \p instr
and have > pos+3 bytes.
Sets the 4 bytes beginning at position \p pos (0-based) to the value word.
Sets \p instr’s source operand at position \p pos to be \p opnd.
Also calls instr_set_raw_bits_valid(\p instr, false) and
instr_set_operands_valid(\p instr, true).
Assumes that \p cti_instr is a control transfer instruction.
Sets the first source operand of \p cti_instr to be \p target.
Also calls instr_set_raw_bits_valid(\p instr, false) and
instr_set_operands_valid(\p instr, true).
Sets the translation pointer for \p instr, used to recreate the
application address corresponding to this instruction. When adding
or modifying instructions that are to be considered application
instructions (i.e., non meta-instructions: see #instr_is_app),
the translation should always be set. Pick
the application address that if executed will be equivalent to
restarting \p instr. Currently the translation address must lie
within the existing bounds of the containing code block.
Returns the supplied \p instr (for easy chaining). Use
#instr_get_app_pc to see the current value of the translation.
Shrinks all registers not used as addresses, and all immed integer and
address sizes, to 16 bits.
Does not shrink DR_REG_ESI or DR_REG_EDI used in string instructions.
Returns true iff \p instr’s opcode is NOT OP_INVALID.
Not to be confused with an invalid opcode, which can be OP_INVALID or
OP_UNDECODED. OP_INVALID means an instruction with no valid fields:
raw bits (may exist but do not correspond to a valid instr), opcode,
eflags, or operands. It could be an uninitialized
instruction or the result of decoding an invalid sequence of bytes.
Returns true iff any of \p instr’s destination operands is a memory
reference. If \p instr is predicated (see instr_is_predicated()), the
destination may not always be written.
Assumes that \p reg is a DR_REG_ constant.
Returns true iff at least one of \p instr’s destination operands is
the same register (not enough to just overlap) as \p reg.
Which operands are considered to be accessed for conditionally executed
instructions are controlled by \p flags.
Assumes that \p reg is a DR_REG_ constant.
Returns true iff at least one of \p instr’s destination operands is
a register operand for a register that overlaps \p reg.
Which operands are considered to be accessed for conditionally executed
instructions are controlled by \p flags.
Returns true iff \p instr writes to an xmm register and zeroes the top half
of the corresponding ymm register as a result (some instructions preserve
the top half while others zero it when writing to the bottom half).
This zeroing will occur even if \p instr is predicated (see instr_is_predicated()).
Returns true iff \p instr writes to an xmm or ymm register and zeroes the top half
of the corresponding zmm register as a result (some instructions preserve
the top half while others zero it when writing to the bottom half).
This zeroing will occur even if \p instr is predicated (see instr_is_predicated()).
Allocates a new instrlist_t and for each instr_t in \p old allocates
a new instr_t using instr_clone to produce a complete copy of \p old.
Each operand that is opnd_is_instr() has its target updated
to point to the corresponding instr_t in the new instrlist_t
(this routine assumes that all such targets are contained within \p old,
and may fault otherwise).
Prints each instruction in \p ilist in sequence to \p outfile.
The default is to use DR’s custom syntax (see disassemble_set_syntax())
with additional information. The first column contains the offset
in bytes from the start of the list.
Next, each instruction is labeled according to its type, which
will typically either be \p L3 for an unchanged application instruction
or \p m4 for a tool instruction (the names come from “Level 3” and
“meta Level 4”, IR details which are no longer exposed to tools).
Tool instructions have their IR heap addresses included (indicated with a
leading @ character) to make instruction jump targets easier to
identify. The final two columns contain the raw bytes and the
actual instruction disassembly.
Encodes each instruction in \p ilist in turn in contiguous memory starting
at \p pc. Returns the pc after all of the encodings, or NULL if any one
of the encodings failed.
Uses the x86/x64 mode stored in each instr, not the mode of the current thread.
In order for instr_t operands to be encoded properly,
\p has_instr_jmp_targets must be true. If \p has_instr_jmp_targets is true,
the offset field of each instr_t in ilist will be overwritten, and if any
instr_t targets are not in \p ilist, they must have their offset fields set with
their offsets relative to pc.
x86 instructions can occupy up to 17 bytes each, so the caller should ensure
the target location has enough room to avoid overflow.
Encodes each instruction in \p ilist in turn in contiguous memory
starting \p copy_pc in preparation for copying to \p final_pc. Any
pc-relative instruction is encoded as though the instruction list were
located at \p final_pc. This allows for direct copying of the
encoded bytes to \p final_pc without re-relativization.
Create meta instructions for storing pointer-size integer \p val to \p dst,
and then insert them into \p ilist prior to \p where.
Pointers to the first and last created meta instructions are returned
in \p first and \p last, unless only one meta instruction is created,
in which case NULL is returned in last.
If the instruction is a no-op (when dst is the zero register on AArch64)
then no instructions are created and NULL is returned in first and last.
Create meta instructions for storing the address of \p src_inst to \p dst,
and then insert them into \p ilist prior to \p where.
The \p encode_estimate parameter, used only for 64-bit mode,
indicates whether the final address of \p src_inst, when it is
encoded later, will fit in 32 bits or needs 64 bits.
If the encoding will be in DynamoRIO’s code cache, pass NULL.
If the final encoding location is unknown, pass a high address to be on
the safe side.
Pointers to the first and last created meta instructions are returned
in \p first and \p last, unless only one meta instruction is created,
in which case NULL is returned in last.
If the instruction is a no-op (when dst is the zero register on AArch64)
then no instructions are created and NULL is returned in first and last.
Create meta instructions for pushing pointer-size integer \p val on the stack,
and then insert them into \p ilist prior to \p where.
Pointers to the first and last created meta instructions are returned
in \p first and \p last, unless only one meta instruction is created,
in which case NULL is returned in last.
Create meta instructions for pushing the address of \p src_inst on the stack,
and then insert them into \p ilist prior to \p where.
The \p encode_estimate parameter, used only for 64-bit mode,
indicates whether the final address of \p src_inst, when it is
encoded later, will fit in 32 bits or needs 64 bits.
If the encoding will be in DynamoRIO’s code cache, pass NULL.
If the final encoding location is unknown, pass a high address to be on
the safe side.
Pointers to the first and last created meta instructions are returned
in \p first and \p last, unless only one meta instruction is created,
in which case NULL is returned in last.
All future instructions inserted into \p ilist will be predicated
with \p pred. This is a convenience routine to make it easy to have
emitted code from internal DR components predicated.
Specifies the fall-through target of a basic block if its last
instruction is a conditional branch instruction.
It can only be called in basic block building event callbacks
when the \p for_trace parameter is false,
and has NO EFFECT in other cases.
Specifies the return target of a basic block if its last
instruction is a call instruction.
It can only be called in basic block building event callbacks
when the \p for_trace parameter is false,
and has NO EFFECT in other cases.
All future instructions inserted into \p ilist that do not have raw bits
will have instr_set_translation() called with \p pc as the target.
This is a convenience routine to make it easy to have the same
code generate non-translation and translation instructions, and it does
not try to enforce that all instructions have translations (e.g.,
some could be inserted via instr_set_next()).
Assumes \p opnd is a register operand, base+disp memory reference, or
an immediate integer.
Sets the flags describing additional properties of the operand to
be the current flags plus the \p flags parameter and returns the
new operand value.
Returns the effective address of \p opnd, computed using the passed-in
register values. If \p opnd is a far address, ignores that aspect
except for TLS references on Windows (fs: for 32-bit, gs: for 64-bit)
or typical fs: or gs: references on Linux. For far addresses the
calling thread’s segment selector is used.
\p mc->flags must include DR_MC_CONTROL and DR_MC_INTEGER.
Returns a memory reference operand that refers to the address \p
seg : \p addr, but will be encoded as a pc-relative address. It is
up to the caller to ensure that the resulting address is reachable
via a 32-bit signed displacement from the next instruction at emit
time.
Returns an immediate double operand with value \p d.
The caller’s code should use proc_save_fpstate() or be inside a
clean call that has requested to preserve the floating-point state.
Returns an immediate float operand with value \p f.
The caller’s code should use proc_save_fpstate() or be inside a
clean call that has requested to preserve the floating-point state.
Returns an unsigned immediate integer operand with value \p i and size
\p data_size; \p data_size must be a OPSZ_ constant.
This operand can be distinguished from a regular immediate integer
operand by the flag #DR_OPND_MULTI_PART in opnd_get_flags() which tells
the caller to use opnd_get_immed_int64() to retrieve the full value.
\note 32-bit only: use opnd_create_immed_int() for 64-bit architectures.
Returns an operand whose value will be the encoded address of \p
instr. This operand can be used as an immediate integer or as a
direct call or jump target. Its size is always #OPSZ_PTR.
Returns an operand whose value will be the encoded address of \p
instr. This operand can be used as an immediate integer or as a
direct call or jump target. Its size is the specified \p size.
Its value can be optionally right-shifted by \p shift from the
encoded address.
Returns a memory reference operand whose value will be the encoded
address of \p instr plus the 16-bit displacement \p disp. For 32-bit
mode, it will be encoded just like an absolute address
(opnd_create_abs_addr()); for 64-bit mode, it will be encoded just
like a pc-relative address (opnd_create_rel_addr()). This operand
can be used anywhere a regular memory operand can be used. Its
size is \p data_size.
Returns a register operand with additional properties specified by \p flags.
If \p subsize is 0, creates a full-sized register; otherwise, creates a
partial register in the manner of opnd_create_reg_partial().
Returns a memory reference operand that refers to the address \p
addr, but will be encoded as a pc-relative address. At emit time,
if \p addr is out of reach of the maximum encodable displacement
(signed 32-bit for x86) from the next instruction, encoding will
fail.
Returns true iff \p def, considered as a write, affects \p use.
Is conservative, so if both \p def and \p use are memory references,
will return true unless it can disambiguate them based on their
registers and displacement.
Prints the operand \p opnd to the buffer \p buf.
Always null-terminates, and will not print more than \p bufsz characters,
which includes the final null character.
Returns the number of characters printed, not including the final null.
The default is to use DR’s custom syntax (see disassemble_set_syntax()).
Assumes \p opnd is a (near or far) absolute or pc-relative memory reference,
or a base+disp memory reference with no base or index register.
Returns \p opnd’s absolute address (which will be pc-relativized on encoding
for pc-relative memory references).
Assumes \p opnd is a (near or far) base+disp memory reference.
Returns the displacement.
On ARM, the displacement is always a non-negative value, and the
presence or absence of #DR_OPND_NEGATED in opnd_get_flags()
determines whether to add or subtract from the base register.
Assumes \p opnd is a register operand, base+disp memory reference, or
an immediate integer.
Returns the flags describing additional properties of the register,
the index register or displacement component of the memory reference,
or the immediate operand \p opnd.
Assumes \p opnd is an immediate double and returns its value.
The caller’s code should use proc_save_fpstate() or be inside a
clean call that has requested to preserve the floating-point state.
Assumes \p opnd is an immediate float and returns its value.
The caller’s code should use proc_save_fpstate() or be inside a
clean call that has requested to preserve the floating-point state.
Used in conjunction with opnd_num_regs_used(), this routine can be used
to iterate through all registers used by \p opnd.
The index values begin with 0 and proceed through opnd_num_regs_used(opnd)-1.
Assumes \p opnd is a (near or far) memory reference of any type.
Returns \p opnd’s segment (a DR_SEG_ constant), or DR_REG_NULL if it is a near
memory reference.
Return the data size of \p opnd as a OPSZ_ constant.
Returns OPSZ_NA if \p opnd does not have a valid size.
\note A register operand may have a size smaller than the full size
of its DR_REG_* register specifier.
Performs a bitwise NOT operation on the integer value in \p opnd, but only on the LSB
bits provided by opnd_size_in_bits(opnd). \p opnd must carry an immed integer.
Returns true iff \p opnd is a (near or far) absolute address operand.
Returns true for both base-disp operands with no base or index and
64-bit non-base-disp absolute address operands.
Returns true iff \p opnd is a far absolute address operand.
Returns true for both base-disp operands with no base or index and
64-bit non-base-disp absolute address operands.
Returns true iff \p opnd is a near (i.e., default segment) absolute address operand.
Returns true for both base-disp operands with no base or index and
64-bit non-base-disp absolute address operands.
Returns true iff \p opnd is a (near or far) pc-relative memory reference operand.
Returns true for base-disp operands on ARM that use the PC as the base register.
Assumes that both \p old_reg and \p new_reg are DR_REG_ constants.
Replaces all occurrences of \p old_reg in \p *opnd with \p new_reg.
Only replaces exact matches (use opnd_replace_reg_resize() to match
size variants).
Returns whether it replaced anything.
Replaces all instances of \p old_reg (or any size variant) in \p *opnd
with \p new_reg. Resizes \p new_reg to match sub-full-size uses of \p old_reg.
Returns whether it replaced anything.
Set the displacement of a memory reference operand \p opnd to \p disp.
On ARM, a negative value for \p disp will be converted into a positive
value with #DR_OPND_NEGATED set in opnd_get_flags().
Assumes \p opnd is a register operand, base+disp memory reference, or
an immediate integer.
Sets the flags describing additional properties of the operand to \p flags.
Shrinks all 32-bit registers in \p opnd to their 16-bit versions.
Also shrinks the size of immediate integers and memory references from
OPSZ_4 to OPSZ_2.
Shrinks all 64-bit registers in \p opnd to their 32-bit versions.
Also shrinks the size of immediate integers and memory references from
OPSZ_8 to OPSZ_4.
Returns the appropriate OPSZ_ constant for the given number of bytes.
Returns OPSZ_NA if there is no such constant.
The intended use case is something like “opnd_size_in_bytes(sizeof(foo))” for
integer/pointer types. This routine returns simple single-size
types and will not return complex/variable size types.
Assumes \p size is an OPSZ_ constant, typically obtained from
opnd_get_size() or reg_get_size().
Returns the number of bits the OPSZ_ constant represents.
If OPSZ_ is a variable-sized size, returns the default size,
which may or may not match the actual size decided up on at
encoding time (that final size depends on other operands).
Assumes \p size is an OPSZ_ constant, typically obtained from
opnd_get_size() or reg_get_size().
Returns the number of bytes the OPSZ_ constant represents.
If OPSZ_ is a variable-sized size, returns the default size,
which may or may not match the actual size decided up on at
encoding time (that final size depends on other operands).
Assumes that \p reg is a DR_REG_ constant.
Returns true iff \p opnd refers to reg directly or refers to a register
that overlaps \p reg (e.g., DR_REG_AX overlaps DR_REG_EAX).
Specifies hints for how an instruction should be encoded if redundant encodings are
available. Currently, we provide a hint for x86 evex encoded instructions. It can be
used to encode an instruction in its evex form instead of its vex format (xref #3339).
These flags describe how the index register in a memory reference is extended
before being optionally shifted and added to the base register. They also describe
how a general source register is extended before being used in its containing
instruction.
These flags describe operations performed on the value of a source register
before it is combined with other sources as part of the behavior of the
containing instruction, or operations performed on an index register or
displacement before it is added to or subtracted from the base register.
Bitmask values passed as flags to routines that ask about whether operands
and condition codes are read or written. These flags determine how to treat
conditionally executed instructions.
As a special case, the addressing registers inside a destination memory
operand are covered by DR_QUERY_INCLUDE_COND_SRCS rather than
DR_QUERY_INCLUDE_COND_DSTS.
These flags describe the values for “pattern” operands for aarch64
predicate count instructions. They are always set for imms with the
flag #DR_OPND_IS_PREDICATE_CONSTRAINT
These flags describe how the index register in a memory reference is shifted
before being added to or subtracted from the base register. They also describe
how a general source register is shifted before being used in its containing
instruction.
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().
DR will call the end trace event if it is registered prior to
adding each basic block to a trace being generated. The return
value of the event callback should be from the
dr_custom_trace_action_t enum.
Data structure passed within dr_exception_t, dr_siginfo_t, and
dr_restore_state_info_t.
Contains information about the code fragment inside the code cache
at the exception/signal/translation interruption point.
Indicates which category the instruction corresponds to.
Update instr_get_category_name() in core/ir/instr_shared.c
when adding new categories in this enum.
Data structure passed to a restore_state_ex event handler (see
dr_register_restore_state_ex_event()). Contains the machine
context at the translation point and other translation
information.
Defines the Valgrind client request object, which is constructed by each instance of
a Valgrind annotation in the target app. An instance is passed to Valgrind annotation
callback functions to make the arguments available. Some arguments may be
undefined for some Valgrind client requests; see the Valgrind documentation for each
specific Valgrind client request for details about the arguments.
Label instruction callback function. Set by instr_set_label_callback() and
called when the label is freed. \p instr is the label instruction allowing
the caller to free the label’s auxiliary data.
Holds the names of a module. This structure contains multiple
fields corresponding to different sources of a module name. Note
that some of these names may not exist for certain modules. It is
highly likely, however, that at least one name is available. Use
dr_module_preferred_name() on the parent _module_data_t to get the
preferred name of the module.
Anonymous union of alternative names for the program counter /
instruction pointer (eip/rip). \note This field is not always set or
read by all API routines.