The drwrap DynamoRIO Extension provides function wrapping and replacing support.

Setup

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

use_DynamoRIO_extension(clientname drwrap)

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

Initialize and clean up drwrap by calling drwrap_init() and drwrap_exit().

Event Replacement

drwrap uses the drmgr Extension to ensure its events occur at the proper order. A user of drwrap must use the drmgr versions of the basic block and thread events.

API

The first step in replacing or wrapping is to determine the address of the target application function. For functions exported by an application library, use dr_get_proc_address() to locate the entry point. For internal functions, use the drsyms Extension (see Symbol Access Library).

Function replacing is provided by drwrap_replace(). The replacement function executes as application code and will be passed to the client via the basic block and trace events just like any other application code. The replaced function may still show up in the basic block event as a jump instruction; none of its actual code will execute. To avoid changing application behavior, ensure that the replacement function mirrors the calling convention and other semantics of the original function.

Function wrapping is provided by drwrap_wrap(). A pre-function and/or post-function callback must be provided. The pre-function callback is invoked prior to every execution of the target function. The callback can examine and change function arguments and can skip the call to the target function (in which case there will be no post-function callback). The post-function callback can examine and change the target function's return value. Information (including copies of the arguments for examination in the post-function) can be passed between the pre- and post-functions via a user-controlled parameter.

Multiple wrap requests are allowed for one target function. Their callbacks are called sequentially in the reverse order of registration. If any pre-function callback asks to skip the function, the remaining pre-function callbacks will not be called, nor will any post-function callback.

The pre-function callback occurs at the beginning of the wrapped function, i.e., it executes after the call instruction but before any instructions within the body of the wrapped function. The post-function callback occurs after the wrapped function returns, as if inserted just after the call instruction.

Performance

For the lowest overhead, if your use case is compatible with the (relatively minor) limitations imposed by the two flags DRWRAP_NO_FRILLS and DRWRAP_FAST_CLEANCALLS, we recommend setting them both.

A major cause of overhead is flushing when a post-call point is dynamically discovered and it is already present in the code cache. The drwrap_get_stats() interface can be used to measure the number of flushes triggered by drwrap.

LGPL 2.1 License

The drwrap Extension is licensed under the LGPL 2.1 License and NOT the BSD license used for the rest of DynamoRIO.