MSIX-PackageSupportFramework/Detours

Microsoft Research Detours Package

Internal Version 3.0 Build_343



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 scenarios that mix both 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 by 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.