samfzb / detours Goto Github PK

Microsoft Research Detours Package
Express Version 3.0 Build_316

DISCLAIMER AND LICENSE:
=======================
The entire Detours package is covered by copyright law.
Copyright (c) Microsoft Corporation.  All rights reserved.
Portions are 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.

Detours 3.0 Professional, which includes rights to use Detours in commerical
products and production use is available through the online Microsoft Store:
http://www.microsoftstore.com/store/msstore/en_US/pd/productID.216531800


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:
======================
If you installed Detours under the "Program Files" directory, copy the entire
contents of the detours directory to some other location where your account
has write access before attempting to build.

To build the libraries and the sample applications, type "nmake" in the
root directory of your Detours distribution.

If you are using Detours for the first time, a good practice is to start
by modifying one of the samples that is closest to your desired usage.


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 typing "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 3.0:
==========================
The following major changes were made in Detours 3.0 from Detours 2.x:
 * Support for mixing 32-bit and 64-bit processes.
 * Support for ARM processors (in addition to support for X86, X64, and IA64).
 * Removal of the detoured.dll marker binary.
 * Compatibility improvements, especially on x64 processors.
 * Addition of APIs to enumerate PE binary Imports and to determine the
   module referenced by a function pointer.
 * Improved support for highly-optimized code on X64 processors.
 * Improved support for detouring hot-patchable binaries.
 * Improved algorithm for allocation of trampolines.


4.1. SUPPORT FOR MIXING 32-BIT AND 64-BIT PROCESSES:
====================================================
Previous version of Detours only supported pure 64-bit or pure 32-bit
environments.  Detours 3.0 includes support for creating parallel 32-bit
and 64-bit DLLs that can be loaded dynamically into target processes with
Detours automatically selecting the correct architectur DLL. The
DetourCreateProcessWithDllEx function selects the correct DLL based on
the word size (32-bit or 64-bit) of the target process.  For more
information see the "Detouring 32-bit and 64-bit Processes" section of
the Detours documentation (Detours.chm).


4.2. ARM SUPPORT:
=================
Detours 3.0 includes support for detouring functions on ARM processors
using the Thumb-2 instruction set.


4.3. REMOVAL OF DETOURED.DLL:
=============================
Products shipping with Detours 3.0 no longer need to include detoured.dll
in their dependencies.  Prior to Detours 3.0, Detours loaded the detoured.dll
shared library stub into any process which was modified by the insertion of
a detour.  This allowed 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.
Microsoft does not provide customer assistance on detoured products.

With Detours 3.0, detoured.dll has been removed.  Advances in recent versions
of Windows allow CSS and OCA to accurately track third-party code that has
been loaded into a process, thus removing the need for detoured.dll.  One
side effect of this change is that the path to the detoured.dll is no longer
provided as an argument to DetourCreateProcessWithDll, reducing it's argument
count by one.


4.4. COMPATIBILITY IMPROVEMENTS:
================================
Fixes have been made in Detours 3.0 to improve support for target binaries
containing no DLL imports, DLL binaries compiled for online-patching,
binaries generated with hot-patching support, and 64-bit PE binaries
containing managed code.


4.5. APIS TO ENUMERATE PE BINARY IMPORTS:
=========================================
Added DetourEnumerateImports API to enumerate the functions imported by a
EXE or DLL.  Given a pointer to a function, the DetourGetContainingModule
API will return the HMODULE of the binary within which it resides.


4.6. 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 detoured 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 3.0 uses 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 affected by the updates, and then call
DetourTransactionCommit to complete the operation.

When DetourTransactionCommit 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 affected functions, then resumes the affected 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 marked for update, the entire transaction is atomic,
either all threads and functions are modified, or none are modified.


4.7. 64-BIT SUPPORT:
====================
Detours includes support for 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.


4.8. ALLOCATION OF TRAMPOLINES:
===============================
To intercept calls, Detours copies the first few instructions of the target
function into a block of memory called a trampoline.  In previous versions
of Detours, trampolines were allocated a close as possible to the target
code.  In some cases, the trampoline memory would conflict with later
DLL loads in the same process.  This would hurt performance by causing
later DLLs to be dynamically rebased.  Detours 3.0 includes a new algorithm
for allocating trampolines.  The new algorithm attempts to place trampolines
roughly 1GB above or below the target code in the address space.


5. API SUMMARY:
===============

5.1. APIS FOR DETOURING TARGET FUNCTIONS:
=========================================
DetourTransactionBegin()    - Begin a new detour transaction.

DetourUpdateThread()        - Mark a thread that should be included in the
                              current detour transaction.

DetourAttach()              - Attach a detour to a target function as part
                              of the current detour transaction.

DetourAttachEx()            - Attach a detour to a target function and
                              retrieved additional detail about the ultimate
                              target as part of the current detour transaction.

DetourDetach()              - Detach a detour from a target function as part
                              of the current detour transaction.

