dr_ir_encode.h File Reference

Encoding routines. More...

Typedefs

typedef enum _dr_isa_mode_t dr_isa_mode_t
 

Enumerations

enum  _dr_isa_mode_t {
  DR_ISA_IA32,
  DR_ISA_X86 = DR_ISA_IA32,
  DR_ISA_AMD64,
  DR_ISA_ARM_A32,
  DR_ISA_ARM_THUMB,
  DR_ISA_ARM_A64,
  DR_ISA_RV64IMAFDC
}
 

Functions

DR_API bool dr_set_isa_mode (void *drcontext, dr_isa_mode_t new_mode, dr_isa_mode_t *old_mode DR_PARAM_OUT)
 
DR_API dr_isa_mode_t dr_get_isa_mode (void *drcontext)
 
void dr_set_sve_vector_length (int vl)
 
int dr_get_sve_vector_length (void)
 
DR_API bool instr_is_encoding_possible (instr_t *instr)
 
DR_API byte * instr_encode (void *drcontext, instr_t *instr, byte *pc)
 
DR_API byte * instr_encode_to_copy (void *drcontext, instr_t *instr, byte *copy_pc, byte *final_pc)
 
DR_API byte * instrlist_encode (void *drcontext, instrlist_t *ilist, byte *pc, bool has_instr_jmp_targets)
 
DR_API byte * instrlist_encode_to_copy (void *drcontext, instrlist_t *ilist, byte *copy_pc, byte *final_pc, byte *max_pc, bool has_instr_jmp_targets)
 

Detailed Description

Encoding routines.

Typedef Documentation

◆ dr_isa_mode_t

Specifies which processor mode to use when decoding or encoding.

Enumeration Type Documentation

◆ _dr_isa_mode_t

Specifies which processor mode to use when decoding or encoding.

Enumerator
DR_ISA_IA32 

IA-32 (Intel/AMD 32-bit mode).

DR_ISA_X86 

Alias for DR_ISA_IA32.

DR_ISA_AMD64 

AMD64 (Intel/AMD 64-bit mode).

DR_ISA_ARM_A32 

ARM A32 (AArch32 ARM).

DR_ISA_ARM_THUMB 

Thumb (ARM T32).

DR_ISA_ARM_A64 

ARM A64 (AArch64).

DR_ISA_RV64IMAFDC 

RISC-V (rv64imafdc).

Function Documentation

◆ dr_get_isa_mode()

DR_API dr_isa_mode_t dr_get_isa_mode ( void *  drcontext)

The decode and encode routines use a per-thread persistent flag that indicates which processor mode to use. This routine returns the value of that flag.

◆ dr_get_sve_vector_length()

int dr_get_sve_vector_length ( void  )

Read AArch64 Scalable Vector Extension's vector length, in bits.

◆ dr_set_isa_mode()

DR_API bool dr_set_isa_mode ( void *  drcontext,
dr_isa_mode_t  new_mode,
dr_isa_mode_t *old_mode  DR_PARAM_OUT 
)

The decode and encode routines use a per-thread persistent flag that indicates which processor mode to use. This routine sets that flag to the indicated value and optionally returns the old value. Be sure to restore the old value prior to any further application execution to avoid problems in mis-interpreting application code.

◆ dr_set_sve_vector_length()

void dr_set_sve_vector_length ( int  vl)

AArch64 Scalable Vector Extension's vector length in bits is one of: 128 256 384 512 640 768 896 1024 1152 1280 1408 1536 1664 1792 1920 2048 TODO i#3044: This function will only allow setting vector length if not running on SVE.

◆ instr_encode()

DR_API 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 offset 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().

◆ instr_encode_to_copy()

DR_API 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 offset 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().

◆ instr_is_encoding_possible()

DR_API bool instr_is_encoding_possible ( instr_t instr)

Returns true iff instr can be encoded as

  • a valid IA-32 instruction on X86
  • a valid Armv8-a instruction on AArch64 (Note: The AArch64 encoder/decoder is not complete yet, so DynamoRIO may fail to encode some valid Armv8-a instructions)
  • a valid Armv7 instruction on ARM

◆ instrlist_encode()

DR_API byte* instrlist_encode ( void *  drcontext,
instrlist_t ilist,
byte *  pc,
bool  has_instr_jmp_targets 
)

Encodes each instruction in ilist in turn in contiguous memory starting at pc. Returns the pc after all of the encodings, or NULL if any one of the encodings failed. Uses the x86/x64 mode stored in each instr, not the mode of the current thread. In order for instr_t operands to be encoded properly, has_instr_jmp_targets must be true. If has_instr_jmp_targets is true, the offset field of each instr_t in ilist will be overwritten, and if any instr_t targets are not in ilist, they must have their offset fields set with their offsets relative to pc. x86 instructions can occupy up to 17 bytes each, so the caller should ensure the target location has enough room to avoid overflow.

◆ instrlist_encode_to_copy()

DR_API byte* instrlist_encode_to_copy ( void *  drcontext,
instrlist_t ilist,
byte *  copy_pc,
byte *  final_pc,
byte *  max_pc,
bool  has_instr_jmp_targets 
)

Encodes each instruction in ilist in turn in contiguous memory starting copy_pc in preparation for copying to final_pc. Any pc-relative instruction is encoded as though the instruction list were located at final_pc. This allows for direct copying of the encoded bytes to final_pc without re-relativization.

Returns the pc after all of the encodings, or NULL if any one of the encodings failed.

Uses the x86/x64 mode stored in each instr, not the mode of the current thread.

In order for instr_t operands to be encoded properly, has_instr_jmp_targets must be true. If has_instr_jmp_targets is true, the offset field of each instr_t in ilist will be overwritten, and if any instr_t targets are not in ilist, they must have their offset fields set with their offsets relative to pc.

If max_pc is non-NULL, computes the total size required to encode the instruction list before performing any encoding. If the whole list will not fit starting at copy_pc without exceeding max_pc, returns NULL without encoding anything. Otherwise encodes as normal. Note that x86 instructions can occupy up to 17 bytes each, so if max_pc is NULL, the caller should ensure the target location has enough room to avoid overflow.