DynamoRIO API
dr_ir_instr.h File Reference

Functions to create and manipulate instructions. More...

Data Structures

struct  _dr_instr_label_data_t
 

Macros

#define EFLAGS_READ_CF   0x00000001
 
#define EFLAGS_READ_PF   0x00000002
 
#define EFLAGS_READ_AF   0x00000004
 
#define EFLAGS_READ_ZF   0x00000008
 
#define EFLAGS_READ_SF   0x00000010
 
#define EFLAGS_READ_TF   0x00000020
 
#define EFLAGS_READ_IF   0x00000040
 
#define EFLAGS_READ_DF   0x00000080
 
#define EFLAGS_READ_OF   0x00000100
 
#define EFLAGS_READ_NT   0x00000200
 
#define EFLAGS_READ_RF   0x00000400
 
#define EFLAGS_WRITE_CF   0x00000800
 
#define EFLAGS_WRITE_PF   0x00001000
 
#define EFLAGS_WRITE_AF   0x00002000
 
#define EFLAGS_WRITE_ZF   0x00004000
 
#define EFLAGS_WRITE_SF   0x00008000
 
#define EFLAGS_WRITE_TF   0x00010000
 
#define EFLAGS_WRITE_IF   0x00020000
 
#define EFLAGS_WRITE_DF   0x00040000
 
#define EFLAGS_WRITE_OF   0x00080000
 
#define EFLAGS_WRITE_NT   0x00100000
 
#define EFLAGS_WRITE_RF   0x00200000
 
#define EFLAGS_READ_ALL   0x000007ff
 
#define EFLAGS_READ_NON_PRED   EFLAGS_READ_ALL
 
#define EFLAGS_WRITE_ALL   0x003ff800
 
#define EFLAGS_READ_6   0x0000011f
 
#define EFLAGS_WRITE_6   0x0008f800
 
#define EFLAGS_READ_ARITH   EFLAGS_READ_6
 
#define EFLAGS_WRITE_ARITH   EFLAGS_WRITE_6
 
#define EFLAGS_WRITE_TO_READ(x)   ((x) >> 11)
 
#define EFLAGS_READ_TO_WRITE(x)   ((x) << 11)
 
#define PREFIX_LOCK   0x01
 
#define PREFIX_JCC_NOT_TAKEN   0x02
 
#define PREFIX_JCC_TAKEN   0x04
 
#define PREFIX_XACQUIRE   0x08
 
#define PREFIX_XRELEASE   0x10
 

Typedefs

typedef enum _dr_pred_type_t dr_pred_type_t
 
typedef struct _dr_instr_label_data_t dr_instr_label_data_t
 
typedef enum _dr_opnd_query_flags_t dr_opnd_query_flags_t
 
typedef enum _dr_pred_trigger_t dr_pred_trigger_t
 

Enumerations

enum  _dr_pred_type_t {
  DR_PRED_NONE,
  DR_PRED_O,
  DR_PRED_NO,
  DR_PRED_B,
  DR_PRED_NB,
  DR_PRED_Z,
  DR_PRED_NZ,
  DR_PRED_BE,
  DR_PRED_NBE,
  DR_PRED_S,
  DR_PRED_NS,
  DR_PRED_P,
  DR_PRED_NP,
  DR_PRED_L,
  DR_PRED_NL,
  DR_PRED_LE,
  DR_PRED_NLE,
  DR_PRED_COMPLEX
}
 
enum  _dr_opnd_query_flags_t {
  DR_QUERY_INCLUDE_COND_DSTS = 0x01,
  DR_QUERY_INCLUDE_COND_SRCS = 0x02,
  DR_QUERY_DEFAULT = DR_QUERY_INCLUDE_COND_SRCS,
  DR_QUERY_INCLUDE_ALL = (DR_QUERY_INCLUDE_COND_DSTS|DR_QUERY_INCLUDE_COND_SRCS)
}
 
enum  _dr_pred_trigger_t {
  DR_PRED_TRIGGER_NOPRED,
  DR_PRED_TRIGGER_MATCH,
  DR_PRED_TRIGGER_MISMATCH,
  DR_PRED_TRIGGER_UNKNOWN,
  DR_PRED_TRIGGER_INVALID
}
 
enum  dr_fp_type_t {
  DR_FP_STATE,
  DR_FP_MOVE,
  DR_FP_CONVERT,
  DR_FP_MATH
}
 
enum  {
  EFLAGS_CF = 0x00000001,
  EFLAGS_PF = 0x00000004,
  EFLAGS_AF = 0x00000010,
  EFLAGS_ZF = 0x00000040,
  EFLAGS_SF = 0x00000080,
  EFLAGS_DF = 0x00000400,
  EFLAGS_OF = 0x00000800,
  EFLAGS_ARITH = EFLAGS_CF|EFLAGS_PF|EFLAGS_AF|EFLAGS_ZF|EFLAGS_SF|EFLAGS_OF
}
 

Functions

bool instr_is_encoding_possible (instr_t *instr)
 
byte * instr_encode (void *drcontext, instr_t *instr, byte *pc)
 
byte * instr_encode_to_copy (void *drcontext, instr_t *instr, byte *copy_pc, byte *final_pc)
 
instr_tinstr_create (void *drcontext)
 
void instr_init (void *drcontext, instr_t *instr)
 
void instr_free (void *drcontext, instr_t *instr)
 
void instr_reset (void *drcontext, instr_t *instr)
 
void instr_reuse (void *drcontext, instr_t *instr)
 
void instr_destroy (void *drcontext, instr_t *instr)
 
INSTR_INLINE instr_tinstr_get_next (instr_t *instr)
 
INSTR_INLINE instr_tinstr_get_next_app (instr_t *instr)
 
INSTR_INLINE instr_tinstr_get_prev (instr_t *instr)
 
INSTR_INLINE instr_tinstr_get_prev_app (instr_t *instr)
 
INSTR_INLINE void instr_set_next (instr_t *instr, instr_t *next)
 
INSTR_INLINE void instr_set_prev (instr_t *instr, instr_t *prev)
 
INSTR_INLINE void * instr_get_note (instr_t *instr)
 
INSTR_INLINE void instr_set_note (instr_t *instr, void *value)
 
app_pc instr_get_branch_target_pc (instr_t *cti_instr)
 
void instr_set_branch_target_pc (instr_t *cti_instr, app_pc pc)
 
bool instr_is_exit_cti (instr_t *instr)
 
bool instr_is_interrupt (instr_t *instr)
 
INSTR_INLINE bool instr_is_app (instr_t *instr)
 
void instr_set_app (instr_t *instr)
 
INSTR_INLINE bool instr_is_meta (instr_t *instr)
 
void instr_set_meta (instr_t *instr)
 
INSTR_INLINE bool instr_ok_to_mangle (instr_t *instr)
 
void instr_set_ok_to_mangle (instr_t *instr, bool val)
 
void instr_set_meta_no_translation (instr_t *instr)
 
bool instr_ok_to_emit (instr_t *instr)
 
void instr_set_ok_to_emit (instr_t *instr, bool val)
 
int instr_length (void *drcontext, instr_t *instr)
 
int instr_mem_usage (instr_t *instr)
 
instr_tinstr_clone (void *drcontext, instr_t *orig)
 
instr_tinstr_build (void *drcontext, int opcode, int num_dsts, int num_srcs)
 
instr_tinstr_build_bits (void *drcontext, int opcode, uint num_bytes)
 
bool instr_valid (instr_t *instr)
 
app_pc instr_get_app_pc (instr_t *instr)
 
int instr_get_opcode (instr_t *instr)
 
void instr_set_opcode (instr_t *instr, int opcode)
 
INSTR_INLINE int instr_num_srcs (instr_t *instr)
 
INSTR_INLINE int instr_num_dsts (instr_t *instr)
 
void instr_set_num_opnds (void *drcontext, instr_t *instr, int num_dsts, int num_srcs)
 
opnd_t instr_get_src (instr_t *instr, uint pos)
 
opnd_t instr_get_dst (instr_t *instr, uint pos)
 
void instr_set_src (instr_t *instr, uint pos, opnd_t opnd)
 
void instr_set_dst (instr_t *instr, uint pos, opnd_t opnd)
 
void instr_remove_srcs (void *drcontext, instr_t *instr, uint start, uint end)
 
void instr_remove_dsts (void *drcontext, instr_t *instr, uint start, uint end)
 
opnd_t instr_get_target (instr_t *cti_instr)
 
void instr_set_target (instr_t *cti_instr, opnd_t target)
 
bool instr_operands_valid (instr_t *instr)
 
void instr_set_operands_valid (instr_t *instr, bool valid)
 
bool instr_opcode_valid (instr_t *instr)
 
uint instr_get_eflags (instr_t *instr, dr_opnd_query_flags_t flags)
 
uint instr_get_opcode_eflags (int opcode)
 
uint instr_get_arith_flags (instr_t *instr, dr_opnd_query_flags_t flags)
 
void instr_set_raw_bits (instr_t *instr, byte *addr, uint length)
 
void instr_set_raw_bits_valid (instr_t *instr, bool valid)
 
bool instr_raw_bits_valid (instr_t *instr)
 
bool instr_has_allocated_bits (instr_t *instr)
 
