| /* ********************************************************** | |
| * 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. | |
| */ |