Memory Debugger for Windows, Linux, and Mac
Dr. Memory
Umbra: Shadow Memory Extension

The Umbra DynamoRIO Extension provides shadow memory features. Umbra is part of the Dr. Memory Framework.

Setup

To use Umbra with your client, first locate the Dr. Memory Framework. Then use the standard method of using an Extension with the name umbra. The two steps will look like this in your client's CMakeLists.txt file:

find_package(DrMemoryFramework)
use_DynamoRIO_extension(clientname umbra)

To point CMake at the framework, set the DrMemoryFramework_DIR variable to point at the drmf subdirectory of the Dr. Memory package that you are using. For example:

cmake -G"Ninja" -DDynamoRIO_DIR=c:/path/to/DynamoRIO-Windows-4.1.0-8/cmake -DDrMemoryFramework_DIR=c:/path/to/DrMemory-Windows-1.6.0-2/drmf ../mysrcs/

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

Your client must call umbra_init() prior to accessing any API routines in umbra, and should call umbra_exit() at process exit time.

Shadow Memory Mapping

A shadow memory mapping scheme map is an opaque data structure that describes how an application memory address is mapped to its corresponding shadow memory address. A mapping scheme can be created using umbra_create_mapping() and destroyed using umbra_destroy_mapping(). A shadow memory mapping scheme must be created before any use of any shadow memory.

Once a mapping scheme is in place, shadow memory can be created and deleted for application memory using umbra_create_shadow_memory() and umbra_delete_shadow_memory().

Umbra API

Umbra provides the following key features:

  1. Create/delete shadow memory
  2. Read/write shadow memory
  3. Iterate over every application/shadow memory region
  4. Instrument code to access shadow memory

The client can use the provided Umbra APIs to manange and access shadow memory without knowing the actual shadow memory address or how shadow memory is managed. Advanced users can create "special" shadow memory (read-only memory region with default value) or directly access shadow memory for better performanc and memory usage.

Umbra may use page faults to implement lazy shadow memory allocation. When generating meta instructions to read shadow values, be sure to assign translation values to the instructions.

Some shadow mapping schemes do not support shadow memory for invalid application addresses (i.e., addresses for which no application memory is allocated). If such application addresses are passed to shadow API routines, they will fail with DRMF_ERROR_INVALID_ADDRESS, while shadow memory type queries will indicate UMBRA_SHADOW_MEMORY_TYPE_NOT_SHADOW.