
PIN 2.5 Release Notes
=====================


Pin is a tool for the instrumentation of programs. It supports Linux*
executables for IA-32, Intel(R) 64, and IA-64 architectures. Pin
supports Windows* executables for the IA-32 and Intel(R) 64
architectures.

For license information, see LICENSE and ExtLibs/LICENSE

For information on how to use Pin, read the manual in
Doc/html/index.html or Doc/pin-user.{pdf,ps}.

Send questions and bug reports see
http://tech.groups.yahoo.com/group/pinheads/


Example usage
=============

This example applies to the Intel(R) 64 architecture.  For the IA-32 architecture, 
use "obj-ia32" instead of "obj-intel64".  For the IA-64 architecture, use "obj-ia64"
instead of "obj-intel64".

To build and run a sample tool on Linux*:

    cd source/tools/SimpleExamples
    make opcodemix.test
    ../../../pin -t obj-intel64/opcodemix.so -- /bin/ls

    This will instrument and run /bin/ls, the output for this tool is in
    opcodemix.out.

To build and run a sample tool on Windows*:

    cd source\tools\SimpleExamples
    ..\nmake opcodemix.dll
    ..\..\..\pin.bat -t obj-intel64\opcodemix.dll -- cmd /C dir
 
    This will instrument and run cmd /C dir, the output for this tool is in
    opcodemix.out.


Restrictions
============

   o The version of the compiler you use to build a tool must be compatible
     with the pin kit. On Linux*, gcc 3.4 requires a gcc3.4 kit, and gcc 4.0 
     and later requires a gcc4.0 kit. 
     On Windows*, pin supports tools built with the Microsoft* Visual C++ 
     compiler* 8.0. Such tools require a VC8 kit.  This only applies to the 
     compiler used to build a tool; the application can use any compiler.

   o Pin on Windows* requires dbghelp.dll version 6.8.4.0.  This DLL is not 
     distributed with the kit. Downloading instructions can be found in the 
     "Additional Information for Using Pin on Windows*" section.

   o There is a known problem of using pin on systems protected by the
     "McAfee Host Intrusion Prevention"* antivirus software.  See the 
     "Additional Information for Using Pin on Windows*" section for more
     information.


Pin performs memory allocations in the application's address space.  
As a result, memory allocations performed by the application can fail. 
For example, some applications use the SmartHeap utility which could 
perform huge memory allocations. Using the "-separate_memory 1" switch 
may be helpful in some of these cases.
On Windows*, using Microsoft* Visual C++ compiler* 8.0 "editbin"* 
utility to rebase pinvm.dll and the pintool preferred loading addresses
might be helpful as well, for example:
   editbin /REBASE:BASE=0x57000000 pinvm.dll
   editbin /REBASE:BASE=0x58000000 <pintool>
is helpful in some Windows applications


Recent Changes
=========================
   o Pin now supports applications with the self-modifying code (SMC).

   o A combined kit is now provided for IA-32 and Intel(R) 64 architecture 
     support.

   o The directory structure in the kit has changed.  The Pin tools can be 
     found under "source/tools".  The Pin executable can be found under the 
     appropriate architecture name: "ia32/bin" for the IA-32 architecture, 
     "intel64/bin" for the Intel(R) 64 architecture, and "ia64/bin" for the 
     IA-64 architecture.

   o When the tools are built, the shared library or DLL will be found in an 
     architecture-specific subdirectory in the tool directory.  The names of
     these subdirectories are "obj-ia32", "obj-intel64" and "obj-ia64". 
     For example, when SimpleExamples/opcodemix.cpp is built for an IA-32 
     architecture, its shared library will be found in 
     SimpleExamples/obj-ia32/opcodemix.so.
     
   o Tools that read application memory may want to use PIN_SafeCopy(),
     especially on Windows.  Pin on Windows replaces a few bytes in the
     application's TEB structure when the tool's analysis code is
     running.  If a tool directly reads the application's memory, it
     may see the modified TEB values rather than the original ones.
     Use PIN_SafeCopy() to avoid this.

   o Pin will accept either dashes or underscores in knob names where
     underscores are normally required. If you declare a knob with dashes,
     then you must use dashes when you specify it.

   o Use IARG_CALL_ORDER to control the order of analysis calls
   
   o Pin tools are now shared libraries on Linux*.  See the User's Guide for new 
     information on how to debug a Pin tool.

   o Linux* pin allows more control over how to find its libraries. See
     "Libraries for Linux*" in the User's Guide.

   o -pin_runtime is deprecated. See "Libraries for Linux*" in the user
     manual. To continue to use -pin_runtime, you must invoke pinbin
     directly.

   o Modeling of system calls in Windows* has been changed. System call 
     instructions are considered as potentially changing control flow even if 
     they fall through to the next instruction.  A tool that monitors control 
     flow of system calls should register for for the newly defined 
     SYSCALL_ENTRY_CALLBACK and SYSCALL_EXIT_CALLBACK notifications using the 
     PIN_AddSyscallEntryFunction() and PIN_AddSyscallExitFunction() APIs.
   
   o The CONTEXT_CHANGE_CALLBACK notification has been implemented for all types 
     of Windows* interruptions: APC, EXCEPTION and CALLBACK. 
   
   o Pin API PIN_UndecorateSymbolName() was added to provide undecoration of C++ 
     and C decorated symbol names generated by Microsoft* and Intel Windows* compilers.

   o PIN_CallApplicationFunction() was added to call an application routine from a 
     replacement function.  PIN_CallApplicationFunction() restores the application 
     context before calling the application routine, and then restores the tools 
     context before returning control to the  replacement function. 

   o "-probe" is no longer needed on the command line in probe mode.  
 

 