bool instr_needs_encoding (instr_t *instr)
 
bool instr_is_meta_may_fault (instr_t *instr)
 
void instr_set_meta_may_fault (instr_t *instr, bool val)
 
void instr_allocate_raw_bits (void *drcontext, instr_t *instr, uint num_bytes)
 
instr_tinstr_set_translation (instr_t *instr, app_pc addr)
 
void instr_make_persistent (void *drcontext, instr_t *instr)
 
byte * instr_get_raw_bits (instr_t *instr)
 
void instr_free_raw_bits (void *drcontext, instr_t *instr)
 
byte instr_get_raw_byte (instr_t *instr, uint pos)
 
void instr_set_raw_byte (instr_t *instr, uint pos, byte byte)
 
void instr_set_raw_bytes (instr_t *instr, byte *start, uint num_bytes)
 
void instr_set_raw_word (instr_t *instr, uint pos, uint word)
 
uint instr_get_raw_word (instr_t *instr, uint pos)
 
instr_tinstr_set_prefix_flag (instr_t *instr, uint prefix)
 
bool instr_get_prefix_flag (instr_t *instr, uint prefix)
 
bool instr_is_predicated (instr_t *instr)
 
dr_pred_type_t instr_get_predicate (instr_t *instr)
 
const char * instr_predicate_name (dr_pred_type_t pred)
 
dr_pred_type_t instr_invert_predicate (dr_pred_type_t pred)
 
uint instr_it_block_get_count (instr_t *it_instr)
 
dr_pred_type_t instr_it_block_get_pred (instr_t *it_instr, uint index)
 
bool instr_it_block_compute_immediates (dr_pred_type_t pred0, dr_pred_type_t pred1, dr_pred_type_t pred2, dr_pred_type_t pred3, byte *firstcond_out, byte *mask_out)
 
instr_tinstr_it_block_create (void *drcontext, dr_pred_type_t pred0, dr_pred_type_t pred1, dr_pred_type_t pred2, dr_pred_type_t pred3)
 
bool instr_is_exclusive_store (instr_t *instr)
 
instr_tinstr_set_predicate (instr_t *instr, dr_pred_type_t pred)
 
dr_pred_trigger_t instr_predicate_triggered (instr_t *instr, dr_mcontext_t *mc)
 
void instr_set_x86_mode (instr_t *instr, bool x86)
 
bool instr_get_x86_mode (instr_t *instr)
 
bool instr_set_isa_mode (instr_t *instr, dr_isa_mode_t mode)
 
dr_isa_mode_t instr_get_isa_mode (instr_t *instr)
 
void instr_shrink_to_16_bits (instr_t *instr)
 
void instr_shrink_to_32_bits (instr_t *instr)
 
bool instr_uses_reg (instr_t *instr, reg_id_t reg)
 
bool instr_uses_fp_reg (instr_t *instr)
 
bool instr_reg_in_src (instr_t *instr, reg_id_t reg)
 
bool instr_reg_in_dst (instr_t *instr, reg_id_t reg)
 
bool instr_writes_to_reg (instr_t *instr, reg_id_t reg, dr_opnd_query_flags_t flags)
 
bool instr_reads_from_reg (instr_t *instr, reg_id_t reg, dr_opnd_query_flags_t flags)
 
bool instr_writes_to_exact_reg (instr_t *instr, reg_id_t reg, dr_opnd_query_flags_t flags)
 
bool instr_replace_src_opnd (instr_t *instr, opnd_t old_opnd, opnd_t new_opnd)
 
bool instr_same (instr_t *instr1, instr_t *instr2)
 
bool instr_reads_memory (instr_t *instr)
 
bool instr_writes_memory (instr_t *instr)
 
bool instr_zeroes_ymmh (instr_t *instr)
 
bool instr_has_rel_addr_reference (instr_t *instr)
 
bool instr_get_rel_addr_target (instr_t *instr, app_pc *target)
 
int instr_get_rel_addr_dst_idx (instr_t *instr)
 
int instr_get_rel_addr_src_idx (instr_t *instr)
 
app_pc instr_compute_address (instr_t *instr, dr_mcontext_t *mc)
 
bool instr_compute_address_ex (instr_t *instr, dr_mcontext_t *mc, uint index, OUT app_pc *addr, OUT bool *write)
 
bool instr_compute_address_ex_pos (instr_t *instr, dr_mcontext_t *mc, uint index, OUT app_pc *addr, OUT bool *is_write, OUT uint *pos)
 
uint instr_memory_reference_size (instr_t *instr)
 
dr_instr_label_data_tinstr_get_label_data_area (instr_t *instr)
 
bool instr_is_mov (instr_t *instr)
 
bool instr_is_call (instr_t *instr)
 
bool instr_is_call_direct (instr_t *instr)
 
bool instr_is_near_call_direct (instr_t *instr)
 
bool instr_is_call_indirect (instr_t *instr)
 
bool instr_is_return (instr_t *instr)
 
bool instr_is_cti (instr_t *instr)
 
bool instr_is_cti_short (instr_t *instr)
 
bool instr_is_cti_loop (instr_t *instr)
 
bool instr_is_cti_short_rewrite (instr_t *instr, byte *pc)
 
bool instr_is_cbr (instr_t *instr)
 
bool instr_is_mbr (instr_t *instr)
 
bool instr_is_ubr (instr_t *instr)
 
bool instr_is_near_ubr (instr_t *instr)
 
bool instr_is_far_cti (instr_t *instr)
 
bool instr_is_far_abs_cti (instr_t *instr)
 
bool instr_is_syscall (instr_t *instr)
 
bool instr_is_wow64_syscall (instr_t *instr)
 
bool instr_is_prefetch (instr_t *instr)
 
bool instr_is_mov_constant (instr_t *instr, ptr_int_t *value)
 
bool instr_is_floating (instr_t *instr)
 
bool instr_is_floating_ex (instr_t *instr, dr_fp_type_t *type)
 
bool instr_is_mmx (instr_t *instr)
 
bool instr_is_sse (instr_t *instr)
 
bool instr_is_sse2 (instr_t *instr)
 
bool instr_is_sse_or_sse2 (instr_t *instr)
 
bool instr_is_3DNow (instr_t *instr)
 
bool instr_is_sse3 (instr_t *instr)
 
bool instr_is_ssse3 (instr_t *instr)
 
bool instr_is_sse41 (instr_t *instr)
 
bool instr_is_sse42 (instr_t *instr)
 
bool instr_is_sse4A (instr_t *instr)
 
bool instr_is_mov_imm_to_tos (instr_t *instr)
 
bool instr_is_label (instr_t *instr)
 
bool instr_is_undefined (instr_t *instr)
 
int instr_get_interrupt_number (instr_t *instr)
 
void instr_invert_cbr (instr_t *instr)
 
instr_tinstr_convert_short_meta_jmp_to_long (void *drcontext, instrlist_t *ilist, instr_t *instr)
 
bool instr_jcc_taken (instr_t *instr, reg_t eflags)
 
int instr_cmovcc_to_jcc (int cmovcc_opcode)
 
bool instr_cmovcc_triggered (instr_t *instr, reg_t eflags)
 
bool instr_is_nop (instr_t *instr)
 
instr_tinstr_create_0dst_0src (void *drcontext, int opcode)
 
instr_tinstr_create_0dst_1src (void *drcontext, int opcode, opnd_t src)
 
instr_tinstr_create_0dst_2src (void *drcontext, int opcode, opnd_t src1, opnd_t src2)
 
instr_tinstr_create_0dst_3src (void *drcontext, int opcode, opnd_t src1, opnd_t src2, opnd_t src3)
 
instr_tinstr_create_0dst_4src (void *drcontext, int opcode, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4)
 
instr_tinstr_create_1dst_0src (void *drcontext, int opcode, opnd_t dst)
 
instr_tinstr_create_1dst_1src (void *drcontext, int opcode, opnd_t dst, opnd_t src)
 
instr_tinstr_create_1dst_2src (void *drcontext, int opcode, opnd_t dst, opnd_t src1, opnd_t src2)
 
instr_tinstr_create_1dst_3src (void *drcontext, int opcode, opnd_t dst, opnd_t src1, opnd_t src2, opnd_t src3)
 
instr_tinstr_create_1dst_4src (void *drcontext, int opcode, opnd_t dst, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4)
 
instr_tinstr_create_1dst_5src (void *drcontext, int opcode, opnd_t dst, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4, opnd_t src5)
 
instr_tinstr_create_2dst_0src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2)
 
instr_tinstr_create_2dst_1src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t src)
 
instr_tinstr_create_2dst_2src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t src1, opnd_t src2)
 
instr_tinstr_create_2dst_3src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t src1, opnd_t src2, opnd_t src3)
 
instr_tinstr_create_2dst_4src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4)
 
instr_tinstr_create_2dst_5src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4, opnd_t src5)
 
instr_tinstr_create_3dst_0src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3)
 
instr_tinstr_create_3dst_2src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t src1, opnd_t src2)
 
instr_tinstr_create_3dst_3src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t src1, opnd_t src2, opnd_t src3)
 
instr_tinstr_create_3dst_4src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4)
 
instr_tinstr_create_3dst_5src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4, opnd_t src5)
 
