DynamoRIO API
Register Usage Coordinator

Data Structures

struct  _drreg_options_t
 

Macros

#define DRMGR_PRIORITY_NAME_DRREG_HIGH   "drreg_high"
 
#define DRMGR_PRIORITY_NAME_DRREG_LOW   "drreg_low"
 
#define DRMGR_PRIORITY_NAME_DRREG_FAULT   "drreg_fault"
 

Typedefs

typedef struct _drreg_options_t drreg_options_t
 

Enumerations

enum  drreg_status_t {
  DRREG_SUCCESS,
  DRREG_ERROR,
  DRREG_ERROR_INVALID_PARAMETER,
  DRREG_ERROR_FEATURE_NOT_AVAILABLE,
  DRREG_ERROR_REG_CONFLICT,
  DRREG_ERROR_IN_USE,
  DRREG_ERROR_OUT_OF_SLOTS,
  DRREG_ERROR_NO_APP_VALUE
}
 
enum  {
  DRMGR_PRIORITY_INSERT_DRREG_HIGH = -7500,
  DRMGR_PRIORITY_INSERT_DRREG_LOW = 7500,
  DRMGR_PRIORITY_FAULT_DRREG = -7500
}
 
enum  drreg_bb_properties_t {
  DRREG_CONTAINS_SPANNING_CONTROL_FLOW = 0x001,
  DRREG_IGNORE_CONTROL_FLOW = 0x002
}
 

Functions

DR_EXPORT drreg_status_t drreg_init (drreg_options_t *ops)
 
DR_EXPORT drreg_status_t drreg_exit (void)
 
DR_EXPORT drreg_status_t drreg_max_slots_used (OUT uint *max)
 
DR_EXPORT drreg_status_t drreg_reserve_aflags (void *drcontext, instrlist_t *ilist, instr_t *where)
 
DR_EXPORT drreg_status_t drreg_unreserve_aflags (void *drcontext, instrlist_t *ilist, instr_t *where)
 
DR_EXPORT drreg_status_t drreg_aflags_liveness (void *drcontext, instr_t *inst, OUT uint *value)
 
DR_EXPORT drreg_status_t drreg_are_aflags_dead (void *drcontext, instr_t *inst, bool *dead)
 
DR_EXPORT drreg_status_t drreg_reserve_register (void *drcontext, instrlist_t *ilist, instr_t *where, drvector_t *reg_allowed, OUT reg_id_t *reg)
 
DR_EXPORT drreg_status_t drreg_reserve_dead_register (void *drcontext, instrlist_t *ilist, instr_t *where, drvector_t *reg_allowed, OUT reg_id_t *reg)
 
DR_EXPORT drreg_status_t drreg_init_and_fill_vector (drvector_t *vec, bool allowed)
 
DR_EXPORT drreg_status_t drreg_set_vector_entry (drvector_t *vec, reg_id_t reg, bool allowed)
 
DR_EXPORT drreg_status_t drreg_get_app_value (void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t app_reg, reg_id_t dst_reg)
 
DR_EXPORT drreg_status_t drreg_restore_app_values (void *drcontext, instrlist_t *ilist, instr_t *where, opnd_t opnd, INOUT reg_id_t *swap)
 
DR_EXPORT drreg_status_t drreg_reservation_info (void *drcontext, reg_id_t reg, opnd_t *opnd OUT, bool *is_dr_slot OUT, uint *tls_offs OUT)
 
DR_EXPORT drreg_status_t drreg_unreserve_register (void *drcontext, instrlist_t *ilist, instr_t *where, reg_id_t reg)
 
DR_EXPORT drreg_status_t drreg_is_register_dead (void *drcontext, reg_id_t reg, instr_t *inst, bool *dead)
 
DR_EXPORT drreg_status_t drreg_set_bb_properties (void *drcontext, drreg_bb_properties_t flags)
 

Detailed Description

Macro Definition Documentation

#define DRMGR_PRIORITY_NAME_DRREG_FAULT   "drreg_fault"

Name of drreg fault handling event.

#define DRMGR_PRIORITY_NAME_DRREG_HIGH   "drreg_high"

Name of drreg instrumentation pass priorities for analysis and insert steps that are meant to take place before any tool actions.

#define DRMGR_PRIORITY_NAME_DRREG_LOW   "drreg_low"

Name of drreg instrumentation pass priorities for analysis and insert steps that are meant to take place after any tool actions.

Typedef Documentation

Specifies the options when initializing drreg.

Enumeration Type Documentation

anonymous enum

Priorities of drmgr instrumentation passes used by drreg. Users of drreg can use the name DRMGR_PRIORITY_NAME_DRREG in the drmgr_priority_t.before field or can use these numeric priorities in the drmgr_priority_t.priority field to ensure proper instrumentation pass ordering.

Enumerator
DRMGR_PRIORITY_INSERT_DRREG_HIGH 

