Umbra DynamoRIO Extension provides shadow memory features.
Umbra is part of the Dr. Memory Framework.
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
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:
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 provides the following key features:
- Create/delete shadow memory
- Read/write shadow memory
- Iterate over every application/shadow memory region
- 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.