
Pin 2.7 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 dir 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.11.1.404.  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.

   o 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.

   o Pin will run on all Intel IA-64 and Intel 64 architectures. An Intel IA-32 
     architecture needs the following features:
         C8 - CMPXCHG8B 
         SSE2
         CMOV 
         FXSR - FXSAVE/FXRSTOR 
     Pentium(R) III processors do not have SSE2. Pentium(R) 4 processors can run Pin. 
     You can check the capabilities of your processor on Linux with the following 
     command:
         cat /proc/cpuinfo


New Features in Pin 2.7
=========================
   o PIN_UndecorateSymbolName() is supported now on Linux and FreeBSD. Pin tools should be statically
     linked with libiberty.a library, which became a part of Pin package like libelf and libdwarf.

Recent Changes
=========================
   o Internal exception handling support was added. The new supported APIs are PIN_AddInternalExceptionHandler(),
     PIN_TryStart(), PIN_TryEnd(), PIN_SetPhysicalContextReg(), PIN_GetPhysicalContextReg(), 
     PIN_SetPhysicalContextFPState(), PIN_GetPhysicalContextFPState(). These APIs allow the user to be notified
     upon internal exception (generated by pin / tool) and handle it. If the exception was generated unintentionally,
     it may indicate about a bug in pin / tool.
     
   o A new version of dbghelp is needed on Windows*.  In order to get support for 
     symbolic information in Pin, you have to download the "Debugging Tools For Windows*" 
     package, version 6.11.1.404 from 
     http://www.microsoft.com/whdc/devtools/debugging/default.mspx.

   o On Windows, Pintools must be compiled with /D_SECURE_SCL=0.  Please see the User's
     Guide for more information on mandatory compiler and linker swtiches.

   o Pin on Windows* now supports "early injection". The injection occurs right after 
     kernel32.dll is loaded and initialized. This allows Pin to instrument 
     DllMain(fdwReason=DLL_PROCESS_ATTACH) of the rest of the implicitly loaded DLLs.
     The injection occurs when the application's loader is active and the system's loader 
     lock is acquired.
          
   o Pin on Windows* in Probe mode supports attach to a running process (using -pid 
     command line switch).
     
   o Pin on Windows* in Probe mode supports lite detach & reattach. 
     The new supported APIs are: PIN_AddDetachFunctionProbed(), PIN_DetachProbed(), 
     PIN_AttachProbed(). The -detach_reattach command line switch must be specified in 
     order to enable the feature.
     
   o In order to perform "early injection", attach, lite detach & reattach, Pin on Windows* 
     uses the debugging APIs.  Therefore, you must attach with a debugger *after* the Pin 
     injection takes place (In particular, don't enable Windbg* "Debug child processes also" 
     button). The -debug_instrumented_processes command line switch can be used 
     in order to get a message that debugger attach can be done.
     
   o Pin now supports applications with 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 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 Support for a new buffering API has been added for IA-32 and Intel(R) 64 architectures.
     This allows a tool to write data to a buffer for processing.  See PIN_DefineTraceBuffer() 
     for more information.

   o The treatment of REP prefixed instructions in the IA-32 and Intel(R) 64 architectures has
     been changed. REP prefixed instructions are now treated as implicit loops, with
     IPOINT_BEFORE and IPOINT_AFTER instrumentation called before each iteration. This will
     affect instruction counts. PinTools/InstLib/icount.H shows how to collect an instruction
     count which only counts a REP prefixed instruction once, as Pin used to do.

   o The Pin User Manual now includes a section on optimizing the treatment of REP prefixed
     instructions.

   o As a result of the changes to REP prefixed instruction handling,
     VARIABLE_MEMORY_REFERENCE_SIZE has been deprecated. No instructions now have a
     variable memory reference size, so code which expected that can probably be removed from
     your tools.

   o On the IA-32 and Intel(R) 64 architectures CMOVcc, FCMOVcc and REP prefixed instructions
     are now treated as predicated.

   o Pin tools which use the REG_INST_Gn registers should consider using the new function
     PIN_ClaimToolRegister() to allocate them to avoid conflicts if you want to integrate
     multiple tools.
 
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 coexistence of pin with other antivirus products that perform 
        run-time execution monitoring.
        
        Pin may not instrument applications that restrict loading of DLLs from
        non-local drives if Pin and / or Pin tool binaries are located
        on a network drive. To workaround this problem, install all Pin and
        Pin tool binaries on a local drive.
        
        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.11.1.404
        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, Itanium, and Pentium are trademarks or registered trademarks of
Intel Corporation or its subsidiaries in the United States and other
countries.

Microsoft, Windows, and the Windows logo are trademarks, or registered trademarks
of Microsoft Corporation in the United States and/or other countries.

Java and all Java based trademarks and logos are trademarks or registered trademarks
of Sun Microsystems, Inc. in the U.S. and other countries.

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

Copyright(c) 2004-2009, Intel Corporation. All rights reserved. 

Intel Corporation, 2200 Mission College Blvd., 
Santa Clara, CA 95052-8119, USA.