instr_tinstr_create_4dst_1src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t dst4, opnd_t src)
 
instr_tinstr_create_4dst_2src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t dst4, opnd_t src1, opnd_t src2)
 
instr_tinstr_create_4dst_4src (void *drcontext, int opcode, opnd_t dst1, opnd_t dst2, opnd_t dst3, opnd_t dst4, opnd_t src1, opnd_t src2, opnd_t src3, opnd_t src4)
 
instr_tinstr_create_Ndst_Msrc_varsrc (void *drcontext, int opcode, uint fixed_dsts, uint fixed_srcs, uint var_srcs, uint var_ord,...)
 
instr_tinstr_create_Ndst_Msrc_vardst (void *drcontext, int opcode, uint fixed_dsts, uint fixed_srcs, uint var_dsts, uint var_ord,...)
 
instr_tinstr_create_popa (void *drcontext)
 
instr_tinstr_create_pusha (void *drcontext)
 
bool instr_is_reg_spill_or_restore (void *drcontext, instr_t *instr, bool *tls OUT, bool *spill OUT, reg_id_t *reg OUT, uint *offs OUT)
 
void instr_disassemble (void *drcontext, instr_t *instr, file_t outfile)
 
size_t instr_disassemble_to_buffer (void *drcontext, instr_t *instr, char *buf, size_t bufsz)
 

Detailed Description

Functions to create and manipulate instructions.

Macro Definition Documentation

#define EFLAGS_READ_6   0x0000011f

Reads all 6 arithmetic flags (CF, PF, AF, ZF, SF, OF).

#define EFLAGS_READ_AF   0x00000004

Reads AF (Auxiliary Carry Flag).

#define EFLAGS_READ_ALL   0x000007ff

Reads all flags.

#define EFLAGS_READ_ARITH   EFLAGS_READ_6

Platform-independent macro for reads all arithmetic flags.

#define EFLAGS_READ_CF   0x00000001

Reads CF (Carry Flag).

#define EFLAGS_READ_DF   0x00000080

Reads DF (Direction Flag).

#define EFLAGS_READ_IF   0x00000040

Reads IF (Interrupt Enable Flag).

#define EFLAGS_READ_NON_PRED   EFLAGS_READ_ALL

Flags not read by predicates.

#define EFLAGS_READ_NT   0x00000200

Reads NT (Nested Task).

#define EFLAGS_READ_OF   0x00000100

Reads OF (Overflow Flag).

#define EFLAGS_READ_PF   0x00000002

Reads PF (Parity Flag).

#define EFLAGS_READ_RF   0x00000400

Reads RF (Resume Flag).

#define EFLAGS_READ_SF   0x00000010

Reads SF (Sign Flag).

#define EFLAGS_READ_TF   0x00000020

Reads TF (Trap Flag).

#define EFLAGS_READ_TO_WRITE (   x)    ((x) << 11)

Converts an EFLAGS_READ_* value to the corresponding EFLAGS_WRITE_* value.

#define EFLAGS_READ_ZF   0x00000008

Reads ZF (Zero Flag).

#define EFLAGS_WRITE_6   0x0008f800

Writes all 6 arithmetic flags (CF, PF, AF, ZF, SF, OF).

#define EFLAGS_WRITE_AF   0x00002000

Writes AF (Auxiliary Carry Flag).

#define EFLAGS_WRITE_ALL   0x003ff800

Writes all flags.

#define EFLAGS_WRITE_ARITH   EFLAGS_WRITE_6

Platform-independent macor for writes all arithmetic flags.

#define EFLAGS_WRITE_CF   0x00000800

Writes CF (Carry Flag).

#define EFLAGS_WRITE_DF   0x00040000

Writes DF (Direction Flag).

#define EFLAGS_WRITE_IF   0x00020000

Writes IF (Interrupt Enable Flag).

#define EFLAGS_WRITE_NT   0x00100000

Writes NT (Nested Task).

#define EFLAGS_WRITE_OF   0x00080000

Writes OF (Overflow Flag).

#define EFLAGS_WRITE_PF   0x00001000

Writes PF (Parity Flag).

#define EFLAGS_WRITE_RF   0x00200000

Writes RF (Resume Flag).

#define EFLAGS_WRITE_SF   0x00008000

Writes SF (Sign Flag).

#define EFLAGS_WRITE_TF   0x00010000

Writes TF (Trap Flag).

#define EFLAGS_WRITE_TO_READ (   x)    ((x) >> 11)

Converts an EFLAGS_WRITE_* value to the corresponding EFLAGS_READ_* value.

#define EFLAGS_WRITE_ZF   0x00004000

Writes ZF (Zero Flag).

#define PREFIX_JCC_NOT_TAKEN   0x02

Branch hint: conditional branch is taken.

#define PREFIX_JCC_TAKEN   0x04

Branch hint: conditional branch is not taken.

#define PREFIX_LOCK   0x01

Makes the instruction's memory accesses atomic.

#define PREFIX_XACQUIRE   0x08

Transaction hint: start lock elision.

#define PREFIX_XRELEASE   0x10

Transaction hint: end lock elision.

Typedef Documentation

Data slots available in a label (instr_create_label()) instruction for storing client-controlled data. Accessible via instr_get_label_data_area().

Bitmask values passed as flags to routines that ask about whether operands and condition codes are read or written. These flags determine how to treat conditionally executed instructions. As a special case, the addressing registers inside a destination memory operand are covered by DR_QUERY_INCLUDE_COND_SRCS rather than DR_QUERY_INCLUDE_COND_DSTS.

This type holds the return values for instr_predicate_triggered().

Triggers used for conditionally executed instructions.

Enumeration Type Documentation

anonymous enum

The actual bits in the eflags register that we care about:

  11 10  9  8  7  6  5  4  3  2  1  0
  OF DF IF TF SF ZF  0 AF  0 PF  1 CF  
Enumerator
EFLAGS_CF 

The bit in the eflags register of CF (Carry Flag).

EFLAGS_PF 

The bit in the eflags register of PF (Parity Flag).

EFLAGS_AF 

The bit in the eflags register of AF (Aux Carry Flag).

EFLAGS_ZF 

The bit in the eflags register of ZF (Zero Flag).

EFLAGS_SF 

The bit in the eflags register of SF (Sign Flag).

EFLAGS_DF 

The bit in the eflags register of DF (Direction Flag).

EFLAGS_OF 

The bit in the eflags register of OF (Overflow Flag).

EFLAGS_ARITH 

The bits in the eflags register of CF, PF, AF, ZF, SF, OF.

Bitmask values passed as flags to routines that ask about whether operands and condition codes are read or written. These flags determine how to treat conditionally executed instructions. As a special case, the addressing registers inside a destination memory operand are covered by DR_QUERY_INCLUDE_COND_SRCS rather than DR_QUERY_INCLUDE_COND_DSTS.

Enumerator
DR_QUERY_INCLUDE_COND_DSTS 

By default, routines that take in these flags will only consider destinations that are always written. Thus, all destinations are skipped for an instruction that is predicated and executes conditionally (see instr_is_predicated()). If this flag is set, a conditionally executed instruction's destinations are included just like any other instruction's. As a special case, the addressing registers inside a destination memory operand are covered by DR_QUERY_INCLUDE_COND_SRCS rather than this flag.

DR_QUERY_INCLUDE_COND_SRCS 

By default, routines that take in these flags will only consider sources that are always read. Thus, all sources are skipped for an instruction that is predicated and executes conditionally (see instr_is_predicated()), except for predication conditions that involve the source operand values. If this flag is set, a conditionally executed instruction's sources are included just like any other instruction's. As a special case, the addressing registers inside a destination memory operand are covered by this flag rather than DR_QUERY_INCLUDE_COND_DSTS.

DR_QUERY_DEFAULT 

The default value that typical liveness analysis would want to use.

DR_QUERY_INCLUDE_ALL 

Includes all operands whether conditional or not.

This type holds the return values for instr_predicate_triggered().

Enumerator
DR_PRED_TRIGGER_NOPRED 

This instruction is not predicated.

DR_PRED_TRIGGER_MATCH 

The predicate matches and the instruction will execute.

DR_PRED_TRIGGER_MISMATCH 

The predicate does not match and the instruction will not execute.

DR_PRED_TRIGGER_UNKNOWN 

It is unknown whether the predicate matches.

DR_PRED_TRIGGER_INVALID 

An invalid parameter was passed.

Triggers used for conditionally executed instructions.

Enumerator
DR_PRED_NONE 

No predicate is present.

DR_PRED_O 

x86 condition: overflow (OF=1).

DR_PRED_NO 

x86 condition: no overflow (OF=0).

DR_PRED_B 

x86 condition: below (CF=1).

DR_PRED_NB 

x86 condition: not below (CF=0).

DR_PRED_Z 

x86 condition: zero (ZF=1).

DR_PRED_NZ 

x86 condition: not zero (ZF=0).

DR_PRED_BE 

x86 condition: below or equal (CF=1 or ZF=1).

DR_PRED_NBE 

x86 condition: not below or equal (CF=0 and ZF=0).

DR_PRED_S 

x86 condition: sign (SF=1).

DR_PRED_NS 

x86 condition: not sign (SF=0).

DR_PRED_P 

x86 condition: parity (PF=1).

