Dynamic Instrumentation Tool Platform
DynamoRIO
Release Notes for Version 11.0.20042

This section is divided into the following subsections:

Distribution Contents

The following are part of the DynamoRIO release distribution:

  • Four different DynamoRIO libraries: debug and release for each of 32-bit and 64-bit (for ARM or AArch64 builds, only a single bitwidth matching the ISA is provided). The debug library enables assertion messages to more easily diagnose API usage errors.
  • Four different IA-32/AMD64/ARM/AArch64 decoding static libraries: debug and release for each of 32-bit and 64-bit (only 32-bit for ARM and 64-bit for AArch64). The debug library enables assertion messages to more easily diagnose API usage errors.
  • A variety of DynamoRIO Extension libraries that augment the core DynamoRIO API (see Extension API).
  • Additional Extension libraries from the Dr. Memory Framework (DRMF). If this documentation is part of a DynamoRIO public release, this link should point at the local documentation for DRMF.
  • The DynamoRIO configuration and execution libraries and command-line utilities drconfiglib.dll, drinjectlib.dll, drfrontendlib.lib, drconfig.exe, drrun.exe, and drinject.exe. On Linux, the tools are named drconfig, drrun, and drinject.
  • A utility drview.exe for viewing which processes are running under DynamoRIO control (Windows package only).
  • Header files for the DynamoRIO APIs.
  • This documentation.
  • Sample clients.
  • A graphical statistics viewer DRstats.exe that displays internal DynamoRIO statistics as well as custom statistics defined by a client (see Use of Custom Client Statistics with the Windows GUI) (Windows package only). DynamoRIO exports a large number of statistics in its debug build, and a handful in release builds.
  • A binary tracedump reader, which also functions as a sample client using DynamoRIO as a standalone library (see Using DynamoRIO as a Standalone Library).
  • A number of end-user tools including a code coverage tool (see Code Coverage Tool), a multi-process cache simulator (see Tracing and Analysis Framework), a last-level cache miss analyzer (see Tracing and Analysis Framework), and a legacy CPU testing tool (see CPU Simulator). If this is a DynamoRIO public release, it also includes the Dr. Memory memory debugging tool (see Dr. Memory Memory Debugging Tool), a system call tracer for Windows (see System Call Tracer for Windows), a library tracing tool (see Library Call Tracer), and a symbol querying tool (see Symbol Query Tool).

When unpacking the release package on Windows, be aware that the Cygwin unzip utility does not preserve executable permissions properly. After unzipping with Cygwin, add ugo+rx permissions to all of the .dll and .exe files in the resulting directory tree:

find . -name \*.dll -exec chmod ugo+rx {} \; -o -name \*.exe -exec chmod ugo+rx {} \;

Changes Since Prior Releases

The current version is 11.0.20042. It includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 11.0.20042 and 11.0.0 include the following compatibility changes:

  • Removed uncompleted instructions and the corresponding memrefs from drmemtraces. Instructions which are fetched but not completed due to asynchronous signal or fault are removed. A new marker dynamorio::drmemtrace::TRACE_MARKER_TYPE_UNCOMPLETED_INSTRUCTION was added to indicate an uncompleted instruction was removed. The value of the marker is the encoding of the removed instruction up to a pointer's length. Added OFFLINE_FILE_VERSION_RETIRED_INSTRUCTIONS_ONLY to increase the trace version for drmemtraces with uncompleted instructions removed.

Further non-compatibility-affecting changes include:

The changes between version 11.0.0 and 10.0.0 include the following compatibility changes:

