Detours 2.1

Microsoft Research Detours Package, Express Version 2.1 Build_216. DISCLAIMER AND LICENSE: ======================= The entire Detours package is covered by copyright law. Copyright (c) Microsoft Corporation. All rights reserved. Portions may be covered by patents owned by Microsoft Corporation. Usage of the Detours package is covered under the End User License Agreement. Your usage of Detours implies your acceptance of the End User License Agreement. If you distribute programs which use Detours, you must also distribute a copy of DETOURED.DLL, which is required for your program to execute. DETOURED.DLL is built when you build the libraries. A complete list of redistributable files is in REDIST.TXT. 1. INTRODUCTION: ================ This document describes the installation and usage of this version of the Detours package. In particular, it provides an updated API table. Complete documentation for the Detours package, including a detailed API reference can be found in the Detours.chm file. 2. BUILD INSTRUCTIONS: ====================== To build the libraries and the sample applications, type "nmake". 3. VERIFYING THE INSTALL AND BUILD: =================================== After building the libraries and sample applications, you can verify that the Detours packet works on your Windows OS by type "nmake test" in the samples\slept directory. The output of "namke test" should be similar to that contained in the file samples\slept\NORMAL.TXT. 4. CHANGES IN VERSION 2.1: ========================== The following major changes were made in Detours 2.1 from Detours 2.0: * Addition of support for 64-bit code on Itanium 2 processors, using the IA64 instruction set. * Correction to disassembly table for X86 for indirection instructions with either 8-bit or 32-bit constant operands. The following major changes were made in Detours 2.0 from Detours 1.5: * Complete API documentation. * Support for 64-bit code on X64 processors. * Addition of a transactional model for attaching and detaching detours. * Addition of code for updating peer threads when adjusting detours. * Replaced trampoline pointers with target pointers in the API to simplify usage. * Support for detection of detoured processes. * Significant compatibility fixes in the DetourCreateProcessWithDll API. * Removed the DetourContinueProcessWithDll API. * Added DetourCopyPayloadToProcess API to copy payloads to target processes. 4.1. COMPLETE API DOCUMENTATION: ================================ Detours 2.1 includes extensive online documentation in the Detours.chm file. The documentation includes a technical overview of the Detours package, an extensive API reference, descriptions of all of the Detours samples with cross-links to the relevant APIs, and a list of Frequently Asked Questions (FAQ) and answers. 4.2. 64-BIT SUPPORT: ==================== Detours 2.1 adds support 64-bit execution on X64 and IA64 processors. Detours understands the new 64-bit instructions of the X64 and IA64 and can detour 64-bit code when used in a 64-bit process. However, Detours does not support cross-compatibility between 32-bit and 64-bit code. For example, 32-bit detours can be applied only to 32-bit code, and 64-bit detours can be applied only to 64-bit code. 4.3. TRANSACTIONAL MODEL AND THREAD UPDATE: =========================================== Typically, a developer uses the Detours package to detour a family of functions. Race conditions can be introduced into the detour code as the target functions are detoured one by one. Also, the developer typically wants a error model in which all target functions are detours entirely or none of the target functions are detoured if a particular function can't be detoured. In previous version of Detours, programmers either ignored these race and error conditions, or attempted to avoid them by carefully timing the insertion and deletion of detours. To simplify the development model, Detours 2.1 use a transactional model for attaching and detaching detours. Your code should call DetourTransactionBegin to begin a transaction, issue a group of DetourAttach or DetourDetach calls to affect the desired target functions, call DetourUpdateThread to mark threads which may be effected by the updates, and then call DetourTransactionCommit to complete the operation. When DetourTranactionCommit is called, Detours suspends all effected threads (except the calling thread), insert or removes the detours as specified, updates the program counter for any threads that were running inside the effected functions, then resumes the effected threads. If an error occurs during the transaction, or if DetourTransactioAbort is called, Detours safely aborts all of the operations within the transaction. From the perspective of all threads marks for update, the entire transaction is atomic, either all threads and functions are modified, or none or modified. 4.4. REPLACED TRAMPOLINE POINTERS WITH TARGET POINTERS IN THE API: ==================================================================== A trampoline is a small block of code modified by Detours to contain the instructions of the target function moved to insert the detour and a jump to the remainder of the target function. In previous versions of Detours, trampolines where managed by the developer. Detours made this as easy as possibly by providing C macros to statically create new trampolines, but developer code was prone to undetected mismatches in function signatures between target functions, detour functions and trampolines. In addition, the developers were forced to use different APIs for statically and dynamically available functions. With Detours 2.1, the allocation, construction, and management of trampolines is controlled completely by Detours. Instead of directly using trampolines, developers should now use target pointers to refer to target functions. Initially, the target pointer should point to the target function. When a detour is attached to the target function, Detours will allocate a trampoline function, and update the target pointer to point to the trampoline. When the detour is detached from the target function, Detours will restore the target pointer to the target function and release the trampoline. Thanks to common C/C++ syntax, target pointers can be used exactly like functions. The most important benefit of using target pointers, instead of trampolines directly, is that C and C++ compiler check the check the equality of calling conventions on function pointer assignment. As a result, any discrepancy between the calling conventions of a target function and a detour function will be detected at compile time, rather than appear at runtime as mysterous bugs caused by stack misalignment. Another benefit of using target pointers is the reduction in the Detours APIs as the same APIs cab be used regardless of whether the address of a target function is available at link time or must be derived dynamically. 4.5. SUPPORT FOR DETECTION OF DETOURED PROCESSES: ================================================= Detours loads the detoured.dll shared library stub into any process which has been modified by the insertion of a detour. This allows the Microsoft Customer Support Services (CSS) and the Microsoft Online Crash Analysis (OCA) teams to quickly and accurately determine that the behavior of a process has been altered by a detour. CSS does not provide customer assistance on detoured products. 4.6. SIGNIFICANT COMPATIBILITY FIXES IN THE DETOURCREATEPROCESSWITHDLL API: =========================================================================== The DetourCreateProcessWithDll API has been completely rewritten. The previous version of the API used a code injection mechanism to create a call to LoadLibrary in the target process. The cod