Additional information for PinTool writers
============================================

   o Due to a compatibility issue between operating systems pin does *not*
     provide support for registering atexit functions inside pintools
     (which means that the behavior of a pintool that does so is
     undefined). If you need such functionality, please register a Fini
     function.

   o If you prefer using a statically linked pin binary, cd Bin; make pin.static


   o To invoke the help message from pin, you MUST specify some
     executable image after two dashes, even pin itself:
            pin -help -- pin
        


Additional information for using Pin on Windows*
===============================================

General issues
        
        Pin tools are DLLs on Windows*.
                  
        Avoid using alertable (interruptable) Windows* system calls in 
        tools.  The SleepEx, SignalObjectAndWait, WaitForSingleObjectEx,
        MsgWaitForMultipleObjectsEx, and WaitForMultipleObjectsEx 
        functions can be interrupted by APCs and callbacks intended for
        the application. This violates normal behavior of the application
        and pin assumptions. When this violation is detected, pin exits
        with an assert message.
        
        Pin provides transparent support for exceptions in the application,
        but prohibits using exceptions in the tool. If you need to assert
        some condition, use the ASSERT() macro defined by pin instead of 
        the standard C assert().
        
        The Image API does not work for gcc-compiled applications.
        
        There is a known problem of using pin on systems protected by the
        "McAfee Host Intrusion Prevention"* antivirus software. We did not
        test coexistance of pin with other antivirus products that perform 
        run-time execution monitoring.
        
        Pin on Windows* uses dbghelp.dll by Microsoft* to provide symbolic 
        information. This DLL is not distributed with the kit. 
        In order to get support for symbolic information in Pin, you have 
        to download the "Debugging Tools For Windows*" package, version 6.8.4.0 
        from http://www.microsoft.com/whdc/devtools/debugging/default.mspx.
	Use "Debugging Tools For Windows* 32-bit Version" for IA-32 architectures and
	"Debugging Tools For Windows* - Native X64" for Intel(R) 64 architectures.
	Distribution of the debugging tools is provided in .msi format which must be
	installed to extract a single file.  Copy dbghelp.dll from the package into 
        "ia32\bin" or "intel64\bin" directory of the Pin kit. This directory should 
	already contain pin.exe and pinvm.dll files.
        
Supported configurations
        
        Windows XP*, Windows Server* 2003, Windows Vista*, Windows Server* 2008
        on Intel(R) IA-32 and Intel(R) 64 architecture.
        
    

Disclaimer and Legal Information
================================

The information in this document is subject to change without notice and
Intel Corporation assumes no responsibility or liability for any
errors or inaccuracies that may appear in this document or any
software that may be provided in association with this document. This
document and the software described in it are furnished under license
and may only be used or copied in accordance with the terms of the
license. No license, express or implied, by estoppel or otherwise, to
any intellectual property rights is granted by this document. The
information in this document is provided in connection with Intel
products and should not be construed as a commitment by Intel
Corporation.

EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH
PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS
ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL
PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A
PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT,
COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not
intended for use in medical, life saving, life sustaining, critical
control or safety systems, or in nuclear facility applications.

Designers must not rely on the absence or characteristics of any
features or instructions marked "reserved" or "undefined." Intel
reserves these for future definition and shall have no responsibility
whatsoever for conflicts or incompatibilities arising from future
changes to them.

The software described in this document may contain software defects
which may cause the product to deviate from published
specifications. Current characterized software defects are available
on request.

Intel, the Intel logo, Intel SpeedStep, Intel NetBurst, Intel
NetStructure, MMX, Intel386, Intel486, Celeron, Intel Centrino, Intel
Xeon, Intel XScale, Itanium, Pentium, Pentium II Xeon, Pentium III
Xeon, Pentium M, and VTune are trademarks or registered trademarks of
Intel Corporation or its subsidiaries in the United States and other
countries.

* Other names and brands may be claimed as the property of others. 

Copyright  2004-2008, Intel Corporation. 