DR_PRED_NP 

x86 condition: not parity (PF=0).

DR_PRED_L 

x86 condition: less (SF != OF).

DR_PRED_NL 

x86 condition: not less (SF=OF).

DR_PRED_LE 

x86 condition: less or equal (ZF=1 or SF != OF).

DR_PRED_NLE 

x86 condition: not less or equal (ZF=0 and SF=OF).

DR_PRED_COMPLEX 

x86 condition: special opcode-specific condition that depends on the values of the source operands. Thus, unlike all of the other conditions, the source operands will be accessed even if the condition then fails and the destinations are not touched. Any written eflags are unconditionally written, unlike regular destination operands.

Indicates which type of floating-point operation and instruction performs.

Enumerator
DR_FP_STATE 

Loads, stores, or queries general floating point state.

DR_FP_MOVE 

Moves floating point values from one location to another.

DR_FP_CONVERT 

Converts to or from floating point values.

DR_FP_MATH 

Performs arithmetic or conditional operations.

Function Documentation

void instr_allocate_raw_bits ( void *  drcontext,
instr_t instr,
uint  num_bytes 
)

Allocates num_bytes of memory for instr's raw bits. If instr currently points to raw bits, the allocated memory is initialized with the bytes pointed to. instr is then set to point to the allocated memory.

instr_t* instr_build ( void *  drcontext,
int  opcode,
int  num_dsts,
int  num_srcs 
)

Convenience routine: calls

  • instr_create(dcontext)
  • instr_set_opcode(opcode)
  • instr_set_num_opnds(dcontext, instr, num_dsts, num_srcs)

and returns the resulting instr_t.

instr_t* instr_build_bits ( void *  drcontext,
int  opcode,
uint  num_bytes 
)

Convenience routine: calls

  • instr_create(dcontext)
  • instr_set_opcode(instr, opcode)
  • instr_allocate_raw_bits(dcontext, instr, num_bytes)

and returns the resulting instr_t.

instr_t* instr_clone ( void *  drcontext,
instr_t orig 
)

Returns a copy of orig with separately allocated memory for operands and raw bytes if they were present in orig. Only a shallow copy of the note field is made.

int instr_cmovcc_to_jcc ( int  cmovcc_opcode)

Converts a cmovcc opcode cmovcc_opcode to the OP_jcc opcode that tests the same bits in eflags.

bool instr_cmovcc_triggered ( instr_t instr,
reg_t  eflags 
)

Given eflags, returns whether or not the conditional move instruction instr would execute the move. The conditional move can be an OP_cmovcc or an OP_fcmovcc instruction.

app_pc instr_compute_address ( instr_t instr,
dr_mcontext_t mc 
)

Returns NULL if none of instr's operands is a memory reference. Otherwise, returns the effective address of the first memory operand when the operands are considered in this order: destinations and then sources. The address is computed using the passed-in registers. mc->flags must include DR_MC_CONTROL and DR_MC_INTEGER. For instructions that use vector addressing (VSIB, introduced in AVX2), mc->flags must additionally include DR_MC_MULTIMEDIA.

Like instr_reads_memory(), this routine does not consider multi-byte nops that use addressing operands, or the OP_lea instruction's source operand, to be memory references.

bool instr_compute_address_ex ( instr_t instr,
dr_mcontext_t mc,
uint  index,
OUT app_pc *  addr,
OUT bool *  write 
)

Performs address calculation in the same manner as instr_compute_address() but handles multiple memory operands. The index parameter should be initially set to 0 and then incremented with each successive call until this routine returns false, which indicates that there are no more memory operands. The address of each is computed in the same manner as instr_compute_address() and returned in addr; whether it is a write is returned in is_write. Either or both OUT variables can be NULL. mc->flags must include DR_MC_CONTROL and DR_MC_INTEGER. For instructions that use vector addressing (VSIB, introduced in AVX2), mc->flags must additionally include DR_MC_MULTIMEDIA.

Like instr_reads_memory(), this routine does not consider multi-byte nops that use addressing operands, or the OP_lea instruction's source operand, to be memory references.

bool instr_compute_address_ex_pos ( instr_t instr,
dr_mcontext_t mc,
uint  index,
OUT app_pc *  addr,
OUT bool *  is_write,
OUT uint *  pos 
)

Performs address calculation in the same manner as instr_compute_address_ex() with additional information of which opnd is used for address computation returned in pos. If pos is NULL, it is the same as instr_compute_address_ex().

Like instr_reads_memory(), this routine does not consider multi-byte nops that use addressing operands, or the OP_lea instruction's source operand, to be memory references.

instr_t* instr_convert_short_meta_jmp_to_long ( void *  drcontext,
instrlist_t *  ilist,
instr_t instr 
)

Assumes that instr is a meta instruction (instr_is_meta()) and an instr_is_cti_short() (<=8-bit reach). Converts instr's opcode to a long form (32-bit reach for x86). If instr's opcode is OP_loop* or OP_jecxz for x86 or OP_cbnz or OP_cbz for ARM, converts it to a sequence of multiple instructions (which is different from instr_is_cti_short_rewrite()). Each added instruction is marked instr_is_meta(). Returns the long form of the instruction, which is identical to instr unless instr is OP_{loop*,jecxz,cbnz,cbz}, in which case the return value is the final instruction in the sequence, the one that has long reach.

Note
DR automatically converts app short ctis to long form.
instr_t* instr_create ( void *  drcontext)

Returns an initialized instr_t allocated on the thread-local heap. Sets the x86/x64 mode of the returned instr_t to the mode of dcontext.

