blob: 4f5595ea80cfb7a37945caf327d5a9c95ae59f65 [file]
/* **********************************************************
* Copyright (c) 2014 Google, Inc. All rights reserved.
* **********************************************************/
/*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
* * Redistributions of source code must retain the above copyright notice,
* this list of conditions and the following disclaimer.
*
* * Redistributions in binary form must reproduce the above copyright notice,
* this list of conditions and the following disclaimer in the documentation
* and/or other materials provided with the distribution.
*
* * Neither the name of Google, Inc. nor the names of its contributors may be
* used to endorse or promote products derived from this software without
* specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
* ARE DISCLAIMED. IN NO EVENT SHALL GOOGLE, INC. OR CONTRIBUTORS BE LIABLE
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
* SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
* CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
* DAMAGE.
*/
/**
***************************************************************************
***************************************************************************
\page page_umbra Umbra: Shadow Memory Extension
The \p Umbra DynamoRIO Extension provides shadow memory features.
\p Umbra is part of the Dr. Memory Framework.
- \ref sec_umbra_setup
- \ref sec_umbra_mapping
- \ref sec_umbra_API
\section sec_umbra_setup Setup
To use \p Umbra with your client, first locate the Dr. Memory
Framework. Then use the standard method of using an Extension with the
name \p umbra. The two steps will look like this in your client's
\p CMakeLists.txt file:
\code
find_package(DrMemoryFramework)
use_DynamoRIO_extension(clientname umbra)
\endcode
To point CMake at the framework, set the DrMemoryFramework_DIR variable to
point at the \p drmf subdirectory of the Dr. Memory package that you are
using. For example:
\code
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/
\endcode
That will automatically set up the include path and library dependence.
Your client must call \p umbra_init() prior to accessing any API
routines in \p umbra, and should call \p umbra_exit() at process exit
time.
\section sec_umbra_mapping Shadow Memory Mapping
A shadow memory mapping scheme \p 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 \p umbra_create_mapping() and destroyed using
\p 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 \p umbra_create_shadow_memory() and
\p umbra_delete_shadow_memory().
\section sec_umbra_API Umbra API
\p 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 \p 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.
*/