DynamoRIO
Build Your Own Tool

DynamoRIO is a runtime code manipulation system that supports code transformations on any part of a program, while it executes. DynamoRIO gives complete control over the runtime code stream and does not limit transformations to trampoline insertion. DynamoRIO exports an interface for building dynamic tools for a wide variety of uses: program analysis and understanding, profiling, instrumentation, optimization, translation, etc. DynamoRIO provides efficient, transparent, and comprehensive manipulation of an unmodified application running on a stock operating system (Windows, Linux, or Android) and commodity IA-32, AMD64, ARM, and AArch64 hardware. See Platform Limitations for details of which platform combinations are fully supported.

This document describes the DynamoRIO system and the various APIs that it exports for building custom tools. It is divided into the following sections:

  • Tutorials
    Gives a few short tutorials on using DynamoRIO and includes slides from prior in-person tutorial presentations.
  • Sample Tools
    Shows some sample use cases and reference implementations.
  • How to Build a Tool
    How to build a tool or "client" of DynamoRIO.
  • How to Run
    How to run DynamoRIO.
  • Tool Event Model and API
    The top-level interfaces provided to a tool.
  • Code Manipulation API
    DynamoRIO's full runtime code manipulation interface.
  • Extension API
    DynamoRIO's API is augmented by a collection of extension libraries.
  • Disassembly Library
    DynamoRIO can be used as a standalone library for IA-32/AMD64/ARM/AArch64 disassembly, decoding, encoding, and general instruction manipulation. A separate static library is provided for this purpose.
  • DynamoRIO System Overview
    A description of the implementation of the DynamoRIO system.
  • Release Notes for Version 9.0.19046
    Release notes for this release, including changes since prior releases and plans for future releases.