instr_t* instr_create_0dst_0src ( void *  drcontext,
int  opcode 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode and no sources or destinations.

instr_t* instr_create_0dst_1src ( void *  drcontext,
int  opcode,
opnd_t  src 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode and a single source (src).

instr_t* instr_create_0dst_2src ( void *  drcontext,
int  opcode,
opnd_t  src1,
opnd_t  src2 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode and two sources (src1, src2).

instr_t* instr_create_0dst_3src ( void *  drcontext,
int  opcode,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode and three sources (src1, src2, src3).

instr_t* instr_create_0dst_4src ( void *  drcontext,
int  opcode,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode and four sources (src1, src2, src3, src4).

instr_t* instr_create_1dst_0src ( void *  drcontext,
int  opcode,
opnd_t  dst 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode and one destination (dst).

instr_t* instr_create_1dst_1src ( void *  drcontext,
int  opcode,
opnd_t  dst,
opnd_t  src 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, one destination(dst), and one source (src).

instr_t* instr_create_1dst_2src ( void *  drcontext,
int  opcode,
opnd_t  dst,
opnd_t  src1,
opnd_t  src2 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, one destination (dst), and two sources (src1, src2).

instr_t* instr_create_1dst_3src ( void *  drcontext,
int  opcode,
opnd_t  dst,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, one destination (dst), and three sources (src1, src2, src3).

instr_t* instr_create_1dst_4src ( void *  drcontext,
int  opcode,
opnd_t  dst,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, one destination (dst), and four sources (src1, src2, src3, src4).

instr_t* instr_create_1dst_5src ( void *  drcontext,
int  opcode,
opnd_t  dst,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4,
opnd_t  src5 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, one destination (dst), and five sources (src1, src2, src3, src4, src5).

instr_t* instr_create_2dst_0src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, two destinations (dst1, dst2) and no sources.

instr_t* instr_create_2dst_1src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  src 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, two destinations (dst1, dst2) and one source (src).

instr_t* instr_create_2dst_2src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  src1,
opnd_t  src2 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, two destinations (dst1, dst2) and two sources (src1, src2).

instr_t* instr_create_2dst_3src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, two destinations (dst1, dst2) and three sources (src1, src2, src3).

instr_t* instr_create_2dst_4src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, two destinations (dst1, dst2) and four sources (src1, src2, src3, src4).

instr_t* instr_create_2dst_5src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4,
opnd_t  src5 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, two destinations (dst1, dst2) and five sources (src1, src2, src3, src4, src5).

instr_t* instr_create_3dst_0src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, three destinations (dst1, dst2, dst3) and no sources.

instr_t* instr_create_3dst_2src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  src1,
opnd_t  src2 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, three destinations (dst1, dst2, dst3) and two sources (src1, src2).

instr_t* instr_create_3dst_3src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, three destinations (dst1, dst2, dst3) and three sources (src1, src2, src3).

instr_t* instr_create_3dst_4src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, three destinations (dst1, dst2, dst3) and four sources (src1, src2, src3, src4).

instr_t* instr_create_3dst_5src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4,
opnd_t  src5 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, three destinations (dst1, dst2, dst3) and five sources (src1, src2, src3, src4, src5).

instr_t* instr_create_4dst_1src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  dst4,
opnd_t  src 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, four destinations (dst1, dst2, dst3, dst4) and 1 source (src).

instr_t* instr_create_4dst_2src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  dst4,
opnd_t  src1,
opnd_t  src2 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, four destinations (dst1, dst2, dst3, dst4) and 2 sources (src1 and src2).

instr_t* instr_create_4dst_4src ( void *  drcontext,
int  opcode,
opnd_t  dst1,
opnd_t  dst2,
opnd_t  dst3,
opnd_t  dst4,
opnd_t  src1,
opnd_t  src2,
opnd_t  src3,
opnd_t  src4 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, four destinations (dst1, dst2, dst3, dst4) and four sources (src1, src2, src3, src4).

instr_t* instr_create_Ndst_Msrc_vardst ( void *  drcontext,
int  opcode,
uint  fixed_dsts,
uint  fixed_srcs,
uint  var_dsts,
uint  var_ord,
  ... 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, fixed_dsts plus var_dsts destination operands, and fixed_srcs source operands. The variable arguments must start with the fixed destinations, followed by the (fixed) sources, followed by the variable destinations. The var_ord parameter specifies the (0-based) ordinal position within the resulting instruction's destination array at which the variable destinations should be placed, allowing them to be inserted in the middle of the fixed destinations.

instr_t* instr_create_Ndst_Msrc_varsrc ( void *  drcontext,
int  opcode,
uint  fixed_dsts,
uint  fixed_srcs,
uint  var_srcs,
uint  var_ord,
  ... 
)

Convenience routine that returns an initialized instr_t allocated on the thread-local heap with opcode opcode, fixed_dsts destination operands, and fixed_srcs plus var_srcs source operands. The variable arguments must start with the (fixed) destinations, followed by the fixed sources, followed by the variable sources. The var_ord parameter specifies the (0-based) ordinal position within the resulting instruction's source array at which the variable sources should be placed, allowing them to be inserted in the middle of the fixed sources.

instr_t* instr_create_popa ( void *  drcontext)

Convenience routine that returns an initialized instr_t for OP_popa.

instr_t* instr_create_pusha ( void *  drcontext)

Convenience routine that returns an initialized instr_t for OP_pusha.

void instr_destroy ( void *  drcontext,
instr_t instr 
)

Performs instr_free() and then deallocates the thread-local heap storage for instr.

void instr_disassemble ( void *  drcontext,
instr_t instr,
file_t  outfile 
)

Prints the instruction instr to file outfile. Does not print address-size or data-size prefixes for other than just-decoded instrs, and does not check that the instruction has a valid encoding. Prints each operand with leading zeros indicating the size. The default is to use DR's custom syntax (see disassemble_set_syntax()).

size_t instr_disassemble_to_buffer ( void *  drcontext,
instr_t instr,
char *  buf,
size_t  bufsz 
)

Prints the instruction instr to the buffer buf. Always null-terminates, and will not print more than bufsz characters, which includes the final null character. Returns the number of characters printed, not including the final null.

Does not print address-size or data-size prefixes for other than just-decoded instrs, and does not check that the instruction has a valid encoding. Prints each operand with leading zeros indicating the size. The default is to use DR's custom syntax (see disassemble_set_syntax()).

byte* instr_encode ( void *  drcontext,
instr_t instr,
byte *  pc 
)

Encodes instr into the memory at pc. Uses the x86/x64 mode stored in instr, not the mode of the current thread. Returns the pc after the encoded instr, or NULL if the encoding failed. If instr is a cti with an instr_t target, the note fields of instr and of the target must be set with the respective offsets of each instr_t! (instrlist_encode does this automatically, if the target is in the list). x86 instructions can occupy up to 17 bytes, so the caller should ensure the target location has enough room to avoid overflow.

Note
: In Thumb mode, some instructions have different behavior depending on whether they are in an IT block. To correctly encode such instructions, they should be encoded within an instruction list with the corresponding IT instruction using instrlist_encode().
byte* instr_encode_to_copy ( void *  drcontext,
instr_t instr,
byte *  copy_pc,
byte *  final_pc 
)

Encodes instr into the memory at copy_pc in preparation for copying to final_pc. Any pc-relative component is encoded as though the instruction were located at final_pc. This allows for direct copying of the encoded bytes to final_pc without re-relativization.

Uses the x86/x64 mode stored in instr, not the mode of the current thread. Returns the pc after the encoded instr, or NULL if the encoding failed. If instr is a cti with an instr_t target, the note fields of instr and of the target must be set with the respective offsets of each instr_t! (instrlist_encode does this automatically, if the target is in the list). x86 instructions can occupy up to 17 bytes, so the caller should ensure the target location has enough room to avoid overflow.

Note
: In Thumb mode, some instructions have different behavior depending on whether they are in an IT block. To correctly encode such instructions, they should be encoded within an instruction list with the corresponding IT instruction using instrlist_encode().
void instr_free ( void *  drcontext,
instr_t instr 
)

Deallocates all memory that was allocated by instr. This includes raw bytes allocated by instr_allocate_raw_bits() and operands allocated by instr_set_num_opnds(). Does not deallocate the storage for instr itself.

void instr_free_raw_bits ( void *  drcontext,
instr_t instr 
)

If instr has raw bits allocated, frees them.

app_pc instr_get_app_pc ( instr_t instr)

Get the original application PC of instr if it exists.

uint instr_get_arith_flags ( instr_t instr,
dr_opnd_query_flags_t  flags 
)

Returns instr's arithmetic flags (bottom 6 eflags) use as EFLAGS_ constants (e.g., EFLAGS_READ_CF, EFLAGS_WRITE_OF, etc.) or'ed together. If instr's eflags behavior has not been calculated yet or is invalid, the entire eflags use is calculated and returned (not just the arithmetic flags). Which eflags are considered to be accessed for conditionally executed instructions are controlled by flags.

app_pc instr_get_branch_target_pc ( instr_t cti_instr)

Return the taken target pc of the (direct branch) instruction.

opnd_t instr_get_dst ( instr_t instr,
uint  pos 
)

Returns instr's destination operand at position pos (0-based).

uint instr_get_eflags ( instr_t instr,
dr_opnd_query_flags_t  flags 
)

Returns instr's eflags use as EFLAGS_ constants (e.g., EFLAGS_READ_CF, EFLAGS_WRITE_OF, etc.) or'ed together. Which eflags are considered to be accessed for conditionally executed instructions are controlled by flags.

int instr_get_interrupt_number ( instr_t instr)

Assumes that instr's opcode is OP_int and that either instr's operands or its raw bits are valid. Returns the first source operand if instr's operands are valid, else if instr's raw bits are valid returns the first raw byte.

dr_isa_mode_t instr_get_isa_mode ( instr_t instr)

Each instruction stores the processor mode under which it should be interpreted. This routine returns the mode for instr.

dr_instr_label_data_t* instr_get_label_data_area ( instr_t instr)
Returns
a pointer to user-controlled data fields in a label instruction. These fields are available for use by clients for their own purposes. Returns NULL if instr is not a label instruction.
Note
These data fields are copied (shallowly) across instr_clone().
INSTR_INLINE instr_t* instr_get_next ( instr_t instr)

Returns the next instr_t in the instrlist_t that contains instr.

Note
The next pointer for an instr_t is inside the instr_t data structure itself, making it impossible to have on instr_t in two different InstrLists (but removing the need for an extra data structure for each element of the instrlist_t).
INSTR_INLINE instr_t* instr_get_next_app ( instr_t instr)

Returns the next application (non-meta) instruction in the instruction list that contains instr.

Note
As opposed to instr_get_next(), this routine skips all meta instructions inserted by either DynamoRIO or its clients.
We recommend using this routine during the phase of application code analysis, as any meta instructions present are guaranteed to be ok to skip. However, caution should be exercised if using this routine after any instrumentation insertion has already happened, as instrumentation might affect register usage or other factors being analyzed.
INSTR_INLINE void* instr_get_note ( instr_t instr)

Gets the value of the user-controlled note field in instr.

Note
Important: is also used when emitting for targets that are other instructions. Thus it will be overwritten when calling instrlist_encode() or instrlist_encode_to_copy() with has_instr_jmp_targets set to true.
The note field is copied (shallowly) by instr_clone().
int instr_get_opcode ( instr_t instr)

Returns instr's opcode (an OP_ constant).

uint instr_get_opcode_eflags ( int  opcode)

Returns the eflags usage of instructions with opcode opcode, as EFLAGS_ constants (e.g., EFLAGS_READ_CF, EFLAGS_WRITE_OF, etc.) or'ed together. If opcode is predicated (see instr_is_predicated()) or if the set of flags read or written varies with an operand value, this routine returns the maximal set that might be accessed or written.

dr_pred_type_t instr_get_predicate ( instr_t instr)

Returns the DR_PRED_ constant for instr that describes what its conditional execution is dependent on.

bool instr_get_prefix_flag ( instr_t instr,
uint  prefix 
)

Assumes that prefix is a PREFIX_ constant. Returns true if instr's prefixes contain the flag prefix.

INSTR_INLINE instr_t* instr_get_prev ( instr_t instr)

Returns the previous instr_t in the instrlist_t that contains instr.

INSTR_INLINE instr_t* instr_get_prev_app ( instr_t instr)

Returns the previous application (non-meta) instruction in the instruction list that contains instr.

Note
As opposed to instr_get_prev(), this routine skips all meta instructions inserted by either DynamoRIO or its clients.
We recommend using this routine during the phase of application code analysis, as any meta instructions present are guaranteed to be ok to skip. However, caution should be exercised if using this routine after any instrumentation insertion has already happened, as instrumentation might affect register usage or other factors being analyzed.
byte* instr_get_raw_bits ( instr_t instr)

Assumes that instr's raw bits are valid. Returns a pointer to instr's raw bits.

Note
A freshly-decoded instruction has valid raw bits that point to the address from which it was decoded. However, for instructions presented in the basic block or trace events, use instr_get_app_pc() to retrieve the corresponding application address, as the raw bits will not be set for instructions added after decoding, and may point to a different location for insructions that have been modified.
byte instr_get_raw_byte ( instr_t instr,
uint  pos 
)

Assumes that instr's raw bits are valid and have > pos bytes. Returns a pointer to instr's raw byte at position pos (beginning with 0).

uint instr_get_raw_word ( instr_t instr,
uint  pos 
)

Assumes that instr's raw bits are valid and have > pos + 3 bytes. Returns the 4 bytes beginning at position pos (0-based).

int instr_get_rel_addr_dst_idx ( instr_t instr)

If any of instr's destination operands is a rip-relative memory reference, returns the operand position. If there is no such destination operand, returns -1.

Note
For 64-bit DR builds only.
int instr_get_rel_addr_src_idx ( instr_t instr)

If any of instr's source operands is a rip-relative memory reference, returns the operand position. If there is no such source operand, returns -1.

Note
For 64-bit DR builds only.
bool instr_get_rel_addr_target ( instr_t instr,
app_pc *  target 
)

If any of instr's operands is a rip-relative memory reference, returns the address that reference targets. Else returns false.

Note
For 64-bit DR builds only.
opnd_t instr_get_src ( instr_t instr,
uint  pos 
)

Returns instr's source operand at position pos (0-based).

opnd_t instr_get_target ( instr_t cti_instr)

Assumes that cti_instr is a control transfer instruction Returns the first source operand of cti_instr (its target).

bool instr_get_x86_mode ( instr_t instr)

Returns true if instr is an x86 instruction (32-bit) and false if instr is an x64 instruction (64-bit).

Note
For 64-bit DR builds only.
Deprecated:
Replaced by instr_get_isa_mode().
bool instr_has_allocated_bits ( instr_t instr)

Returns true iff instr has its own allocated memory for raw bits.

bool instr_has_rel_addr_reference ( instr_t instr)

Returns true iff any of instr's operands is a rip-relative memory reference.

Note
For 64-bit DR builds only.
void instr_init ( void *  drcontext,
instr_t instr 
)

Initializes instr. Sets the x86/x64 mode of instr to the mode of dcontext.

void instr_invert_cbr ( instr_t instr)

Assumes that instr is a conditional branch instruction Reverses the logic of instr's conditional e.g., changes OP_jb to OP_jnb. Works on cti_short_rewrite as well.

dr_pred_type_t instr_invert_predicate ( dr_pred_type_t  pred)

Returns the DR_PRED_ constant that represents the opposite condition from pred. A valid conditional branch predicate must be passed (i.e., not DR_PRED_NONE, DR_PRED_AL, or DR_PRED_OP).

Note
ARM-only.
bool instr_is_3DNow ( instr_t instr)

Returns true iff instr is part of AMD's 3D-Now! instructions.

INSTR_INLINE bool instr_is_app ( instr_t instr)

Return true iff instr is an application (non-meta) instruction (see instr_set_app() for more information).

bool instr_is_call ( instr_t instr)

Returns true iff instr's opcode is OP_call, OP_call_far, OP_call_ind, or OP_call_far_ind on x86; OP_bl, OP_blx, or OP_blx_ind on ARM.

bool instr_is_call_direct ( instr_t instr)

Returns true iff instr's opcode is OP_call or OP_call_far.

bool instr_is_call_indirect ( instr_t instr)

Returns true iff instr's opcode is OP_call_ind or OP_call_far_ind on x86; OP_blx_ind on ARM.

bool instr_is_cbr ( instr_t instr)

Returns true iff instr is a conditional branch: OP_jcc, OP_jcc_short, OP_loop*, or OP_jecxz on x86; OP_cbnz, OP_cbz, or when a predicate is present any of OP_b, OP_b_short, OP_bx, OP_bxj, OP_bl, OP_blx, OP_blx_ind on ARM.

bool instr_is_cti ( instr_t instr)

Returns true iff instr is a control transfer instruction of any kind This includes OP_jcc, OP_jcc_short, OP_loop*, OP_jecxz, OP_call*, and OP_jmp*.

bool instr_is_cti_loop ( instr_t instr)

Returns true iff instr is one of OP_loop* or OP_jecxz.

bool instr_is_cti_short ( instr_t instr)

Returns true iff instr is a control transfer instruction that takes an 8-bit offset on x86 (OP_loop*, OP_jecxz, OP_jmp_short, or OP_jcc_short) or a small offset on ARM (OP_cbz, OP_cbnz, OP_b_short).

bool instr_is_cti_short_rewrite ( instr_t instr,
byte *  pc 
)

Returns true iff instr's opcode is OP_loop* or OP_jecxz on x86 or OP_cbz or OP_cbnz on ARM and instr has been transformed to a sequence of instruction that will allow a larger offset. If pc != NULL, pc is expected to point to the beginning of the encoding of instr, and the following instructions are assumed to be encoded in sequence after instr. Otherwise, the encoding is expected to be found in instr's allocated bits.

bool instr_is_encoding_possible ( instr_t instr)

Returns true iff instr can be encoding as a valid IA-32 instruction.

bool instr_is_exclusive_store ( instr_t instr)

Returns true iff instr is an exclusive store instruction, e.g., OP_strex on ARM.

bool instr_is_exit_cti ( instr_t instr)

Returns true iff instr is a conditional branch, unconditional branch, or indirect branch with a program address target (NOT an instr_t address target) and instr is ok to mangle.

bool instr_is_far_abs_cti ( instr_t instr)

Returns true if instr is an absolute call or jmp that is far.

bool instr_is_far_cti ( instr_t instr)

Returns true iff instr is a far control transfer instruction: OP_jmp_far, OP_call_far, OP_jmp_far_ind, OP_call_far_ind, OP_ret_far, or OP_iret.

bool instr_is_floating ( instr_t instr)

Returns true iff instr is a floating point instruction.

bool instr_is_floating_ex ( instr_t instr,
dr_fp_type_t type 
)

Returns true iff instr is a floating point instruction.

Parameters
[in]instrThe instruction to query
[out]typeIf the return value is true and type is non-NULL, the type of the floating point operation is written to type.
bool instr_is_interrupt ( instr_t instr)

Return true iff instr's opcode is OP_int, OP_into, or OP_int3.

bool instr_is_label ( instr_t instr)

Returns true iff instr is a label meta-instruction.

bool instr_is_mbr ( instr_t instr)

Returns true iff instr is a multi-way (indirect) branch: OP_jmp_ind, OP_call_ind, OP_ret, OP_jmp_far_ind, OP_call_far_ind, OP_ret_far, or OP_iret on x86; OP_bx, OP_bxj, OP_blx_ind, or any instruction with a destination register operand of DR_REG_PC on ARM.

INSTR_INLINE bool instr_is_meta ( instr_t instr)

Return true iff instr is a meta instruction (see instr_set_meta() for more information).

bool instr_is_meta_may_fault ( instr_t instr)

Return true iff instr is not a meta-instruction that can fault (see instr_set_meta_may_fault() for more information).

Deprecated:
Any meta instruction can fault if it has a non-NULL translation field and the client fully handles all of its faults, so this routine is no longer needed.
bool instr_is_mmx ( instr_t instr)

Returns true iff instr is part of Intel's MMX instructions.

bool instr_is_mov ( instr_t instr)

Returns true iff instr is an IA-32/AMD64 "mov" instruction: either OP_mov_st, OP_mov_ld, OP_mov_imm, OP_mov_seg, or OP_mov_priv.

bool instr_is_mov_constant ( instr_t instr,
ptr_int_t *  value 
)

Tries to identify common cases of moving a constant into either a register or a memory address. Returns true and sets *value to the constant being moved for the following cases: OP_mov_imm, OP_mov_st, and OP_xor where the source equals the destination, for x86; OP_mov, OP_movs, OP_movw, OP_mvn, OP_mvns, or OP_eor where the sources equal the destination and there is no shift, for ARM.

bool instr_is_mov_imm_to_tos ( instr_t instr)

Returns true iff instr is a "mov $imm -> (%esp)".

bool instr_is_near_call_direct ( instr_t instr)

Returns true iff instr's opcode is OP_call on x86; OP_bl or OP_blx on ARM.

bool instr_is_near_ubr ( instr_t instr)

Returns true iff instr is a near unconditional direct branch: OP_jmp, or OP_jmp_short on x86; OP_b with no predicate on ARM.

bool instr_is_nop ( instr_t instr)

Returns true if instr is one of a class of common nops. currently checks:

  • nop
  • nop reg/mem
  • xchg reg, reg
  • mov reg, reg
  • lea reg, (reg)
bool instr_is_predicated ( instr_t instr)

Returns whether instr is predicated: i.e., whether its operation is conditional.

bool instr_is_prefetch ( instr_t instr)

Returns true iff instr is a prefetch instruction.

bool instr_is_reg_spill_or_restore ( void *  drcontext,
instr_t instr,
bool *tls  OUT,
bool *spill  OUT,
reg_id_t *reg  OUT,
uint *offs  OUT 
)

Returns whether instr is a register spill or restore, whether it was created by dr_save_reg(), dr_restore_reg(), dr_insert_read_raw_tls(), dr_insert_write_raw_tls(), routines that call the aforementioned routines (e.g., dr_save_arith_flags()), or DR's own internal spills and restores. Returns information about the spill/restore in the OUT parameters. The returned offs is the raw offset in bytes from the TLS segment base, the stolen register base, or the thread-private context area.

bool instr_is_return ( instr_t instr)

Returns true iff instr's opcode is OP_ret, OP_ret_far, or OP_iret on x86. On ARM, returns true iff instr reads DR_REG_LR and writes DR_REG_PC.

bool instr_is_sse ( instr_t instr)

Returns true iff instr is part of Intel's SSE instructions.

bool instr_is_sse2 ( instr_t instr)

Returns true iff instr is part of Intel's SSE2 instructions.

bool instr_is_sse3 ( instr_t instr)

Returns true iff instr is part of Intel's SSE3 instructions.

bool instr_is_sse41 ( instr_t instr)

Returns true iff instr is part of Intel's SSE4.1 instructions.

bool instr_is_sse42 ( instr_t instr)

Returns true iff instr is part of Intel's SSE4.2 instructions.

bool instr_is_sse4A ( instr_t instr)

Returns true iff instr is part of AMD's SSE4A instructions.

bool instr_is_sse_or_sse2 ( instr_t instr)

Returns true iff instr is part of Intel's SSE or SSE2 instructions.

Deprecated:
Use instr_is_sse() combined with instr_is_sse2() instead.
bool instr_is_ssse3 ( instr_t instr)

Returns true iff instr is part of Intel's SSSE3 instructions.

bool instr_is_syscall ( instr_t instr)

Returns true iff instr is used to implement system calls: OP_int with a source operand of 0x80 on linux or 0x2e on windows, or OP_sysenter, or OP_syscall, or instr_is_wow64_syscall() for WOW64.

bool instr_is_ubr ( instr_t instr)

Returns true iff instr is an unconditional direct branch: OP_jmp, OP_jmp_short, or OP_jmp_far on x86; OP_b or OP_b_short with no predicate on ARM.

bool instr_is_undefined ( instr_t instr)

Returns true iff instr is an "undefined" instruction (ud2)

bool instr_is_wow64_syscall ( instr_t instr)

Returns true iff instr is the indirect transfer from the 32-bit ntdll.dll to the wow64 system call emulation layer. This instruction will also return true for instr_is_syscall, as well as appear as an indirect call, so clients modifying indirect calls may want to avoid modifying this type.

Note
Windows-only
bool instr_it_block_compute_immediates ( dr_pred_type_t  pred0,
dr_pred_type_t  pred1,
dr_pred_type_t  pred2,
dr_pred_type_t  pred3,
byte *  firstcond_out,
byte *  mask_out 
)

Computes immediates (firstcond and mask) for creating a new instruction with opcode OP_it with the given predicates. Up to four instructions can exist in a single IT block. Pass DR_PRED_NONE for all predicates beyond the desired instruction count in the newly created IT block. Returns whether the given predicates are valid for creating an IT block.

Note
ARM-only.
instr_t* instr_it_block_create ( void *  drcontext,
dr_pred_type_t  pred0,
dr_pred_type_t  pred1,
dr_pred_type_t  pred2,
dr_pred_type_t  pred3 
)

Creates a new instruction with opcode OP_it and immediates set to encode an IT block with the given predicates. Up to four instructions can exist in a single IT block. Pass DR_PRED_NONE for all predicates beyond the desired instruction count in the newly created IT block.

Note
ARM-only.
uint instr_it_block_get_count ( instr_t it_instr)

Assumes that it_instr's opcode is OP_it. Returns the number of instructions in the IT block that it_instr heads.

Note
ARM-only.
dr_pred_type_t instr_it_block_get_pred ( instr_t it_instr,
uint  index 
)

Assumes that it_instr's opcode is OP_it. Returns the predicate for the instruction with ordinal index in IT block that it_instr heads.

Note
ARM-only.
bool instr_jcc_taken ( instr_t instr,
reg_t  eflags 
)

Given eflags, returns whether or not the conditional branch, instr, would be taken.

int instr_length ( void *  drcontext,
instr_t instr 
)

Returns the length of instr. As a side effect, if instr_is_app(instr) and instr's raw bits are invalid, encodes instr into bytes allocated with instr_allocate_raw_bits(), after which instr is marked as having valid raw bits.

void instr_make_persistent ( void *  drcontext,
instr_t instr 
)

Calling this function with instr makes it safe to keep the instruction around indefinitely when its raw bits point into the cache. The function allocates memory local to instr to hold a copy of the raw bits. If this was not done, the original raw bits could be deleted at some point. Making an instruction persistent is necessary if you want to keep it beyond returning from the call that produced the instruction.

int instr_mem_usage ( instr_t instr)

Returns number of bytes of heap used by instr.

uint instr_memory_reference_size ( instr_t instr)

Calculates the size, in bytes, of the memory read or write of instr. If instr does not reference memory, or is invalid, returns 0. If instr is a repeated string instruction, considers only one iteration. If instr uses vector addressing (VSIB, introduced in AVX2), considers only the size of each separate memory access.

bool instr_needs_encoding ( instr_t instr)

Returns true iff instr's raw bits are not a valid encoding of instr.

INSTR_INLINE int instr_num_dsts ( instr_t instr)

Returns the number of destination operands of instr.

INSTR_INLINE int instr_num_srcs ( instr_t instr)

Returns the number of source operands of instr.

Note
Addressing registers used in destination memory references (i.e., base, index, or segment registers) are not separately listed as source operands.
bool instr_ok_to_emit ( instr_t instr)

Return true iff instr is to be emitted into the cache.

INSTR_INLINE bool instr_ok_to_mangle ( instr_t instr)

Return true iff instr is not a meta-instruction (see instr_set_app() for more information).

Deprecated:
instr_is_app()/instr_is_meta() should be used instead.
bool instr_opcode_valid ( instr_t instr)

Returns true iff instr's opcode is valid. If the opcode is ever set to other than OP_INVALID or OP_UNDECODED it is assumed to be valid. However, calling instr_get_opcode() will attempt to decode a valid opcode, hence the purpose of this routine.

bool instr_operands_valid ( instr_t instr)

Returns true iff instr's operands are up to date.

const char* instr_predicate_name ( dr_pred_type_t  pred)

Returns the string name corresponding to the given DR_PRED_ constant.

Note
ARM-only.
dr_pred_trigger_t instr_predicate_triggered ( instr_t instr,
dr_mcontext_t mc 
)

Given the machine context mc, returns whether or not the predicated instruction instr will execute. Currently condition-code predicates are supported and OP_bsf and OP_bsr from DR_PRED_COMPLEX; other instances of DR_PRED_COMPLEX are not supported. mc->flags must include DR_MC_CONTROL for condition-code predicates, and additionally DR_MC_INTEGER for OP_bsf and OP_bsr.

Note
More complex predicates will be added in the future and they may require additional state in mc.
bool instr_raw_bits_valid ( instr_t instr)

Returns true iff instr's raw bits are a valid encoding of instr.

bool instr_reads_from_reg ( instr_t instr,
reg_id_t  reg,
dr_opnd_query_flags_t  flags 
)

Assumes that reg is a DR_REG_ constant. Returns true iff at least one of instr's operands reads from a register that overlaps reg (checks both source operands and addressing registers used in destination operands).

Returns false for multi-byte nops with an operand using reg.

Which operands are considered to be accessed for conditionally executed instructions are controlled by flags. As a special case, the addressing registers inside a destination memory operand are covered by DR_QUERY_INCLUDE_COND_SRCS rather than DR_QUERY_INCLUDE_COND_DSTS.

bool instr_reads_memory ( instr_t instr)

Returns true iff any of instr's source operands is a memory reference.

Unlike opnd_is_memory_reference(), this routine conisders the semantics of the instruction and returns false for both multi-byte nops with a memory operand and for the OP_lea instruction, as they do not really reference the memory. It does return true for prefetch instructions.

If instr is predicated (see instr_is_predicated()), the memory reference may not always be accessed.

bool instr_reg_in_dst ( instr_t instr,
reg_id_t  reg 
)

Assumes that reg is a DR_REG_ constant. Returns true iff at least one of instr's destination operands references reg.

bool instr_reg_in_src ( instr_t instr,
reg_id_t  reg 
)

Assumes that reg is a DR_REG_ constant. Returns true iff at least one of instr's source operands references reg.

Returns false for multi-byte nops with a source operand using reg.

Note
Use instr_reads_from_reg() to also consider addressing registers in destination operands.
void instr_remove_dsts ( void *  drcontext,
instr_t instr,
uint  start,
uint  end 
)

Removes instr's destination operands from position start up to but not including position end (so pass n,n+1 to remove just position n). Shifts all subsequent destination operands (if any) down in the operand array. Also calls instr_set_raw_bits_valid(instr, false) and instr_set_operands_valid(instr, true).

void instr_remove_srcs ( void *  drcontext,
instr_t instr,
uint  start,
uint  end 
)

Removes instr's source operands from position start up to but not including position end (so pass n,n+1 to remove just position n). Shifts all subsequent source operands (if any) down in the operand array. Also calls instr_set_raw_bits_valid(instr, false) and instr_set_operands_valid(instr, true).

bool instr_replace_src_opnd ( instr_t instr,
opnd_t  old_opnd,
opnd_t  new_opnd 
)

Replaces all instances of old_opnd in instr's source operands with new_opnd (uses opnd_same() to detect sameness).

void instr_reset ( void *  drcontext,
instr_t instr 
)

Performs both instr_free() and instr_init(). instr must have been initialized.

void instr_reuse ( void *  drcontext,
instr_t instr 
)

Frees all dynamically allocated storage that was allocated by instr, except for allocated bits. Also zeroes out instr's fields, except for raw bit fields, whether instr is instr_is_meta(), and the x86 mode of instr. instr must have been initialized.

bool instr_same ( instr_t instr1,
instr_t instr2 
)

Returns true iff instr1 and instr2 have the same opcode, prefixes, and source and destination operands (uses opnd_same() to compare the operands).

void instr_set_app ( instr_t instr)

Sets instr as an application (non-meta) instruction. An application instruction might be mangled by DR if necessary, e.g., to create an exit stub for a branch instruction. All application instructions that are added to basic blocks or traces should have their translation fields set (via instr_set_translation()).

void instr_set_branch_target_pc ( instr_t cti_instr,
app_pc  pc 
)

Set the taken target pc of the (direct branch) instruction.

void instr_set_dst ( instr_t instr,
uint  pos,
opnd_t  opnd 
)

Sets instr's destination operand at position pos to be opnd. Also calls instr_set_raw_bits_valid(instr, false) and instr_set_operands_valid(instr, true).

bool instr_set_isa_mode ( instr_t instr,
dr_isa_mode_t  mode 
)

Each instruction stores the processor mode under which it should be interpreted. This routine sets the mode for instr.

void instr_set_meta ( instr_t instr)

Sets instr as a meta instruction. A meta instruction will not be mangled by DR in any way, which is necessary to have DR not create an exit stub for a branch instruction. Meta instructions should not fault (unless such faults are handled by the client) and are not considered application instructions but rather added instrumentation code (see dr_register_bb_event() for further information).

void instr_set_meta_may_fault ( instr_t instr,
bool  val 
)
Deprecated:
Any meta instruction can fault if it has a non-NULL translation field and the client fully handles all of its faults, so this routine is no longer needed.
void instr_set_meta_no_translation ( instr_t instr)

A convenience routine that calls both instr_set_meta (instr) and instr_set_translation (instr, NULL).

INSTR_INLINE void instr_set_next ( instr_t instr,
instr_t next 
)

Sets the next field of instr to point to next.

INSTR_INLINE void instr_set_note ( instr_t instr,
void *  value 
)

Sets the user-controlled note field in instr to value.

void instr_set_num_opnds ( void *  drcontext,
instr_t instr,
int  num_dsts,
int  num_srcs 
)

Assumes that instr has been initialized but does not have any operands yet. Allocates storage for num_srcs source operands and num_dsts destination operands.

void instr_set_ok_to_emit ( instr_t instr,
bool  val 
)

Set instr to "ok to emit" if val is true and "not ok to emit" if val is false. An instruction that should not be emitted is treated normally by DR for purposes of exits but is not placed into the cache. It is used for final jumps that are to be elided.

void instr_set_ok_to_mangle ( instr_t instr,
bool  val 
)

Sets instr to "ok to mangle" if val is true and "not ok to mangle" if val is false.

Deprecated:
instr_set_app()/instr_set_meta() should be used instead.
void instr_set_opcode ( instr_t instr,
int  opcode 
)

Assumes opcode is an OP_ constant and sets it to be instr's opcode.

void instr_set_operands_valid ( instr_t instr,
bool  valid 
)

Sets instr's operands to be valid if valid is true, invalid otherwise.

instr_t* instr_set_predicate ( instr_t instr,
dr_pred_type_t  pred 
)

Sets the predication for instr to the given DR_PRED_ constant. Returns instr if successful, or NULL if unsuccessful.

instr_t* instr_set_prefix_flag ( instr_t instr,
uint  prefix 
)

Assumes that prefix is a PREFIX_ constant. Ors instr's prefixes with prefix. Returns the supplied instr (for easy chaining).

INSTR_INLINE void instr_set_prev ( instr_t instr,
instr_t prev 
)

Sets the prev field of instr to point to prev.

void instr_set_raw_bits ( instr_t instr,
byte *  addr,
uint  length 
)

Assumes that instr does not currently have any raw bits allocated. Sets instr's raw bits to be length bytes starting at addr. Does not set the operands invalid.

void instr_set_raw_bits_valid ( instr_t instr,
bool  valid 
)

Sets instr's raw bits to be valid if valid is true, invalid otherwise.

void instr_set_raw_byte ( instr_t instr,
uint  pos,
byte  byte 
)

Assumes that instr's raw bits are valid and allocated by instr and have > pos bytes. Sets instr's raw byte at position pos (beginning with 0) to the value byte.

void instr_set_raw_bytes ( instr_t instr,
byte *  start,
uint  num_bytes 
)

Assumes that instr's raw bits are valid and allocated by instr and have >= num_bytes bytes. Copies the num_bytes beginning at start to instr's raw bits.

void instr_set_raw_word ( instr_t instr,
uint  pos,
uint  word 
)

Assumes that instr's raw bits are valid and allocated by instr and have > pos+3 bytes. Sets the 4 bytes beginning at position pos (0-based) to the value word.

void instr_set_src ( instr_t instr,
uint  pos,
opnd_t  opnd 
)

Sets instr's source operand at position pos to be opnd. Also calls instr_set_raw_bits_valid(instr, false) and instr_set_operands_valid(instr, true).

void instr_set_target ( instr_t cti_instr,
opnd_t  target 
)

Assumes that cti_instr is a control transfer instruction. Sets the first source operand of cti_instr to be target. Also calls instr_set_raw_bits_valid(instr, false) and instr_set_operands_valid(instr, true).

instr_t* instr_set_translation ( instr_t instr,
app_pc  addr 
)

Sets the translation pointer for instr, used to recreate the application address corresponding to this instruction. When adding or modifying instructions that are to be considered application instructions (i.e., non meta-instructions: see instr_is_app), the translation should always be set. Pick the application address that if executed will be equivalent to restarting instr. Currently the translation address must lie within the existing bounds of the containing code block. Returns the supplied instr (for easy chaining). Use instr_get_app_pc to see the current value of the translation.

void instr_set_x86_mode ( instr_t instr,
bool  x86 
)

Each instruction stores whether it should be interpreted in 32-bit (x86) or 64-bit (x64) mode. This routine sets the mode for instr.

Note
For 64-bit DR builds only.
Deprecated:
Replaced by instr_set_isa_mode().
void instr_shrink_to_16_bits ( instr_t instr)

Shrinks all registers not used as addresses, and all immed integer and address sizes, to 16 bits. Does not shrink DR_REG_ESI or DR_REG_EDI used in string instructions.

void instr_shrink_to_32_bits ( instr_t instr)

Shrinks all registers, including addresses, and all immed integer and address sizes, to 32 bits.

Note
For 64-bit DR builds only.
bool instr_uses_fp_reg ( instr_t instr)

Returns true iff at least one of instr's operands references a floating point register.

bool instr_uses_reg ( instr_t instr,
reg_id_t  reg 
)

Assumes that reg is a DR_REG_ constant. Returns true iff at least one of instr's operands references a register that overlaps reg.

Returns false for multi-byte nops with an operand using reg.

bool instr_valid ( instr_t instr)

Returns true iff instr's opcode is NOT OP_INVALID. Not to be confused with an invalid opcode, which can be OP_INVALID or OP_UNDECODED. OP_INVALID means an instruction with no valid fields: raw bits (may exist but do not correspond to a valid instr), opcode, eflags, or operands. It could be an uninitialized instruction or the result of decoding an invalid sequence of bytes.

bool instr_writes_memory ( instr_t instr)

Returns true iff any of instr's destination operands is a memory reference. If instr is predicated (see instr_is_predicated()), the destination may not always be written.

bool instr_writes_to_exact_reg ( instr_t instr,
reg_id_t  reg,
dr_opnd_query_flags_t  flags 
)

Assumes that reg is a DR_REG_ constant. Returns true iff at least one of instr's destination operands is the same register (not enough to just overlap) as reg. Which operands are considered to be accessed for conditionally executed instructions are controlled by flags.

bool instr_writes_to_reg ( instr_t instr,
reg_id_t  reg,
dr_opnd_query_flags_t  flags 
)

Assumes that reg is a DR_REG_ constant. Returns true iff at least one of instr's destination operands is a register operand for a register that overlaps reg. Which operands are considered to be accessed for conditionally executed instructions are controlled by flags.

bool instr_zeroes_ymmh ( instr_t instr)

Returns true iff instr writes to an xmm register and zeroes the top half of the corresponding ymm register as a result (some instructions preserve the top half while others zero it when writing to the bottom half). This zeroing will occur even if instr is predicated (see instr_is_predicated()).