DynamoRIO API
Multi-Instrumentation Manager

The drmgr DynamoRIO Extension provides a mediator for combining and coordinating multiple instrumentation passes. It replaces certain DynamoRIO events and API routines with its own versions that mediate among multiple components, typically several libraries and one client, though it is also useful for splitting a client up into modules. drmgr facilitates developing instrumentation frameworks and libraries that can be composed and combined.

Setup

To use drmgr with your client simply include this line in your client's CMakeLists.txt file:

use_DynamoRIO_extension(clientname drmgr)

That will automatically set up the include path and library dependence.

The drmgr_init() function may be called multiple times; subsequent calls will be nops and will return true for success. This allows a library to use drmgr without coordinating with the client over who invokes drmgr_init().

Event Replacement

In order to provide ordering control over event callbacks, drmgr replaces a number of DynamoRIO's events. For many of these, simply replacing dr_ with drmgr_ is sufficient, as that will then use a default priority. To request a priority, use the _ex version of the drmgr_register_ routine. The basic block event is a special case as it is completely replaced with a new set of multiple events for different stages of instrumentation.

Instrumentation Stages

drmgr divides code changes into three types:

  1. Application-to-application transformations: changes to the application code itself that are meant to affect application behavior or application performance
  2. Instrumentation insertion: monitoring code added between the application instructions
  3. Instrumentation-to-instrumentation transformations: typically, optimizations applied to the full set of inserted instrumentation

Instrumentation insertion is split into two pieces: analysis of the full application code (after any changes from its original form), followed by insertion of instrumentation, one instruction at a time. The result is four separate, sequential stages:

  1. Application-to-application transformations
  2. Application code analysis
  3. Instrumentation insertion, one instruction at a time
  4. Instrumentation-to-instrumentation transformations

Each component that registers with drmgr can register for some or all of the four stages. In each stage, each registered compoment's callback is invoked. This groups the different types of changes together and allows them to assume that no later change will invalidate their analysis or actions. The instrumentation insertion is performed in one forward pass: for each instruction, each registered component is invoked. This simplifies register allocation (register allocation is provided by a separate Extension drreg).

Ordering

The proper ordering of instrumentation passes depends on the particulars of what each pass is doing. drmgr supports naming each pass and specifying relative ordering by requesting that one pass occur before and/or after another named pass. Numeric priorities are also supported for resolving order among identical placement once named ordering is resolved.

Some ordering rules do apply. For example, function replacing should occur before most other application transformations. Ordering of instrumentation insertion and especially instrumentation-to-instrumentation transformations can be highly dependent on exact transformations involved. Care should be taken when ordering passes within each stage.

Traces

drmgr does not mediate trace instrumentation. Those interested in hot code should use the drmgr basic block events and act only when the for_trace parameter is set. Those wanting to optimize the longer code sequences in traces are on their own for register allocation, and must be careful to handle instrumentation that has already been added from the basic block events.

IT Blocks

To facilitate simple instrumentation of IT blocks, when in Thumb mode drmgr automatically adds the predicate of the application instruction being operated on in the instrumentation insertion stage to all meta instructions added by callbacks during that stage. Furthermore, drmgr automatically adds IT instructions after all stages are complete, to ensure that all condtional instructions are legal in Thumb mode.

Thread-Local and Callback-Local Storage

drmgr also coordinates sharing of the thread-local-storage field among multiple components and provides automated support for callback-private fields on Windows. It replaces the single dr_get_tls_field() pointer with two separate arrays of pointers: one for callback-shared fields, and one for callback-private fields. When a field is requested, an integer index is returned to the caller for use in retrieving the appropriate pointer.

Callback-local Storage

On Windows, events such as keypresses or mouse movements are delivered to applications as callbacks. These callbacks interrupt a thread's execution in order to handle the event. The interrupted context is saved and a new context entered. When the event handling is finished, the interrupted context is resumed. Callbacks can interrupt other callbacks, resulting in a stack of contexts.

When a tool maintains state across application execution, it must handle callback contexts. Thread-local storage (tls) is per-thread and is thus callback-shared. Callbacks interrupt thread execution to execute arbitrary amounts of code in a new context before returning to the interrupted context. Thread-local storage fields that persist across application execution can be overwritten during callback execution, resulting in incorrect values when returning to the original context. Callback-local storage, rather than thread-local storage, should be used for any fields that store information specific to the application's execution.

Callbacks are Windows-specific. The cls interfaces are not marked for Windows-only, however, to facilitate cross-platform code. We recommend that cross-plaform code be written using cls fields on both platforms; the fields on Linux will never be stacked and will function as tls fields. Technically the same context interruption can occur with a Linux signal, but Linux signals typically execute small amounts of code and avoid making stateful changes; furthermore, there is no guaranteed end point to a signal. The drmgr_push_cls() and drmgr_pop_cls() interface can be used to provide a stack of contexts on Linux, or to provide a stack of contexts for any other purpose such as layered wrapped functions. These push and pop functions are automatically called on Windows callback entry and exit.

Instruction Note Fields

Instrumentation passes often need to mark instructions with information for later passes. One method of doing this is to use the note field built in to the instr_t type. For example, labels can be inserted with their note fields corresponding to pre-defined constants to indicate insertion points. In order to avoid these note constants from overlapping and conflicting among different components or passes, drmgr provides mediation of the namespace.

drmgr does not make use of its note mediation mandatory and does not override instr_set_note() or instr_get_note(). Instrumentation passes should feel free to use pointer values in the note field. The note constant value mediation is intended for small constants that will not be confused with pointer values.