Priority of drreg analysis and pre-insert

DRMGR_PRIORITY_INSERT_DRREG_LOW 

Priority of drreg post-insert

DRMGR_PRIORITY_FAULT_DRREG 

Priority of drreg fault handling event

Flags passed to drreg_set_bb_properties().

Enumerator
DRREG_CONTAINS_SPANNING_CONTROL_FLOW 

drreg was designed for linear control flow and assumes that it can safely wait to restore an unreserved scratch register across application instructions. If a client inserts internal control flow that crosses application instructions (hence "spanning"), and the client is not explicitly ensuring that each forward jump contains the same set of saved scratch registers at its source and target (typically done by saving all scratch registers needed inside control flow prior to any forward branches), the client should set this property either prior to the drmgr insertion phase or as early as possible in the insertion phase. Setting this property causes application instructions to become barriers to spilled scratch registers that have been unreserved but have not yet been lazily restored. drreg will still collapse adjacent spill+restore pairs for the same app instr.

DRREG_IGNORE_CONTROL_FLOW 

drreg was designed for linear control flow. Normally, drreg disables optimizations if it sees any kind of internal control flow (viz., a branch with an instr_t target) that was added during drmgr's app2app phase, which includes flow added by drutil_expand_rep_string(). The primary consequence of disabling optimizations means that application instructions become barriers to spilled scratch registers that have been unreserved but have not yet been lazily restored, which are restored prior to each application instruction. If this flag is set, drreg assumes that internal control flow either does not cross application instructions or that the client is ensuring that each forward jump contains the same set of saved scratch registers at its source and target (typically done by saving all scratch registers needed inside control flow prior to any forward branches). Such scratch registers are then restored prior to each application instruction.

Success code for each drreg operation

Enumerator
DRREG_SUCCESS 

Operation succeeded.

DRREG_ERROR 

Operation failed.

DRREG_ERROR_INVALID_PARAMETER 

Operation failed: invalid parameter

DRREG_ERROR_FEATURE_NOT_AVAILABLE 

Operation failed: not available

DRREG_ERROR_REG_CONFLICT 

Operation failed: register conflict

DRREG_ERROR_IN_USE 

Operation failed: resource already in use

DRREG_ERROR_OUT_OF_SLOTS 

Operation failed: no more TLS slots

DRREG_ERROR_NO_APP_VALUE 

Operation failed: app value not available. Set conservative in drreg_options_t to avoid this error.

Function Documentation

DR_EXPORT drreg_status_t drreg_aflags_liveness ( void *  drcontext,
instr_t inst,
OUT uint *  value 
)

Returns in value EFLAGS_READ_6 bits telling which arithmetic flags are live at the point of inst. If called during drmgr's insertion phase, inst must be the current application instruction.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_are_aflags_dead ( void *  drcontext,
instr_t inst,
bool *  dead 
)

Returns in dead whether the arithmetic flags are all dead at the point of inst. If called during drmgr's insertion phase, inst must be the current application instruction.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_exit ( void  )

Cleans up the drreg extension.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_get_app_value ( void *  drcontext,
instrlist_t *  ilist,
instr_t where,
reg_id_t  app_reg,
reg_id_t  dst_reg 
)

Inserts instructions at where in ilist to retrieve the application value for app_reg into dst_reg. This will automatically be done for reserved registers prior to an application instruction that reads app_reg, but sometimes instrumentation needs to read the application value of a register that has been reserved. If app_reg is a dead register, DRREG_ERROR_NO_APP_VALUE may be returned. Set conservative in drreg_options_t to avoid this error.

If called during drmgr's insertion phase, where must be the current application instruction.

On ARM, asking to place the application value of the register returned by dr_get_stolen_reg() into itself is not supported. Instead the caller should use dr_insert_get_stolen_reg_value() and opnd_replace_reg() to swap the use of the stolen register within a tool instruction with a scratch register.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_init ( drreg_options_t ops)

Initializes the drreg extension. Must be called prior to any of the other routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to drreg_exit(). The fields of ops are combined from multiple calls as described in the documentation for each field. Typically the end-user tool itself specifies these options, with most other library components not directly interacting with drreg (libraries often take in scratch registers from the caller for most of their operations).

Parameters
[in]opsSpecifies the optional parameters that control how drreg operates.
Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_init_and_fill_vector ( drvector_t vec,
bool  allowed 
)

Initializes vec to hold DR_NUM_GPR_REGS entries, each either set to NULL if allowed is false or a non-NULL value if allowed is true. This is intendend as a convenience routine for setting up the reg_allowed parameter to drreg_reserve_register().

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_is_register_dead ( void *  drcontext,
reg_id_t  reg,
instr_t inst,
bool *  dead 
)

Returns in dead whether the register reg is dead at the point of inst. If called during drmgr's insertion phase, inst must be the current application instruction.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_max_slots_used ( OUT uint *  max)

