--- title: "Umbra: Shadow Memory Extension" layout: default permalink: /page_umbra.html ---

Dr. Memory

Umbra: Shadow Memory Extension

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

- Setup
- Shadow Memory Mapping
- Umbra API

# 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.