Further non-compatibility-affecting changes include:

  • Added DWARF-5 support to the drsyms library by linking in 4 static libraries from elfutils. These libraries have LGPL licenses.
  • Added raw2trace support to inject system call kernel trace templates collected from elsewhere (e.g., QEMU, Gem5) into the user-space drmemtrace traces at the corresponding system call number marker. This is done by specifying the path to the template file via the new -syscall_template_file option.
  • Added a new scheme for the modoffs field in the PC trace entry which allows L0 filtering of non-module code; see dynamorio::drmemtrace::ENCODING_FILE_TYPE_SEPARATE_NON_MOD_INSTRS. Also added file type entry to the header of encoding files.
  • Fixed a bug in the AArch64 codec with the way that SVE scalar+immediate predicated contiguous load and store instructions represented the immediate offset in the IR. In 10.0.0 the memory operand in these instruction used the immediate value from the instruction (which is an index to be scaled by the vector length) as the displacement, whereas the displacement value in a DynamoRIO memory operand should always be a byte offset. This has now been corrected. Traces and other tool results created with DynamoRIO prior to this fix may have incorrect results if the application contained these instructions. See PR #6390 for the full list of affected instructions.
  • Added core-sharded analysis tool support where traces are sharded by core instead of by thread, with the thread schedules onto the cores either following how they were traced or using a dynamic schedule. Adds dynamorio::drmemtrace::shard_type_t passed to initialize_shard_type() to inform tools of the shard type. Adds a new memtrace_stream_t::get_output_cpuid() query. Adds a number of drcachesim options to set sharding mode (-core_sharding, -core_serial) and control the schedule (-sched_quantum, -sched_time, sched_order_time, -record_file, -replay_file, -cpu_schedule_file).
  • Added additional timestamps to drmemtrace traces: at the end of each buffer, and before and after each system call.
  • Added type_is_read() API that returns true if a trace type reads from memory.
  • Added instr_num_memory_read_access() and instr_num_memory_write_access() that return the number of memory read and write accesses of an instruction respectively.
  • Added realloc to the set of functions traced by -record_heap by default.
  • Deprecated dr_fp_type_t for Floating-Point operation types in favor of the new dr_instr_category_t. Deprecated instr_is_floating_ex(), replacing it with instr_is_floating_type(). The old versions will continue to work.
  • Added several routines to the dynamorio::drmemtrace::memtrace_stream_t interface for drmemtrace analysis tools: get_output_cpuid(), get_workload_id(), get_input_id(), get_input_interface().
  • Added -record_syscall to drmemtrace for recording syscall parameters.
  • Added opportunity to run multiple drcachesim analysis tools simultaneously.
  • Added support of loading separately-built analysis tools to drcachesim dynamically.
  • Added instr_is_opnd_store_source().
  • Added kernel context switch sequence injection support to the drmemtrace scheduler.
  • Added dr_running_under_dynamorio().
  • Added instr_get_category_name() API that returns the string version (as char*) of a category.
  • Added dynamorio::drmemtrace::TRACE_MARKER_TYPE_VECTOR_LENGTH marker to indicate the current vector length for architectures with a hardware defined or runtime changeable vector length (such as AArch64's SVE scalable vectors).
  • Added a new drmemtrace analyzer option -interval_instr_count that enables trace analyzer interval results for every given count of instrs in each shard. This mode does not support merging the shard interval snapshots to output the whole-trace interval snapshots. Instead, the print_interval_results() API is called separately for each shard with the interval state snapshots of that shard.
  • Added a new finalize_interval_snapshots() API to dynamorio::drmemtrace::analysis_tool_t to allow the tool to make holistic adjustments to the interval snapshots after all have been generated, and before they are used for merging across shards (potentially), and printing the results.
  • Added opnd_is_vector_base_disp() to test if an opnd_t is a base+disp memory operand that uses a vector register for the base or index register.
  • Added -abort_on_invariant_error flag that instructs the invariant checker drmemtrace analysis tool to abort trace analysis when a trace invariant error is found. This is set to true by default to match the existing behavior of the invariant checker.
  • Added a new instr API instr_is_xrstor() that tells whether an instruction is any variant of the x86 xrstor opcode.
  • Added a new dr_isa_mode_t: DR_ISA_REGDEPS, which is a synthetic ISA with the main purpose of preserving register dependencies.
  • Added instr_convert_to_isa_regdeps() API that converts an instr_t from a real ISA (e.g., DR_ISA_AMD64) to the DR_ISA_REGDEPS synthetic ISA.
  • Added encodings2regdeps_filter_t filter to dynamorio::drmemtrace::record_filter_t to generate DR_ISA_REGDEPS traces.
  • Added dynamorio::drmemtrace::OFFLINE_FILE_TYPE_ARCH_REGDEPS file type for DR_ISA_REGDEPS traces.
  • Added -tool as the preferred alias for -simulator_type for the drmemtrace/drcachesim trace analysis tool framework.
  • Added "-t drmemtrace" as the preferred launcher for the drmemtrace/drcachesim trace analysis tool framework.
  • Added func_id_filter_t to dynamorio::drmemtrace::record_filter_t to filter function markers based on the function ID. This filter is enabled by "-filter_keep_func_ids" followed by a comma-separated list of function IDs to preserve in the output trace. All function markers whose ID is not in the list are removed.
  • Added -skip_to_timestamp and dynamorio::drmemtrace::scheduler_tmpl_t:: input_workload_t::times_of_interest to the drmemtrace scheduler.
  • Added v2p_reader_t to parse a virtual-to-physical mapping in textproto format and v2p_info_t to hold that mapping in memory.
  • Added -v2p_file option to drcachesim TLB tool to set the path to a v2p.textproto file, which provides a virtual to physical mapping of addresses for an offline trace. This option overwrites both -page_size and dynamorio::drmemtrace::TRACE_MARKER_TYPE_PAGE_SIZE (if present) with the page size in v2p.textproto. Option -use_physical (in offline mode) must also be set to use the mapping in v2p.textproto (note that -use_physical during tracing is not necessary, nor related to -use_physical offline).
  • Added -trace_instr_intervals_file option to the drmemtrace trace analysis tools framework. The file must be in CSV format containing a <start,duration> tracing interval per line where start and duration are expressed in number of instructions.
  • Added modify_marker_value_filter_t to dynamorio::drmemtrace::record_filter_t to modify the value of TRACE_MARKER_TYPE_ markers. This filter takes a list of <TRACE_MARKER_TYPE_,new_value> and changes every listed marker in the trace to its corresponding new_value.
  • Added trace_analysis_tool::preferred_shard_type() to the drmemtrace framework to allow switching to core-sharded by default if all tools prefer that mode.
  • For the drmemtrace framework, if only core-sharded-preferring tools are enabled (these include cache and TLB simulators and the schedule_stats tool), -core_sharded or -core_serial is automatically turned on for offline analysis to enable more representative simulated software thread scheduling onto virtual cores.

The changes between version 10.0.0 and 9.0.1 include the following compatibility changes:

  • Eliminated the -skip_syscall option to drrun and drinject, which is now always on by default.
  • Changed the drcachesim -use_physical option to not modify the regular trace entry virtual addresses but to instead insert metadata containing translation information for converting virtual to physical addresses.
  • Changed the layout of the DR_FAST_IR struct to add an element size property that supports more information about vectors. This changes the method of accessing the register in the structure from struct.value.reg to struct.value.reg_and_element_size.reg. The element size can be accessed directly via struct.value.reg_and_element_size.element_size.
  • Changed the size of the instr_t structure by appending a field which is used for relative offsets while encoding. The note field is no longer modified during encoding.
  • Reduced the value of DR_NOTE_FIRST_RESERVED. This is not expected to cause problems unless clients are directly choosing high note values without using drmgr_reserve_note_range().
  • Changed the values of the AArch64 DR_REG_Z* constants so that Z registers can be used in base+disp operands in SVE scatter/gather instructions. This breaks binary compatibility for clients built against an older version of opnd_api.h, but source code compatibility is unchanged.
  • Removed the drcachesim external iterator analyzer interface. Users should instead use the new dynamorio::drmemtrace::scheduler_tmpl_t interface for direct control over iteration. See Trace Scheduler for example code.
  • Refactored the drmemtrace reader and file reader classes to better fit the new scheduler model: now each reader owns just one single stream of records with all multi-stream interleaving owned by the scheduler.
  • Replaced the AArch64 OP_reta with OP_retaa and OP_retab. "reta" is not a real AArch64 instruction and "reta" entries in the AArch64 codec were being used to decode "retaa" and "retab". These instructions will now encode and decode correctly as "retaa" and "retab".
  • Added a DR_XFER_RSEQ_ABORT event for a signal generated during an rseq region.
  • Changed the interrupted PC for DR_XFER_RSEQ_ABORT for native execution aborts to be the abort handler (a signal during the instrumented execution will continue to have the actual interrupted PC); changed the interrupted PC for DR_XFER_SIGNAL_DELIVERY for a signal generated during an rseq region to be the abort handler, matching the kernel behavior.
  • Changed the arguments and decode behavior of the INSTR_CREATE_orr_sve_pred(), INSTR_CREATE_eor_sve_pred(), INSTR_CREATE_and_sve_pred() and INSTR_CREATE_bic_sve_pred() to use the new vector element registers and to correctly encode the predicate mode.
  • ud2a and ud2b have been renamed to ud2 and ud1, respectively. The old constants OP_ud2a and OP_ud2b, as well as the INSTR_CREATE_ud2a()/INSTR_CREATE_ud2b() macros, are #defined to the new names, OP_ud2, OP_ud1, INSTR_CREATE_ud2(), and INSTR_CREATE_ud1() respectively. ud1 now correctly accounts for its operands so manipulation of ud1 is not backwards compatible.
  • All drcachesim/ code was changed to use the dynamorio::drmemtrace namespace. External code using any drcachesim or drmemtrace library will need to be recompiled.
  • The droption header library is now inside the dynamorio::droption namespace.
  • The drmemtrace record type dynamorio::drmemtrace::TRACE_TYPE_INSTR_CONDITIONAL_JUMP is deprecated in offline traces where it is replaced by dynamorio::drmemtrace::TRACE_TYPE_INSTR_TAKEN_JUMP and dynamorio::drmemtrace::TRACE_TYPE_INSTR_UNTAKEN_JUMP.
  • All int_least64_t and uint_least64_t types in drcachesim were replaced with their precise counterparts int64_t and uint64_t.
  • The dynamorio::drmemtrace::memref_t structure has a new field appended for holding the actual target of each indirect branch.
  • Increased the size of dr_simd_t to accommodate AArch64's Scalable Vector Extension (SVE) as well as adding two new dr_simd_t instances to dr_mcontext_t: SVE predicate registers svep[] and the SVE first-fault register, ffr. This is a significant binary compatibility change and will require re-building clients built before SVE was added.
  • The instr_t structure has a new field inserted for holding the category type dr_instr_category_t which changes the size and the offsets of most fields in 32-bit. 64-bit compatibility is not affected.

Further non-compatibility-affecting changes include:

The changes between version 9.0.1 and 9.0.0 include the following compatibility changes:

  • Introduced a new CMake option called BUILD_PACKAGE to skip glibc compatibility checks. This is off by default such that building DynamoRIO from source is straight-forward to do on rolling release Linux distributions, and enabled by make/package.cmake when building a distributable version of DynamoRIO.

Further non-compatibility-affecting changes include:

  • Fixed a significant performance regression between 8.0.0 and 9.0.0 (between 8.0.18740 and 8.0.18747) affecting Windows programs with varying indirect branches on hot code paths.
  • Added alias support to droption.
  • The drcpusim option -blacklist was renamed to -blocklist but the old name is still accepted.
  • Added droption_parser_t::clear_values() for re-setting accumulating option values on re-attach for statically linked clients.
  • Added the count of cache exits to dr_stats_t.
  • Added dr_register_inject_paths() and a corresponding -use_alt_dll drrun/drconfig parameter for control over DynamoRIO library paths, in particular the other bitwidth path, when configuring target processes.
  • Added -tool_dir drrun/drconfig parameter to control where to look for tool config files.

The changes between version 9.0.0 and 8.0.0 include the following compatibility changes:

  • The AArch64 opcode enum ordering changed.
  • A source compatibilty change in drcachesim analysis tools for users who have created derived classes from existing analysis tools: member fields of classes are now following a consistent style with an underscore suffix. References to renamed fields will need to be updated.
  • A change in the load callbacks used with drmodtrack_add_custom_data() and drmemtrace_custom_module_data(): they each take an additional parameter, the segment index. The custom data field is now per-segment and not per-module, and all callbacks are invoked separately for each segment.

The changes between version 11.0.20042 and 8.0.0 include the following minor compatibility changes:

  • drconfiglib (and thus drrun and drconfig) now sets only the new client path options which are added in this release to support other-bitwidth child processes. This means that a drconfiglib from this version will not properly configure for a DynamoRIO core library from a prior version.
  • A new option -ldstex2cas is on by default on ARM and AArch64. This converts load-exclusive store-exclusive sequences to use compare-and-swap instead, which enables normal instrumentation of such sequences without clearing the exclusive monitor and causing infinite loops. However, the compare- and-swap's semantics are not identical: it does not detect "ABA" changes and could cause errors in lock-free data structures or other application constructs. See Exclusive Monitor Instrumentation for more information.
  • The header file dr_tools.h has been split up, with module information now in a new file dr_modules.h, os-specific queries in dr_os_api.h, and tracedump types in dr_tracedump.h. dr_api.h includes the new files, so users including dr_api.h are unaffected.
  • The header files dr_ir_utils.h, dr_ir_opnd.h, dr_ir_instr.h, and dr_ir_instrlist.h have been split up, with encoding routines now in a new file dr_ir_encode.h, decoding routines in dr_ir_decode.h, disassembly routines in dr_ir_disassemble.h. dr_api.h includes the new files, so users including dr_api.h are unaffected.
  • The routines dr_insert_save_fpstate(), dr_insert_restore_fpstate(), and dr_insert_get_seg_base() moved from dr_proc.h to dr_ir_utils.h.
  • Added a flags field to emulated_instr_t and two emulator-set flags values: DR_EMULATE_REST_OF_BLOCK, indicating an emulation sequence that has no end label and includes the rest of the block; and DR_EMULATE_INSTR_ONLY, indicating an emulation for which instrumentation should still examine the emulation sequence for observing data operations. A third value is set by drmgr_in_emulation_region(): DR_EMULATE_IS_FIRST_INSTR. This flag addition preserves binary compatibility, but source code that did not zero the structure could end up with an uninitialized flags field when calling drmgr_insert_emulation_start().
  • drcov's output now uses a module segment offset, rather than a module base offset. This better supports modules with code beyond the first segment and with gaps between segments.
  • Changed the drcachesim view tool's behavior to count all trace entries, rather than just instructions, with respect to the -skip_refs and -sim_refs flags. This matches the cache and TLB simulator behavior.
  • drcachesim's child cache statistics now include hits from all lower levels and not just the immediately lower level child caches.
  • For AArch64 the OP_sys opcode is still implemented but has been split up into its data and instruction cache opcodes. In cases where OP_sys was used with enums representing data and instruction cache opcodes, OP_sys is no longer used, replaced by the relevant data and instruction cache opcodes starting with OP_dc_ and OP_ic_, e.g. OP_ic_ivau, OP_dc_zva.

Further non-compatibility-affecting changes include:

Version 8.0.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 8.0.0 and 7.1.0 include the following compatibility changes:

  • Changed the enumeration of the DR_REG_ enum by adding x86 AVX-512 registers as well as reserved ranges for future extensions. This is a binary compatibility change for the DR_REG_ enum.
  • Changed the enumeration of the OPSZ_ enum by moving its start back to 0. The OPSZ_ enum now completely overlaps the DR_REG_ enum. This is a binary compatibility change for the OPSZ_ enum.
  • Added a new encoding hint field to instr_t.
  • Added a requirement that a C++11-compliant compiler be used with DynamoRIO Option Parser.
  • Changed the syntax of the drcachesim -record_function option. It no longer takes in an identifier: the identifier is computed by the tracer. It thus takes pairs, with an optional third argument for flags such as "noret" to indicate that the return value should not be recorded. The tracer writes out a file listing functions traced and their identifiers with "id,library!symbol" on each line of the file.
  • Added free_key_func to the drcontainers hashtable_configure(), which adds a field to hashtable_config_t. Binary compatibility is maintained via the size field of the struct, but users who were not zeroing the whole structure and who update and recompile without setting the field may see crashes due to free_key_func being uninitialized.
  • Changed the 32-bit x86 stack alignment of DynamoRIO and clients built using DR's CMake configuration from 4 to 16 on Linux to match modern conventions.

The changes between version 8.0.0 and 7.1.0 include the following minor compatibility changes:

  • Added the define MCXT_NUM_SIMD_SLOTS that was renamed from NUM_SIMD_SLOTS. MCXT_NUM_SIMD_SLOTS is now a constant that shall be used only to determine the number of SIMD slots in DynamoRIO's mcontext.
  • Replaced NUM_SIMD_SLOTS with proc_num_simd_saved(). Clients may set(DynamoRIO_NUM_SIMD_SLOTS_COMPATIBILITY ON) in order to provide the define NUM_SIMD_SLOTS using proc_num_simd_saved(). The macro is not a constant expression and code relying on this needs to be rewritten. DynamoRIO_NUM_SIMD_SLOTS_COMPATIBILITY is set automatically if clients target version 7.1.0 or earlier.
  • Renamed mcontext's "ymm" structure to "simd".
  • Deprecated reg_is_xmm() and reg_is_ymm().
  • The function reg_is_extended() now returns true for the upper 8 simd registers as part of AVX-512, e.g. xmm16 - xmm31.
  • Dropped support for clients used with statically linked DynamoRIO to reach the code cache with 32-bit displacements.
  • An additional parameter in the accessors to the drcachesim cache stats (namely cache_stats_t and caching_device_stats_t) that passes a pointer to the cache block being accessed (on a hit) or being replaced (on a miss). This allows users to extend the cache block and stats classes in order to collect more stats.
  • Moves the immediate operand of the VEX encoded version of vextractps and vinsertps to be the first source.
  • The GPR versions of the vmovd and vmovq AVX opcodes are no longer combined into a single vmovd.
  • Changed the PFX format string specifier to use p rather than x internally.
  • DR no longer forwards snprintf, _snwprintf, _vsnprintf, sprintf, or sscanf to ntdll. Clients should use the dr-prefixed versions of these functions.
  • PC-relative control transfer instructions are now auto-re-relativized by the general decoder and encoder. This affects clients and standalone tools that use decode_from_copy() or instr_encode_to_copy() or instrlist_encode_to_copy(). Previously, re-relativization for instruction references only happened when an instruction was re-encoded. This auto-PC-relativization can be avoided by calling instr_set_rip_rel_valid() and setting the validity of the PC-relative data to false.
  • Fixed major synchronization bugs on ARM and AArch64.

Further non-compatibility-affecting changes include:

Version 7.1.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 7.1.0 and 7.0.0 include the following minor compatibility changes:

  • The drltrace tool has been moved to the Dr.Memory Framework.
  • Removed DRMGR_PRIORITY_INSERT_CLS_ENTRY, DRMGR_PRIORITY_INSERT_CLS_EXIT, DRMGR_PRIORITY_NAME_CLS_ENTRY, and DRMGR_PRIORITY_NAME_CLS_EXIT, as the new kernel xfer event (drmgr_register_kernel_xfer_event()) removes the need for them.
  • Renamed the LOG_ macros (LOG_NONE, LOG_ALL, etc.) to have a DR_ prefix to avoid name conflicts. Clients should set(DynamoRIO_LOG_COMPATIBILITY ON) prior to configure_DynamoRIO_client() to use the old constants and avoid any source changes; this will happen automatically if the client targets version 7.0.0 or earlier. Binary compatibility is unaffected.
  • Added a parameter to cmake functions DynamoRIO_get_target_path_for_execution and DynamoRIO_copy_target_to_device. External projects outside of DynamoRIO need to pass _DR_location_suffix.
  • The drcachesim tool's offline traces are now stored in separate files per traced application thread, rather than a single interleaved file. Reading and analyzing a legacy interleaved file is still supported, but all new generated traces are split. Splitting enables parallelized post-processing and trace analysis.
  • In standalone mode, there are no 32-bit-displacement reachability guarantees regarding DynamoRIO's heap.

Further non-compatibility-affecting changes include:

Version 7.0.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 7.0.0 and 6.2.0 include the following minor compatibility changes:

  • Changed dr_app_stop() to send all threads native instead of only the calling thread.
  • Replaced PAGE_SIZE with dr_page_size() and removed PAGE_START from the API. However, clients may set(DynamoRIO_PAGE_SIZE_COMPATIBILITY ON), in which case definitions of PAGE_SIZE and PAGE_START using dr_page_size() are provided, though code that uses these macros in a constant expression, such as a static initialiser, will still need to be rewritten. DynamoRIO_PAGE_SIZE_COMPATIBILITY will be set automatically if the client targets version 6.2 or earlier.

Further non-compatibility-affecting changes include:

Version 6.2.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 6.2.0 and 6.1.0 include:

Version 6.1.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 6.1.0 and 6.0.0 include the following minor compatibility changes:

  • Fixed problems with configuration directories on Android. This involved changing drfront_access() to attempt to create a file by calling a new routine that is also exported, drfront_dir_try_writable().
  • Fixed several bugs.

Version 6.1.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 6.1.0 and 6.0.0 include the following minor compatibility changes:

Further non-compatibility-affecting changes include:

Version 6.0.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 6.0.0 and 5.0.0 include the following minor compatibility changes:

  • Deprecated dr_init() as a client's entry point, replacing it with dr_client_main() which is passed an argv-style array of client options just like a regular application's main() routine.
  • Changed the default injection method on Linux to use "early injection" which begins executing the target application from its very first instruction. Clients on Linux will now see more application code than they did previously. The old behavior can be requested by passing "-late" to drrun or drinject, or including "-no_early_inject" in the options to drinjectlib.
  • Moved the module load event to a later point where the application first executes code from the library. This enables clients to access properly relocated values inside the library, which was not possible with the prior event point at the first memory mapping of the library. Applications that still wish to see the first mapping will need to monitor system calls to replicate the old control point.
  • To support conditionally executed instructions, added a new parameter of type dr_opnd_query_flags_t to routines that explicitly query what was read or written by an instruction: instr_get_eflags(), instr_get_arith_flags(), decode_eflags_usage(), instr_writes_to_reg(), instr_reads_from_reg(), and instr_writes_to_exact_reg(). This new parameter determines how to treat conditionally accessed operands. We decided that breaking compatibility directly was the best solution to ensure that clients performing liveness analysis versus other types of usage analysis are properly updated to handle conditionally executed instructions. All other API routines include all operands whether conditionally accessed or not.
  • Removed the artificial additional source operand that was added to each OP_cmovcc and OP_fcmovcc instruction in the past. We have replaced this with the new predication API (instr_is_predicated(), etc.) and new parameters to read/write query routines (dr_opnd_query_flags_t).
  • Widened the reg_id_t type from a byte to a ushort.
  • Changed both drconfiglib and drinjectlib to be static libraries rather than shared libraries on UNIX platforms, for simpler usage without worrying about locating them at runtime, as well as making it easier to use on Android. They remain shared libraries on Windows.
  • Deprecated dr_get_options(), replacing it with direct arguments to dr_client_main() or alternatively with dr_get_option_array().
  • Deprecated set_x86_mode(), replacing it with dr_set_isa_mode().
  • Deprecated get_x86_mode(), replacing it with dr_get_isa_mode().
  • Deprecated instr_set_x86_mode(), replacing it with instr_set_isa_mode().
  • Deprecated instr_get_x86_mode(), replacing it with instr_get_isa_mode().
  • Added a third parameter to drfront_is_64bit_app().
  • Deprecated instr_is_sse_or_sse2().
  • Removed legacy executable bbcov2lcov.
  • Removed legacy "-t bbcov" support.

Further non-compatibility-affecting changes include:

Version 5.0.0 includes Dr. Memory and the Dr. Memory Framework (DRMF) in the same package as DynamoRIO. DRMF provides the umbra, drsyscall, and drsymcache Extensions for use by clients.

The changes between version 5.0.0 and 4.2.0 also include the following minor compatibility changes:

  • Dropped official support for Windows 2000. The core DynamoRIO engine should continue to work there, but the official release package will not run on Windows 2000.
  • Changed the third parameter to drsym_search_symbols_ex() from a bool to a uint flags in order to take in demangling flags. Binary compatibility is maintained as drsym_info_t's size was changed, but source compatibility is affected by this change.
  • Added collapsing of template parameters to "<>" for drsyms operations on Windows PDB symbols when DRSYM_DEMANGLE is specified. This can be undone by specifying DRSYM_DEMANGLE_PDB_TEMPLATES.
  • Removed empty parentheses "()" from partially-demangled symbols (when DRSYM_DEMANGLE is specified) for DRSYM_ELF_SYMTAB and DRSYM_PECOFF_SYMTAB. Windows and Linux symbols are now consistent for DRSYM_DEMANGLE.
  • Changed the operand sizes of instructions that read or write only part of a multimedia register (mmx, xmm, or ymm) to reflect the partial size.
  • Added return value for dr_fprintf to indicate how many bytes are written.
  • Renamed the function add_rel_rpaths() in DynamoRIOConfig.cmake to DynamoRIO_add_rel_rpaths().
  • Deprecated instr_ok_to_mangle() and instr_set_ok_to_mangle() (replaced with instr_is_app(), instr_is_meta(), instr_set_app(), and instr_set_meta()).

Further non-compatibility-affecting changes include:

The changes between version 4.2.0 and 4.1.0 include:

The changes between version 4.1.0 and 4.0.1 include the following compatibility changes:

  • The drsym_info_t data structure has changed. The file name is now a caller-allocated buffer, and it and the symbol name are separated out. This affects code that calls drsym_lookup_address().
  • Memory allocated through system libraries (including malloc, operator new, and HeapAlloc) is not guaranteed to be reachable by a 32-bit displacement from the code cache: only memory directly allocated via DR's API. The -reachable_heap runtime option can be used to guarantee that all memory is reachable.
  • For 64-bit, the opcode constants OP_fxsave, OP_fxrstor, OP_xsave, OP_xrstor, and OP_xsaveopt have all been replaced with two versions: one with a "32" suffix and one with a "64" suffix. E.g., OP_fxsave is split into OP_fxsave32 and OP_fxsave64. The 32 version corresponds to the no-suffix assembler mnemonic while the 64 version coresponds to the assembler mnemonic of the same name. Previously, the 64-bit versions of these instrutions could not be distinguished nor encoded from scratch.

Further non-compatibility-affecting changes include:

The changes between version 4.0.1 and 4.0.0 include:

  • Fixed a bug resulting in large 64-bit applications failing to allocate heap (Issue 1041)

The changes between version 4.0.0 and 3.2.0 include a compatibility change in the drsyms Extension:

And in the drmgr Extension:

And in the core API:

And in the non-core APIs:

  • dr_inject_process_create() now takes a NULL-terminated array of strings for the app command line to better support porting to Linux.

Further non-compatibility-affecting changes include:

The changes between version 3.2.0 and 3.1.0 are:

Version 3.0.0 was a development version. 3.1.0 is the first official released version of the 3.x series.

The changes between version 3.0.0 and 2.2.0 include the following major features:

  • Added a private loader on Linux for better support for C++ clients and third-party library usage by clients
  • Added Linux support for drsyms to enable symbol processing in Linux clients
  • Added drutil Extension which provides memory address retrieval and string loop expansion (note: LGPL license)
  • Added a static library for decoding and encoding

IMPORTANT: The 3.0.0 and onward client API is mostly backward compatible with releases from 1.0.0 (originally called 0.9.6: see below) onward with the exception of functions that involve dr_mcontext_t and several other source and binary compatibility changes since version 2.2.0 described below. The dr_mcontext_t struct and all structs that contain it have changed and are NOT backward compatible with releases prior to 3.0.0.

A sample script for updating client sources to the 3.0.0 API's version of dr_mcontext_t and related functions is as follows:

perl -pi -e '\
s|dr_mcontext_t (\w+);|dr_mcontext_t \1 = {sizeof(\1),DR_MC_ALL,};|;\
s|(dr_[gs]et_mcontext\(\S+,\s+\S+),\s+[^\s\)]+\)|\1)|;\
s|(dr_redirect_execution\(\S+),\s+\S+\)|\1)|;\
s|^\s+int app_errno;\s*\n||ms;\
s|raw_mcontext\.|raw_mcontext->|g;\
s|info->mcontext\.|info->mcontext->|g;\
s|excpt->mcontext\.|excpt->mcontext->|g;' *.c

The script makes 3 main changes. First, any dr_mcontext_t allocated by the client must have its size and flags fields set. Second, the app_errno parameter was removed from several functions; it required a local variable, so any local named app_errno is removed. Third, the dr_mcontext_t fields in the fault, signal, and exception structs all became pointers.

This script may not catch all cases. Use your version control system to look at the diff after applying it to ensure it did not change anything it shouldn't have. Run with debug build to catch other instances where dr_mcontext_t.size is not set. Also note that using the dr_mcontext_t initialization syntax in the script will end up calling memset; for performance-critical situations, instead initialize only the size and flags fields separately. Also note that if the xmm or ymm registers are not needed, asking for DR_MC_CONTROL and/or DR_MC_INTEGER is more performant than DR_MC_ALL.

IMPORTANT: Further changes between version 3.0.0 and 2.2.0 include the following that affect source and/or binary compatibilty:

  • Changed the dr_mcontext_t structure field layout. This is a binary compatibility change with respect to versions prior to 3.0.0.
  • Added a dr_mcontext_t.size field which must be set by the client prior to calling dr_get_mcontext(), dr_set_mcontext(), or dr_redirect_execution. This is a source compatibility change with respect to versions prior to 3.0.0.
  • Added a dr_mcontext_t.flags field which must be set by the client prior to calling dr_get_mcontext(), dr_set_mcontext(), or dr_redirect_execution. This is a source compatibility change with respect to versions prior to 3.0.0.
  • Removed the app_errno parameter from dr_get_mcontext(), dr_set_mcontext(), and dr_redirect_execution(). This is a source compatibility change with respect to versions prior to 3.0.0.
  • Changed all dr_mcontext_t fields in the dr_restore_state_info_t, dr_exception_t, and dr_siginfo_t structs to be pointers. This is a source compatibility change with respect to versions prior to 3.0.0.
  • Changed the bool typedef from int to char for C++ compatibility. This is a binary compatibility change with respect to versions prior to 3.0.0.
  • Changed the signature of drwrap_unwrap(), in order to allow one of the pre or post hooks to be optional (Issue 562). This is a source compatibility change with respect to versions prior to 3.0.0.
  • Moved console printing support from the drsyms Extension to core DR. The drsym_write_to_console() and drsym_using_console() are no longer supported. Instead, call dr_enable_console_printing() in dr_init(), which then enables dr_printf() and dr_fprintf() to print to the console (with some limitations: see dr_enable_console_printing() documentation). This is a source compatibility change with respect to versions prior to 3.0.0.
  • Added a flags argument to most of the routines in the drsyms extension to control demangling, and added drsym_demangle_symbol(). This is a source compatibility change with respect to versions prior to 3.0.0.
  • Added drsym_get_module_debug_kind() and a debug_kind field to the drsym_info_t struct written by drsym_lookup_address(). These additions allow drsyms users to determine what kind of debug info is available for a module. The debug_kind field creates a binary compatibility change for users of drsym_info_t with respect to versions prior to 3.0.0.

Additional changes between version 3.0.0 and 2.2.0 include the following:

The changes between version 2.2.0 and 2.1.0 are:

  • Added drwrap Extension which provides function wrapping and replacing (note: LGPL license)
  • Added drmgr Extension: the DynamoRIO Multi-Instrumentation Manager Extension, a mediator for combining and coordinating multiple instrumentation passes
  • Added read-write locks (Issue 406)
  • Added isolation of client-opened files from the application (Issue 357)
  • Added dr_mcontext_t.xip for syscall events (Issue 442)
  • Several bug fixes

The changes between version 2.1.0 and 2.0.0 are:

  • Added Windows 7 support
  • Added clean call sequence optimization and auto-inlining.
  • Added Windows child process following support for clients: -follow_children is now on by default for both Windows and Linux.
  • Added DR_TRY_EXCEPT() (Issue 51)
  • Added dynamic client auxiliary library loading support via dr_load_aux_library(), dr_lookup_aux_library_routine(), and dr_unload_aux_library()
  • Added dr_switch_to_app_state() and dr_switch_to_dr_state()
  • Added dr_client_thread_set_suspendable()
  • Added dr_get_random_value(), dr_set_random_seed(), and dr_get_random_seed()
  • Added dr_file_exists() and dr_directory_exists() for Linux
  • Added support for dr_get_mcontext() from secondary thread init events, and changed its return type to bool
  • Added dynamic hashtable resizing to the drcontainers hashtable
  • Added dr_app_pc_from_cache_pc()
  • Added a segment list to module_data_t for Linux and internal support for non-contiguously-mapped modules (Issue 160)
  • Added PEB isolation (Issue 249) and dr_get_app_PEB()
  • Added drsym_enumerate_symbols() to the drsyms Extension
  • Added limited support for printing to the cmd window (Issue 261) via the drsyms Extension: drsym_write_to_console() and drsym_using_console()
  • Renamed the REG_ constants to DR_REG_ to avoid conflicts with system headers (Issue 34). Clients should set(DynamoRIO_REG_COMPATIBILITY ON) prior to configure_DynamoRIO_client() to use the old constants and avoid any source changes; this will happen automatically if the client targets version 2.0 or earlier. Binary compatibility is unaffected.
  • Deprecated dr_request_synchronized_exit() and replaced it with dr_set_process_exit_behavior(). Now a full thread synch is performed at exit time in release build if a process exit event or thread exit event is registered. dr_set_process_exit_behavior() can provide more performant exit performance for clients that have flexible exit event requirements.
  • Switched debug build to also be an INTERNAL=ON build
  • Fixed bug in handling single-byte-bb selfmod code
  • Fixed bugs in handling alarm signals
  • Fixed 64-bit Windows stack alignment bug (Issue 331)
  • Fixed handling of "data32 rex.w call"
  • Fixed Issue 320: a problem with thread-private cache resizing
  • Fixed Issue 319: decode movlhps and movhlps properly
  • Fixed Issue 139: add xmm0-7 preservation for 32-bit Linux applications, which may have noticeable impacts on clients calling clean calls: e.g., pushing bbs over the max size limit or having a noticeable performance hit.
  • Support building sources using Visual Studio

In version 2.0.0, the configuration and deployment API and tools changed and are not backward compatible with earlier versions: see below for details. The changes between version 2.0.0 and 1.5.0 are:

  • Changed the configuration and deployment model for both Linux and Windows to use a configuration file based approach on both platforms, which adds control over child processes on Linux and supports local configuration on Windows for un-privileged and parallel execution (Issue 265). The registry is no longer used for individual application configuration on Windows other than to point at the location for global configuration files, when used.
    IMPORTANT: On Windows the following non-backward-compatible changes have been made:

    • drdeploy.exe no longer exists (replaced by drconfig.exe and drrun.exe)
    • drconfig.dll is now drconfiglib.dll
    • drconfiglib.dll's API routines now take in a process id to support one-time targeted-process configuration (to support parallel execution)
    • configuration is either per-user or global, with per-user taking precedence when both exist
    • configuration does NOT enable systemwide injection by default: use the -syswide_on parameter to drconfig or drrun for that (it requires administrative privileges)

    IMPORTANT: On Linux, if you're using custom injection via raw environment variables rather than using the drdeploy script, you must also set DYNAMORIO_RUNUNDER to 1 for injection to work with this release.

  • Added drinjectlib.dll and dr_inject.h, making custom injection tools easier to build (Issue 246)
  • Added DynamoRIO Extension support for auxiliary libraries that extend the DynamoRIO API (Issue 277)
  • Added symbol lookup support via Extension (Windows only for now) (Issue 44)
  • Added a "drcontainers" Extension that initially contains a hashtable
  • Added thread creation support: dr_create_client_thread() (Issue 41)
  • Added dr_sleep()
  • Added dr_set_itimer() and dr_get_itimer() (Linux-only) (Issue 283)
  • Added dr_app_pc_for_decoding()
  • Added -synch_at_exit option and dr_request_synchronized_exit() to provide guarantees over thread exit event timing in release build
  • Added instr_cmovcc_triggered() and instr_cmovcc_to_jcc()
  • Renamed OP_fcmovene to OP_fcmovne
  • Implemented instr_invert_cbr() for OP_jcc_short
  • Added the full path to modules in module_data_t
  • Added dr_get_proc_address_ex() to support indirect code objects
  • Added dr_get_milliseconds() and dr_get_time() impl for Linux
  • Added instr_is_undefined()

The changes between version 1.5.0 and 1.4.0 are:

The changes between version 1.4.0 and 1.3.2 are:

  • Added directly-addressable thread-local storage slots for exclusive client use:
  • Provide 64-bit versions of the drdeploy.exe and drview.exe tools
  • Provide dr_get_proc_address() on Linux
  • Added dr_query_memory_ex() to allow address space walking on Linux
  • Added -msgbox_mask on Linux: waits for a keypress
  • Added shared library versioning on Linux
  • Support calling dr_get_mcontext() from bb and trace callbacks
  • Provide support for building clients using CMake (see cmake/, and for an example of usage see samples/CMakeLists.txt)
  • Provide support for clients to use -fvisibility by setting the define USE_VISIBILITY_ATTRIBUTES for dr_defines.h
  • Added instr_compute_address_ex() for instrs with multiple memory operands
  • Provide dr_snprintf() (identical to snprintf()) for consistent naming and to avoid gcc warnings about using pointers with x (which we're using because there is no portable way to precisely control p)
  • The statistics viewer DRgui.exe is no longer supported on Windows NT. Statistics still work, but the graphical application itself will not run on NT.
  • Changed the top-level registry key to "DynamoRIO"
  • Re-arranged layout of bin and samples directories
  • Symbols for all binaries are now included

The changes between version 1.3.2 and 1.3.1 are:

  • Added support for Linux execve of cross-architectural executables (e.g., 32-bit process performing execve of 64-bit executable)
    • Also, libdrpreload.so is now kept in the same libXX/{debug,release} directory as libdynamorio.so
  • instr_convert_short_meta_jmp_to_long() now returns the longer version of the taken jump, to use when setting the target of a jecxz or loop* branch.
  • Various bug fixes including in these areas:

Version 1.3.1 is identical to 1.3.0 but is under a BSD license (see License).

We re-numbered the previous DynamoRIO versions as follows:

  • 1.0.0 = 0.9.6 build 9600
  • 1.1.0 = 0.9.6 build 9601
  • 1.2.0 = 0.9.6 build 9602

The changes between version 1.3.0 and version 1.2.0 (0.9.6 9602) are:

The changes between the 0.9.6 release builds 9602 and 9601 are:

The changes between the 0.9.6 release builds 9601 and 9600 are:

Release 0.9.6 is not backward compatible with prior releases 0.9.1-0.9.5.

The major changes between the 0.9.6 and 0.9.5 releases include 64-bit support, multiple clients, state translation, trace contents, and Linux module events and fast system calls:

The major changes between the 0.9.5 and 0.9.4 releases are:

  • The basic block hook (Basic Block Creation) passes completely unmodified application code to the client (no mangling or elision).
  • The old client hook exports have been replaced with an explicit event registration model.
  • Instruction representation simplification: the client only sees fully decoded instructions.
  • Easier-to-use clean calls (see dr_insert_clean_call).
  • Library support (-wrap on linux, ntdll on windows: see Using External Libraries and Common Utilities).
  • Some features have been removed (these are easily implemented by a client): there is no more edge-counting profile build, no more custom exit stubs, and no more prefixes.
  • Infrastructure improvements:
  • Module events (dr_register_module_load_event), module iteration (dr_module_iterator_start, dr_lookup_module, etc.), and memory querying (dr_query_memory, dr_virtual_query).
  • The full API is now documented in html and pdf for easy browsing.
  • Numerous type and routine name changes.

Limitations

Client Limitations

The most important limitation on a client is that it remain transparent. This is described fully in Client Transparency. Here we summarize the key points to remain transparent:

  • For full transparency, the client should be a self-contained library with linkage to nothing other than DynamoRIO libraries. We provide private loading that makes some use of system libraries safe, but global resource conflicts can still occur and clients are cautioned from using system-interacting library routines. See Using External Libraries for further details.
  • Currently, the communication API provided by DynamoRIO is limited to file I/O and nudges.

Platform Limitations

  • This version of DynamoRIO supports Windows 8, 8.1, and 10. However, systemwide injection (-syswide_on) is not yet supported on Windows 8 or higher except for WOW64 (i.e., 32-bit applications on a 64-bit kernel).
  • DynamoRIO currently supports the following NT-based 32-bit Windows systems: XP (32-bit, service packs 0-3), 2003 (32-bit, service packs 0-2), Vista (32-bit, service packs 0-1), Windows 7 (32-bit, service packs 0-1), Windows 8, Windows 8.1, and Windows 10. It does not support Windows 95, 98, or ME. It no longer officially supports NT (all service packs) or 2000 (all service packs), although the core DynamoRIO library should still work there: it is only the tools and utility programs that will fail to run. Windows Server 2008 is expected to work but has not been tested.
  • This release of DynamoRIO supports running 32-bit Windows applications on the following 64-bit Windows operating systems: Windows XP Professional x64 (service pack 2), Windows 2003 x64 (service pack 2), Vista x64 (service packs 0-1), Windows 7 (service packs 0-1), Windows Server 2008, Windows 8, Windows 8.1, and Windows 10. Only the 32-bit code will be seen, and child processes created will not be injected into. On 64-bit Windows 32-bit applications are automatically run through the Windows-On-Windows or WOW64 emulator so system call and indirect call processing clients must be aware of instr_is_wow64_syscall().
  • On all versions of Windows, attaching DynamoRIO to an already-running process can result in loss of control if the attach point is in the middle of an operating system event callback. From the callback return point until the next system call hook, no instructions will be observed by a client.
  • This release of DynamoRIO supports running 64-bit Windows applications, using the 64-bit DynamoRIO build, on the following 64-bit Windows systems: Windows XP Professional x64 (service pack 2), Windows 2003 x64 (service pack 2), Vista x64 (service packs 0-1), Windows 7 x64 (service packs 0-1), Windows 8, Windows 8.1, and Windows 10. Windows Server 2008 is expected to work but has not been tested.
  • DynamoRIO does not support any Itanium based Windows systems.
  • This release does not fully support applications that mix 32-bit and 64-bit code. Future releases will support such mixtures.
  • When running a cygwin application under control of DynamoRIO, stderr and stdout output from DynamoRIO or its clients may not be visible.
  • UTF-8 support is not yet present in drinjectlib, drconfiglib, drrun.exe, drconfig.exe, or drinject.exe. It is present in the core DR API.
  • This release of DynamoRIO has support for most 32-bit and 64-bit Linux distributions running on Intel-compatible hardware, including Ubuntu and Fedora.
  • This release of DynamoRIO has support for running 32-bit Linux applications on 64-bit Linux operating systems on AMD64-compatible hardware.
  • Cross-architecture execve (e.g., a 32-bit process performing execve of a 64-bit executable) may stop working if the paths to the libdynamorio.so and libdrpreload.so libraries are renamed.
  • This release of DynamoRIO supports 32-bit applications running on 32-bit Linux operating systems on AArch32 ARMv7 and ARMv8 hardware. However, a few features are not yet ported: traces, clean call inlining and other optimizations, and several samples.
  • This release of DynamoRIO has experimental support for 32-bit Android applications running on AArch32 ARMv7 and ARMv8 hardware. However, a few features are not yet ported: traces, clean call inlining and other optimizations, and several samples.
  • This release of DynamoRIO has experimental support for 64-bit applications running on 64-bit Linux operating systems on AArch64 ARMv8 hardware. However, floating-point and SIMD instruction operands are not fully decoded or encoded yet, and a few features are not yet ported: traces, clean call inlining and other optimizations, and several samples and provided tools.
  • This release of DynamoRIO includes support for applications using the Linux kernel restartable sequence ("rseq") feature, subject to the limitations listed in Restartable Sequence Instrumentation Constraints.

Performance Limitations

  • In order to present a more straightforward code stream to clients, DynamoRIO has several optimizations disabled in this release. System-call-heavy applications are the ones most likely to be affected. Future releases may allow clients to choose performance versus visibility. This release does provide the -opt_memory option to enable prioritizing memory usage and the -opt_speed option to prioritize performance at the cost of more complex basic blocks that cross control transfers.
  • The performance when starting up large desktop applications may be noticeably worse than native. Upcoming releases will address this issue.
  • The performance when running Java, .Net, Flash or similar managed execution applications can be noticeably worse then native. This can include applications that load these components as in-process plugins (such as Internet Explorer). Upcoming releases will address this issue.
  • When using DynamoRIO on all or many processes on a system simultaneously, memory usage may become a factor. Upcoming releases will address this issue.

Deployment Limitations

  • The dr_config.lib library is not multi-thread safe. Users of the library should ensure that no more then one thread accesses the library at a time.
  • Other installed software that uses hooks may not always be interoperable with DynamoRIO.
  • Other installed software may conflict with DynamoRIO's use of the \HKLM\SOFTWARE\Microsoft\Windows\WindowsNT\CurrentVersion\AppInit_DLLs registry key (only very rarely an issue), which is used for the -syswide_on feature.
  • On Windows, the Enhanced Mitigation Experience Toolkit (EMET) may prevent applications from running under DynamoRIO (issue 1546). Please disable EMET for the application if necessary.
  • On Windows 7 and Windows Server 2008 R2, the digital signature requirement for AppInit_DLLs libraries is disabled when systemwide injection is requested (-syswide_on). This can be a security concern.
  • On Windows 8 or 8.1, system wide injection (-syswide_on) is not yet supported.
  • Cygwin processes may not work with DynamoRIO due to cygwin's implementation of fork being incompatible with DynamoRIO.
  • A Windows application that does not statically link with user32.dll will not be run under control of DynamoRIO using system-wide injection unless its parent process (typically cmd.exe or explorer.exe, for manually launched applications) is already under DynamoRIO control. Only some small non-graphical applications do not link with user32.dll.
  • When invoking an application in any way that is not from a parent process under DynamoRIO control, DynamoRIO takes control a little later and in some rare cases the application has already created a new thread. This is in violation of the Windows specficiations, but cygwin processes do this. This new thread will not be under DynamoRIO control and can cause a variety of problems. In such cases it is best to invoke from a parent process under DynamoRIO control. However, for 32-bit applications on 64-bit Windows operating systems, DynamoRIO takes over later even from the parent. Future releases will address this limitation.
  • This release does not support running some Windows services under control of DynamoRIO: the "System" process, smss.exe, csrss.exe, and protected processes on Windows Vista.

  • On Windows Vista most services are run in a separate session as a security feature. This means that neither DynamoRIO nor its client will be able to display a messagebox when running in said services (they have no associated visible window station). See dr_messagebox().
  • On Windows Vista the code from certain dlls (found mostly in services) and the code subsequently called from those dlls is run natively and is not visible to the instrumentation APIs. This only applies to dlls that have a .pexe section (only 13 dlls have such a section in a standard Vista install) which seems to be associated with a likely obfuscation method involving kernel side components that this release has no other workaround for.
  • On Linux, non-default late injection (requested via -late to drrun) is unable to run binaries with the suid or sgid permission bits set. Default injection is capable of executing these binaries, but if late injection is desired, one method of running these binaries is to place both libdrpreload.so and libdynamorio's full paths in /etc/ld.so.preload. You'll need to use a separate configure step approach. Don't forget to run drconfig to create a configuration for the application first; otherwise, libdrpreload.so will refuse to take control. This method of injection takes control part-way through initialization of the target application, rather than at the very beginning. Alternatively, you could run as root, or remove the suid and sgid bits: however, both of those solutions may open up security holes and are not recommended. If the suid or sgid binary is a leaf child process of the parent target application, another option is to run the problematic child process natively by either creating a configuration file for the child with the "-norun" parameter or running with the -no_follow_children runtime option.
  • On Linux, the private loader will fail to load libpthread.so. Therefore clients and the libraries they use cannot link against libpthread.so.

Plans for Future Releases

We hope to include the following major features in future releases:

  • Libraries to facilitate building tools that use shadow memory, examine system calls, and insert heavyweight instrumentation.
  • Earliest Windows injection. Today drinject injects fairly late; from a parent process, injection is very early (before kernel32.dll is loaded), but we plan to provide injection at the very first user-mode instruction in the future.
  • Persistent and process-shared code caches.
  • Full control over trace building.

To discuss current and future features, join the DynamoRIO Users group.