DetourSetIgnoreTooSmall()   - Set the flag to determine if failure to detour
                              a target function that is too small for detouring
                              is sufficient error to cause abort of the current
                              detour transaction.

DetourTransactionAbort()    - Abort the current detour transaction.

DetourTransactionCommit()   - Attempt to commit the current detour transaction.

DetourTransactionCommitEx() - Attempt to commit the current transaction, if
                              transaction fails, retrieve error information.


5.2. APIS FOR FINDING TARGETS:
==============================
DetourFindFunction()        - Tries to retrieve a function pointer for a named
                              function through the dynamic linking export
                              tables for the named module and then, if that
                              fails, through debugging symbols if available.

DetourCodeFromPointer()     - Given a function pointer, returns a pointer to the
                              code implementing the function.  Skips over extra
                              code often inserted by linkers or compilers for
                              cross-DLL calls.


5.3. APIS FOR FINDING ACCESSING LOADED BINARIES AND PAYLOADS:
=============================================================
DetourEnumerateModules()    - Enumerates all of the PE binaries loaded into a
                              process.

DetourGetContainingModule() - Return the module containing a function.

DetourGetEntryPoint()       - Returns a pointer the entry point for a module.

DetourGetModuleSize()       - Returns the load size of a module.

DetourEnumerateExports()    - Enumerates all exports from a module.

DetourEnumerateImports()    - Enumerates all import dependencies of a module.

DetourFindPayload()         - Finds the address of the specified payload
                              within a module.

DetourFindPayloadEx()       - Finds the specified payload if it exists anywhere
                              in the process.

DetourGetSizeOfPayloads()   - Returns the size of all payloads within a
                              module.


5.4. APIS FOR MODIFYING BINARIES:
=================================
DetourBinaryOpen()          - Open a binary for in-memory update.

DetourBinaryEnumeratePayloads() - Enumerats all of the payloads in a binary.

DetourBinaryFindPayload()   - Finds a specific payload within a binary.

DetourBinarySetPayload()    - Attaches a payload to a binary.

DetourBinaryDeletePayload() - Removes a payload from a binary.

DetourBinaryPurgePayloads() - Removes all payloads from a binary.

DetourBinaryEditImports()   - Edits the import tables of a binary.

DetourBinaryResetImports()  - Removes all edits to the import tables of a
                              binary including any edits made by previous
                              programs using the Detours package.

DetourBinaryWrite()         - Writes the updated binary to a file.

DetourBinaryClose()         - Release the in-memory updates for a binary.

DetourBinaryBind()          - Binds the DLL imports for a named binary file.


5.5. APIS FOR INSERTING DLLS INTO PROCESSES:
============================================
DetourCreateProcessWithDll() - Creates a new process with the specified
                               DLL inserted into it.

DetourCreateProcessWithDllEx() - Creates a new process with a DLL inserted,
                                 selecting a 32-bit DLL for a 32-bit target
                                 process or a 64-bit DLL for a 64-bit target
                                 process.

DetourRestoreAfterWith()     - Restores the contents of the in memory import
                               table after a process was started with
                               DetourCreateProcessWithDll.

DetourIsHelperProcess()      - Determines if a DLL is being loaded by rundll32
                               in a helper process in order to make the
                               transition from a 32-bit process to a 64-bit
                               process or from a 64-bit process to a 32-bit
                               process.

DetourFinishHelperProcess()  - Completes the operations of a helper process.


6. COMPATIBILITY:
=================
All Detours functions are compatible with all versions of Microsoft Windows
Operating Systems with the supported service packs installed. This includes
Windows XP, Windows Server 2003, Windows Server 2003 R2, Windows Vista,
Windows Server 2008, Windows 7, Windows Server 2008 R2, and "Windows 8".


7. MANIFEST:
============
The Detours package consists of the Detours library source code and a number
of sample programs.  Descriptions of the sample programs can be found in
the help file.


8. NOTES:
=========
When writing detour functions, it is imperative that the binary-calling
convention of the detour and trampoline functions match exactly the
binary-calling convention of the target function.

In a few cases, when the sizeof() a return value is smaller than sizeof(int),
C or C++ compilers will generate non-compatible binary-calling conventions by
not widening the return value to an int as is customary for small return values.
The result is a syntactically-identical, but not binary-compatible, detour
function.  In most cases, the problem can be fixed be having the detour function
return a value widened to a sizeof(int) type.  Developers are urged to exercise
caution, and should insure that correct code is generated by their C or C++
compiler for detour functions with small return values.

When attaching a DLL to a binary with Detours DLL import APIs, the DLL must
export one procedure with export ordinal 1.  The exported procedure is not
called by the application, but it used as the import target.

Detours requires a compiler compatible with Visual C++.NET or later.


9. BUG REPORTS:
===============
Please send detailed bug reports to [email protected].  Submitted bug
reports may be used to fix bugs in future versions of the Detours package.
Please include the text "DETOURS BUG REPORT" in the subject line. Please
also include the first line of this README.TXT file containing the full
version description information.  The [email protected] email address
is not a product support line.