#include <drreg.h>

Data Fields
size_t	struct_size

uint	num_spill_slots

bool	conservative

bool(*	error_callback )(drreg_status_t status)

bool	do_not_sum_slots

Detailed Description

Specifies the options when initializing drreg.

Field Documentation

◆ conservative

bool _drreg_options_t::conservative

By default, drreg assumes that the application will not rely on the particular value of a dead register when a fault happens. This allows drreg to reduce overhead. This flag can be set to request that drreg not make this assumption.

If multiple drreg_init() calls are made, this field is combined by logical OR.

XXX i#3801: If a fault occurs between two spills of a GPR or aflags, where the second spill is after an app write, the current drreg application state restoration logic does not restore the dead GPR/aflags even with this field set to true. It is difficult to do so without additional metadata passed to the state restoration callback.

◆ do_not_sum_slots

bool _drreg_options_t::do_not_sum_slots

Generally, library routines should take in scratch registers directly, keeping drreg reservations in the end client. However, sometimes this model is not sufficient, and a library wants to directly reserve drreg registers or aflags. The library can ensure that drreg is initialized, without forcing the client to do so when the client is not directly using drreg already, by calling drreg_init() and setting do_not_sum_slots to true. This ensures that the total requested slots is at least num_spill_slots, but if the total is already higher than that, the total is left alone.. Thus, if clients invoke drreg_init() on their own, the library will not needlessly add to the number of simultaneous slots needed.

◆ error_callback

bool(* _drreg_options_t::error_callback) (drreg_status_t status)

Some drreg operations are performed during drmgr events where there is no direct return value to the user of drreg. When an error is encountered at these times, drreg will call this callback and pass the error value. If this callback is NULL, or if it returns false, drreg will call dr_abort().

If multiple drreg_init() calls are made, only the first callback is honored (thus, libraries generally should not set this).

◆ num_spill_slots

uint _drreg_options_t::num_spill_slots

The number of TLS spill slots to use. This many slots will be requested from DR via dr_raw_tls_calloc(). Any slots needed beyond this number will use DR's base slots, which are not allowed to be used across application instructions. DR's slots are also more expensive to access (beyond the first few). DR's base slots may also be used by APIs like dr_save_reg()/dr_restore_reg() (and the corresponding dr_read_saved_reg()/dr_write_saved_reg()), which may cause correctness issues if there's some slot usage conflict within the same client or with other clients/libraries. Therefore, all cooperating client components should use drreg. Also, clients should make sure to request sufficient dedicated slots from drreg. This number should be computed as one plus the number of simultaneously used general-purpose register spill slots, as drreg reserves one of the requested slots for arithmetic flag preservation.

For each simultaneous value that will be held in a register across application instructions, an additional slot must be requested for adjusting the saved application value with respect to application reads and writes.

When drreg_init() is called multiple times, the number of slots is summed from each call, unless do_not_sum_slots is specified for that call, in which case a maximum is used rather than a sum.

◆ struct_size

size_t _drreg_options_t::struct_size

Set this to the size of this structure.

The documentation for this struct was generated from the following file:

/home/runner/work/dynamorio/dynamorio/ext/drreg/drreg.h