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 code injection mechanism
could fail silently without any diagnostic information and was susceptible
to changes in the underlying loader in Windows.  The new implementation
modifies the DLL import table in the target process to cause the the
Windows loader to load the DLL as if it where listed in the program's
import table.  As a result, the code is much more robust and never
fails silently.


4.7. REMOVED THE DETOURCONTINUEPROCESSWITHDLL API:
=====================================================
The DetourContinueProcessWithDll API has been removed and is no longer
supported.  It was removed because there is no supported or reliable
mechanism to inject a DLL into a running process.


4.8. ADDED DETOURCOPYPAYLOADTOPROCESS API:
==========================================
The DetourCopyPayloadToProcess API copies a block of memory directly into
a payload in a target process.  DetourCopyPayloadToProcess is particular
useful for copying information from a parent process to a child process
created using the DetourCreateProcessWithDll API.


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 traget 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()     - Give 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.

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.

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

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.
DetourRestoreAfterWith()     - Restores the contents in memory import table
                               after a process was started with
                               DetourCreateProcessWithDll.
DetourGetDetouredMarker()    - Returns the handle of the detoured.dll
                               DLL loaded to mark this process as detoured.

6. COMPATIBILITY:
=================
All Detours functions are compatible with all versions of Windows NT,
Windows 2000, Windows XP, and Windows Server 2003.

Detours does not support Windows 95, Windows 98, or Windows ME.


7. MANIFEST:
============
The Detours package current consists of the Detours library (with or without
source code) and a number of sample programs.  Descriptions of the sample
programs can be found in samples\README.TXT


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 detours@microsoft.com.  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 detours@microsoft.com email address
is not a product support line.


10. COMMERCIAL LICENSE REQUESTS:
================================
Detours is available under both a restricted non-commerial/research license
and under a commerical license.  To inquiry about acquiring a commercial
license to the Detours Package, send email to Microsoft's Intellectual
Property and Licensing Group at iplg@microsoft.com.  Please include the text
"DETOURS LICENSE REQUEST" in the subject line.

