DynamoRIO API
Release Notes for Version 7.1.0

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 DynamoRIO Extensions).
  • 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 Cache Simulator), a last-level cache miss analyzer (see Cache Simulator), 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 7.1.0. 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 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 Licenses).

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().
  • 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.

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.
  • More flexible (earlier, or later via attach) Linux injection
  • Persistent and process-shared code caches
  • Full control over trace building

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