In debug build, drreg tracks the maximum simultaneous number of spill slots in use. This can help a user to tune drreg_options_t.num_spill_slots.

Parameters
[out]maxThe maximum number of spill slots used is written here.
Returns
whether successful or an error code on failure. In release build, this routine always fails.
DR_EXPORT drreg_status_t drreg_reservation_info ( void *  drcontext,
reg_id_t  reg,
opnd_t *opnd  OUT,
bool *is_dr_slot  OUT,
uint *tls_offs  OUT 
)

Returns information about the TLS slot assigned to reg, which must be a currently-reserved register.

If opnd is non-NULL, returns an opnd_t in opnd that references the TLS slot assigned to reg. If too many slots are in use and reg is stored in a non-directly-addressable slot, returns a null opnd_t in opnd.

If is_dr_slot is non-NULL, returns true if the slot is a DR slot (and can thus be accessed by dr_read_saved_reg()) and false if the slot is inside the dr_raw_tls_calloc() allocation used by drreg.

If tls_offs is non-NULL, if the slot is a DR slot, returns the DR slot index; otherwise, returns the offset from the TLS base of the slot assigned to reg.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_reserve_aflags ( void *  drcontext,
instrlist_t *  ilist,
instr_t where 
)

Requests exclusive use of the arithmetic flags register. Spills the application value at where in ilist, if necessary. When used during drmgr's insertion phase, optimizations such as keeping the application flags value in a register and eliding duplicate spills and restores will be automatically applied. If called during drmgr's insertion phase, where must be the current application instruction.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_reserve_dead_register ( void *  drcontext,
instrlist_t *  ilist,
instr_t where,
drvector_t reg_allowed,
OUT reg_id_t reg 
)

Identical to drreg_reserve_register() except returns failure if no register is available that does not require a spill.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_reserve_register ( void *  drcontext,
instrlist_t *  ilist,
instr_t where,
drvector_t reg_allowed,
OUT reg_id_t reg 
)

Requests exclusive use of an application register, spilling the application value at where in ilist if necessary. The register chosen is returned in reg.

When used during drmgr's insertion phase, optimizations such as keeping the application flags value in a register and eliding duplicate spills and restores will be automatically applied. If called during drmgr's insertion phase, where must be the current application instruction.

If reg_allowed is non-NULL, only registers from the specified set will be considered, where reg_allowed must be a vector with one entry for each general-purpose register in [DR_REG_START_GPR..DR_REG_STOP_GPR] where a NULL entry indicates not allowed and any non-NULL entry indicates allowed. The drreg_init_and_fill_vector() routine can be used to set up reg_allowed.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_restore_app_values ( void *  drcontext,
instrlist_t *  ilist,
instr_t where,
opnd_t  opnd,
INOUT reg_id_t swap 
)

This is a convenience routine that calls drreg_get_app_value() for every register used by opnd, with that register passed as the application and destination registers. This routine will write to reserved as well as unreserved registers. This is intended as a convenience barrier for lazy restores performed by drreg.

If called during drmgr's insertion phase, where must be the current application instruction.

On ARM, asking to place the application value of the register returned by dr_get_stolen_reg() into itself is not supported. If opnd uses the stolen register, this routine will swap it for a scratch register. This scratch register will be *swap if *swap is not DR_REG_NULL; otherwise, drreg_reserve_register() with NULL for reg_allowed will be called, and the result returned in *swap. It is up to the caller to un-reserve the register in that case.

Returns
whether successful or an error code on failure. On failure, any values that were already restored are not undone.
DR_EXPORT drreg_status_t drreg_set_bb_properties ( void *  drcontext,
drreg_bb_properties_t  flags 
)

May only be called during drmgr's app2app, analysis, or insertion phase. Sets the given properties for the current basic block being instrumented.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_set_vector_entry ( drvector_t vec,
reg_id_t  reg,
bool  allowed 
)

Sets the entry in vec at index reg minus DR_REG_START_GPR to NULL if allowed is false or a non-NULL value if allowed is true. This is intendend as a convenience routine for setting up the reg_allowed parameter to drreg_reserve_register().

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_unreserve_aflags ( void *  drcontext,
instrlist_t *  ilist,
instr_t where 
)

Terminates exclusive use of the arithmetic flags register. Restores the application value at where in ilist, if necessary. If called during drmgr's insertion phase, where must be the current application instruction.

Returns
whether successful or an error code on failure.
DR_EXPORT drreg_status_t drreg_unreserve_register ( void *  drcontext,
instrlist_t *  ilist,
instr_t where,
reg_id_t  reg 
)

Terminates exclusive use of the register reg. Restores the application value at where in ilist, if necessary. If called during drmgr's insertion phase, where must be the current application instruction.

Returns
whether successful or an error code on failure.