_dr_mcontext_t
Definition: dr_defines.h:765
dr_restore_arith_flags
DR_API void dr_restore_arith_flags(void *drcontext, instrlist_t *ilist, instr_t *where, dr_spill_slot_t slot)
dr_annotation_register_call
DR_API bool dr_annotation_register_call(const char *annotation_name, void *callee, bool save_fpstate, uint num_args, dr_annotation_calling_convention_t call_type)
dr_log
DR_API void dr_log(void *drcontext, uint mask, uint level, const char *fmt,...)
dr_mark_trace_head
DR_API bool dr_mark_trace_head(void *drcontext, void *tag)
instr_set_num_opnds
DR_API void instr_set_num_opnds(void *drcontext, instr_t *instr, int num_dsts, int num_srcs)
dr_insert_cbr_instrumentation
DR_API void dr_insert_cbr_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee)
DR_ASSERT
#define DR_ASSERT(x)
Definition: dr_tools.h:99
dr_app_stop_and_cleanup_with_stats
DR_APP_API void dr_app_stop_and_cleanup_with_stats(dr_stats_t *drstats)
instr_is_call_indirect
DR_API bool instr_is_call_indirect(instr_t *instr)
dr_reg_spill_slot_opnd
DR_API opnd_t dr_reg_spill_slot_opnd(void *drcontext, dr_spill_slot_t slot)
dr_mutex_lock
DR_API void dr_mutex_lock(void *mutex)
instr_get_next_app
DR_API INSTR_INLINE instr_t * instr_get_next_app(instr_t *instr)
dr_app_setup_and_start
DR_APP_API int dr_app_setup_and_start(void)
dr_insert_write_tls_field
DR_API void dr_insert_write_tls_field(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg)
dr_using_all_private_caches
DR_API bool dr_using_all_private_caches(void)
dr_app_cleanup
DR_APP_API int dr_app_cleanup(void)
dr_save_reg
DR_API void dr_save_reg(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg, dr_spill_slot_t slot)
decode
DR_API byte * decode(void *drcontext, byte *pc, instr_t *instr)
dr_standalone_init
DR_API void * dr_standalone_init(void)
dr_insert_save_fpstate
DR_API void dr_insert_save_fpstate(void *drcontext, instrlist_t *ilist, instr_t *where, opnd_t buf)
instr_set_dst
DR_API void instr_set_dst(instr_t *instr, uint pos, opnd_t opnd)
OPND_CREATE_MEM32
#define OPND_CREATE_MEM32(base_reg, disp)
Definition: dr_ir_macros.h:80
dr_app_stop
DR_APP_API void dr_app_stop(void)
dr_register_thread_init_event
DR_API void dr_register_thread_init_event(void(*func)(void *drcontext))
instrlist_first
DR_API instr_t * instrlist_first(instrlist_t *ilist)
dr_open_file
DR_API file_t dr_open_file(const char *fname, uint mode_flags)
dr_thread_alloc
DR_API void * dr_thread_alloc(void *drcontext, size_t size)
instr_reset
DR_API void instr_reset(void *drcontext, instr_t *instr)
instr_noalloc_init
DR_API void instr_noalloc_init(void *drcontext, instr_noalloc_t *instr)
dr_insert_ubr_instrumentation
DR_API void dr_insert_ubr_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee)
SPILL_SLOT_2
@ SPILL_SLOT_2
Definition: dr_ir_utils.h:68
dr_app_start
DR_APP_API void dr_app_start(void)
INSTR_CREATE_dec
#define INSTR_CREATE_dec(dc, d)
Definition: dr_ir_macros_x86.h:1579
dr_api.h
Top-level include file for DynamoRIO API.
instr_set_meta
DR_API void instr_set_meta(instr_t *instr)
dr_register_thread_exit_event
DR_API void dr_register_thread_exit_event(void(*func)(void *drcontext))
INSTR_CREATE_inc
#define INSTR_CREATE_inc(dc, d)
Definition: dr_ir_macros_x86.h:1578
dr_thread_free
DR_API void dr_thread_free(void *drcontext, void *mem, size_t size)
dr_write_saved_reg
DR_API void dr_write_saved_reg(void *drcontext, dr_spill_slot_t slot, reg_t value)
dr_close_file
DR_API void dr_close_file(file_t f)
_dr_restore_state_info_t
Definition: dr_events.h:664
instr_get_app_pc
DR_API app_pc instr_get_app_pc(instr_t *instr)
instr_get_arith_flags
DR_API uint instr_get_arith_flags(instr_t *instr, dr_opnd_query_flags_t flags)
dr_get_current_drcontext
DR_API void * dr_get_current_drcontext(void)
dr_client_main
DR_EXPORT void dr_client_main(client_id_t id, int argc, const char *argv[])
OPND_CREATE_ABSMEM
#define OPND_CREATE_ABSMEM(addr, size)
Definition: dr_ir_macros_aarch64.h:96
EFLAGS_READ_6
#define EFLAGS_READ_6
Definition: dr_ir_instr.h:2392
LOCK
#define LOCK(instr_ptr)
Definition: dr_ir_macros_x86.h:60
OPND_CREATE_INT8
#define OPND_CREATE_INT8(val)
Definition: dr_ir_macros.h:134
DR_QUERY_DEFAULT
@ DR_QUERY_DEFAULT
Definition: dr_ir_instr.h:212
DR_LOG_ALL
#define DR_LOG_ALL
Definition: dr_tools.h:1543
OP_dec
@ OP_dec
Definition: dr_ir_opcodes_x86.h:86
instr_set_src
DR_API void instr_set_src(instr_t *instr, uint pos, opnd_t opnd)
INSTR_XL8
#define INSTR_XL8(instr_ptr, app_addr)
Definition: dr_ir_macros.h:63
dr_app_setup
DR_APP_API int dr_app_setup(void)
dr_get_thread_id
DR_API thread_id_t dr_get_thread_id(void *drcontext)
dr_get_tls_field
DR_API void * dr_get_tls_field(void *drcontext)
dr_mutex_create
DR_API void * dr_mutex_create(void)
proc_restore_fpstate
DR_API void proc_restore_fpstate(byte *buf)
OPND_CREATE_INT32
#define OPND_CREATE_INT32(val)
Definition: dr_ir_macros.h:122
INSTR_CREATE_adc
#define INSTR_CREATE_adc(dc, Rd, Rn, Rm_or_imm)
Definition: dr_ir_macros_arm.h:1191
instr_get_next
DR_API INSTR_INLINE instr_t * instr_get_next(instr_t *instr)
dr_save_arith_flags
DR_API void dr_save_arith_flags(void *drcontext, instrlist_t *ilist, instr_t *where, dr_spill_slot_t slot)
dr_emit_flags_t
dr_emit_flags_t
Definition: dr_events.h:82
EFLAGS_WRITE_6
#define EFLAGS_WRITE_6
Definition: dr_ir_instr.h:2394
dr_app_take_over
DR_APP_API void dr_app_take_over(void)
instr_get_opcode
DR_API int instr_get_opcode(instr_t *instr)
instr_init
DR_API void instr_init(void *drcontext, instr_t *instr)
hashtable_add_replace
void * hashtable_add_replace(hashtable_t *table, void *key, void *payload)
instrlist_meta_preinsert
DR_API void instrlist_meta_preinsert(instrlist_t *ilist, instr_t *where, instr_t *instr)
OPND_CREATE_INT_32OR8
#define OPND_CREATE_INT_32OR8(val)
Definition: dr_ir_macros.h:141
opnd_create_reg
DR_API INSTR_INLINE opnd_t opnd_create_reg(reg_id_t r)
dr_app_running_under_dynamorio
DR_APP_API bool dr_app_running_under_dynamorio(void)
instr_is_return
DR_API bool instr_is_return(instr_t *instr)
instrlist_t
struct _instrlist_t instrlist_t
Definition: dr_defines.h:788
dr_fprintf
DR_API ssize_t dr_fprintf(file_t f, const char *fmt,...)
TIDFMT
#define TIDFMT
Definition: dr_defines.h:579
OPND_CREATE_MEM64
#define OPND_CREATE_MEM64(base_reg, disp)
Definition: dr_ir_macros.h:77
instrlist_meta_postinsert
DR_API void instrlist_meta_postinsert(instrlist_t *ilist, instr_t *where, instr_t *instr)
dr_insert_call_instrumentation
DR_API void dr_insert_call_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee)
dr_insert_read_tls_field
DR_API void dr_insert_read_tls_field(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg)
dr_insert_mbr_instrumentation
DR_API void dr_insert_mbr_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee, dr_spill_slot_t scratch_slot)
instr_from_noalloc
DR_API INSTR_INLINE instr_t * instr_from_noalloc(instr_noalloc_t *noalloc)
dr_mutex_unlock
DR_API void dr_mutex_unlock(void *mutex)
dr_register_bb_event
DR_API void dr_register_bb_event(dr_emit_flags_t(*func)(void *drcontext, void *tag, instrlist_t *bb, bool for_trace, bool translating))
dr_replace_fragment
DR_API bool dr_replace_fragment(void *drcontext, void *tag, instrlist_t *ilist)
instr_set_opcode
DR_API void instr_set_opcode(instr_t *instr, int opcode)
instr_writes_memory
DR_API bool instr_writes_memory(instr_t *instr)
OPSZ_8
@ OPSZ_8
Definition: dr_ir_opnd.h:83
dr_messagebox
DR_API void dr_messagebox(const char *fmt,...)
INVALID_FILE
#define INVALID_FILE
Definition: dr_defines.h:325
PFX
#define PFX
Definition: dr_defines.h:569
dr_get_mcontext
DR_API bool dr_get_mcontext(void *drcontext, dr_mcontext_t *context)
dr_register_exit_event
DR_API void dr_register_exit_event(void(*func)(void))
INSTR_CREATE_add
#define INSTR_CREATE_add(dc, Rd, Rn, Rm_or_imm)
Definition: dr_ir_macros_arm.h:1201
instr_is_call_direct
DR_API bool instr_is_call_direct(instr_t *instr)
dr_flush_region_ex
DR_API bool dr_flush_region_ex(app_pc start, size_t size, void(*flush_completion_callback)(void *user_data), void *user_data)
instrlist_encode
DR_API byte * instrlist_encode(void *drcontext, instrlist_t *ilist, byte *pc, bool has_instr_jmp_targets)
INSTR_CREATE_mov_st
#define INSTR_CREATE_mov_st(dc, d, s)
Definition: dr_ir_macros_x86.h:1206
proc_save_fpstate
DR_API size_t proc_save_fpstate(byte *buf)
dr_printf
DR_API void dr_printf(const char *fmt,...)
instr_encode
DR_API byte * instr_encode(void *drcontext, instr_t *instr, byte *pc)
dr_insert_clean_call
DR_API void dr_insert_clean_call(void *drcontext, instrlist_t *ilist, instr_t *where, void *callee, bool save_fpstate, uint num_args,...)
dr_mutex_destroy
DR_API void dr_mutex_destroy(void *mutex)
instr_free
DR_API void instr_free(void *drcontext, instr_t *instr)
DR_EMIT_DEFAULT
@ DR_EMIT_DEFAULT
Definition: dr_events.h:84
instrlist_meta_append
DR_API void instrlist_meta_append(instrlist_t *ilist, instr_t *instr)
dr_read_saved_reg
DR_API reg_t dr_read_saved_reg(void *drcontext, dr_spill_slot_t slot)
instr_opcode_valid
DR_API bool instr_opcode_valid(instr_t *instr)
dr_restore_reg
DR_API void dr_restore_reg(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg, dr_spill_slot_t slot)
instr_t
Definition: dr_defines.h:371
instrlist_first_app
DR_API instr_t * instrlist_first_app(instrlist_t *ilist)
instr_noalloc_t
Definition: dr_ir_instr.h:324
OPSZ_4
@ OPSZ_4
Definition: dr_ir_opnd.h:81
instr_is_mbr
DR_API bool instr_is_mbr(instr_t *instr)
dr_app_stop_and_cleanup
DR_APP_API void dr_app_stop_and_cleanup(void)
instr_create
DR_API instr_t * instr_create(void *drcontext)
dr_set_tls_field
DR_API void dr_set_tls_field(void *drcontext, void *value)
dr_insert_restore_fpstate
DR_API void dr_insert_restore_fpstate(void *drcontext, instrlist_t *ilist, instr_t *where, opnd_t buf)
client_id_t
uint client_id_t
Definition: dr_defines.h:350
dr_global_alloc
DR_API void * dr_global_alloc(size_t size)
OPND_CREATE_INTPTR
#define OPND_CREATE_INTPTR
Definition: dr_ir_macros.h:108