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 10.93.19915
    Release notes for this release, including changes since prior releases and plans for future releases.

Definition: dr_defines.h:879
DR_API void dr_restore_arith_flags(void *drcontext, instrlist_t *ilist, instr_t *where, dr_spill_slot_t slot)
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_API void dr_log(void *drcontext, uint mask, uint level, const char *fmt,...)
DR_API bool dr_mark_trace_head(void *drcontext, void *tag)
DR_API void instr_set_num_opnds(void *drcontext, instr_t *instr, int num_dsts, int num_srcs)
DR_API void dr_insert_cbr_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee)
#define DR_ASSERT(x)
Definition: dr_tools.h:114
DR_APP_API void dr_app_stop_and_cleanup_with_stats(dr_stats_t *drstats)
DR_API bool instr_is_call_indirect(instr_t *instr)
DR_API opnd_t dr_reg_spill_slot_opnd(void *drcontext, dr_spill_slot_t slot)
DR_API void dr_mutex_lock(void *mutex)
DR_API INSTR_INLINE instr_t * instr_get_next_app(instr_t *instr)
DR_APP_API int dr_app_setup_and_start(void)
DR_API void dr_insert_write_tls_field(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg)
#define TESTALL(mask, var)
Definition: droption.h:55
DR_API bool dr_using_all_private_caches(void)
DR_APP_API int dr_app_cleanup(void)
DR_API void dr_save_reg(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg, dr_spill_slot_t slot)
DR_API byte * decode(void *drcontext, byte *pc, instr_t *instr)
DR_API void * dr_standalone_init(void)
DR_API void dr_insert_save_fpstate(void *drcontext, instrlist_t *ilist, instr_t *where, opnd_t buf)
DR_API void instr_set_dst(instr_t *instr, uint pos, opnd_t opnd)
#define OPND_CREATE_MEM32(base_reg, disp)
Definition: dr_ir_macros.h:82
DR_APP_API void dr_app_stop(void)
DR_API void dr_register_thread_init_event(void(*func)(void *drcontext))
DR_API instr_t * instrlist_first(instrlist_t *ilist)
DR_API file_t dr_open_file(const char *fname, uint mode_flags)
DR_API void * dr_thread_alloc(void *drcontext, size_t size)
DR_API void instr_reset(void *drcontext, instr_t *instr)
DR_API void instr_noalloc_init(void *drcontext, instr_noalloc_t *instr)
DR_API void dr_insert_ubr_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee)
Definition: dr_ir_utils.h:68
DR_APP_API void dr_app_start(void)
#define INSTR_CREATE_dec(dc, d)
Definition: dr_ir_macros_x86.h:1592
Top-level include file for DynamoRIO API.
DR_API void instr_set_meta(instr_t *instr)
DR_API void dr_register_thread_exit_event(void(*func)(void *drcontext))
#define INSTR_CREATE_inc(dc, d)
Definition: dr_ir_macros_x86.h:1591
DR_API void dr_thread_free(void *drcontext, void *mem, size_t size)
#define DR_REG_XDI
Definition: dr_ir_opnd.h:1671
DR_API void dr_write_saved_reg(void *drcontext, dr_spill_slot_t slot, reg_t value)
DR_API void dr_close_file(file_t f)
Definition: dr_events.h:724
DR_API app_pc instr_get_app_pc(instr_t *instr)
DR_API uint instr_get_arith_flags(instr_t *instr, dr_opnd_query_flags_t flags)
DR_API void * dr_get_current_drcontext(void)
DR_EXPORT void dr_client_main(client_id_t id, int argc, const char *argv[])
#define OPND_CREATE_ABSMEM(addr, size)
Definition: dr_ir_macros_aarch64.h:102
#define EFLAGS_READ_6
Definition: dr_ir_instr.h:2634
#define LOCK(instr_ptr)
Definition: dr_ir_macros_x86.h:60
#define OPND_CREATE_INT8(val)
Definition: dr_ir_macros.h:136
Definition: dr_ir_instr.h:255
#define DR_LOG_ALL
Definition: dr_tools.h:1569
@ OP_dec
Definition: dr_ir_opcodes_x86.h:87
DR_API void instr_set_src(instr_t *instr, uint pos, opnd_t opnd)
#define INSTR_XL8(instr_ptr, app_addr)
Definition: dr_ir_macros.h:65
DR_APP_API int dr_app_setup(void)
DR_API thread_id_t dr_get_thread_id(void *drcontext)
DR_API void * dr_get_tls_field(void *drcontext)
DR_API void * dr_mutex_create(void)
DR_API void proc_restore_fpstate(byte *buf)
#define OPND_CREATE_INT32(val)
Definition: dr_ir_macros.h:124
#define INSTR_CREATE_adc(dc, Rd, Rn, Rm_or_imm)
Definition: dr_ir_macros_arm.h:1191
DR_API INSTR_INLINE instr_t * instr_get_next(instr_t *instr)
DR_API void dr_save_arith_flags(void *drcontext, instrlist_t *ilist, instr_t *where, dr_spill_slot_t slot)
Definition: dr_events.h:138
#define EFLAGS_WRITE_6
Definition: dr_ir_instr.h:2636
DR_APP_API void dr_app_take_over(void)
DR_API int instr_get_opcode(instr_t *instr)
DR_API void instr_init(void *drcontext, instr_t *instr)
void * hashtable_add_replace(hashtable_t *table, void *key, void *payload)
DR_API void instrlist_meta_preinsert(instrlist_t *ilist, instr_t *where, instr_t *instr)
#define OPND_CREATE_INT_32OR8(val)
Definition: dr_ir_macros.h:143
DR_API INSTR_INLINE opnd_t opnd_create_reg(reg_id_t r)
DR_APP_API bool dr_app_running_under_dynamorio(void)
DR_API bool instr_is_return(instr_t *instr)
struct _instrlist_t instrlist_t
Definition: dr_defines.h:902
DR_API ssize_t dr_fprintf(file_t f, const char *fmt,...)
#define TIDFMT
Definition: dr_defines.h:642
#define OPND_CREATE_MEM64(base_reg, disp)
Definition: dr_ir_macros.h:79
DR_API void instrlist_meta_postinsert(instrlist_t *ilist, instr_t *where, instr_t *instr)
DR_API void dr_insert_call_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee)
DR_API void dr_insert_read_tls_field(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg)
DR_API void dr_insert_mbr_instrumentation(void *drcontext, instrlist_t *ilist, instr_t *instr, void *callee, dr_spill_slot_t scratch_slot)
DR_API INSTR_INLINE instr_t * instr_from_noalloc(instr_noalloc_t *noalloc)
DR_API void dr_mutex_unlock(void *mutex)
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_API bool dr_replace_fragment(void *drcontext, void *tag, instrlist_t *ilist)
DR_API void instr_set_opcode(instr_t *instr, int opcode)
DR_API bool instr_writes_memory(instr_t *instr)
@ OPSZ_8
Definition: dr_ir_opnd.h:87
DR_API void dr_messagebox(const char *fmt,...)
Definition: dr_defines.h:332
#define PFX
Definition: dr_defines.h:632
DR_API bool dr_get_mcontext(void *drcontext, dr_mcontext_t *context)
DR_API void dr_register_exit_event(void(*func)(void))
#define INSTR_CREATE_add(dc, Rd, Rn, Rm_or_imm)
Definition: dr_ir_macros_arm.h:1201
DR_API bool instr_is_call_direct(instr_t *instr)
DR_API bool dr_flush_region_ex(app_pc start, size_t size, void(*flush_completion_callback)(void *user_data), void *user_data)
DR_API byte * instrlist_encode(void *drcontext, instrlist_t *ilist, byte *pc, bool has_instr_jmp_targets)
#define INSTR_CREATE_mov_st(dc, d, s)
Definition: dr_ir_macros_x86.h:1219
DR_API size_t proc_save_fpstate(byte *buf)
DR_API void dr_printf(const char *fmt,...)
DR_API byte * instr_encode(void *drcontext, instr_t *instr, byte *pc)
DR_API void dr_insert_clean_call(void *drcontext, instrlist_t *ilist, instr_t *where, void *callee, bool save_fpstate, uint num_args,...)
DR_API void dr_mutex_destroy(void *mutex)
DR_API void instr_free(void *drcontext, instr_t *instr)
Definition: dr_events.h:140
DR_API void instrlist_meta_append(instrlist_t *ilist, instr_t *instr)
DR_API reg_t dr_read_saved_reg(void *drcontext, dr_spill_slot_t slot)
DR_API bool instr_opcode_valid(instr_t *instr)
DR_API void dr_restore_reg(void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg, dr_spill_slot_t slot)
Definition: dr_defines.h:378
DR_API instr_t * instrlist_first_app(instrlist_t *ilist)
Definition: dr_ir_instr.h:389
@ OPSZ_4
Definition: dr_ir_opnd.h:85
DR_API bool instr_is_mbr(instr_t *instr)
DR_APP_API void dr_app_stop_and_cleanup(void)
DR_API instr_t * instr_create(void *drcontext)
DR_API void dr_set_tls_field(void *drcontext, void *value)
DR_API void dr_insert_restore_fpstate(void *drcontext, instrlist_t *ilist, instr_t *where, opnd_t buf)
uint client_id_t
Definition: dr_defines.h:357
DR_API void * dr_global_alloc(size_t size)
Definition: dr_ir_macros.h:110