Pin 2.12 Release Notes

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

For license information, see LICENSE and <arch>/lib-ext/EXTLICENSE

For information on how to use Pin, read the manual in doc/html/index.html.

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

To build and run a sample tool on Linux*:

cd source/tools/SimpleExamples
make obj-intel64/opcodemix.so
../../../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
make opcodemix.dll
..\..\..\pin.exe -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.

Refer to the Examples section in the Pin User Guide for more usage examples.

Restrictions

o Added support for Android. See the "Additional Information for Using Pin on Android" section for more information.

o Added preliminary support for Mac OSX. See the "Additional Information for Using Pin on OSX*" section for more information.

o Pin is no longer supported on Linux distributions with old kernel version. See the "Additional Information for Using Pin on Linux*" section for more information.

o The version of the compiler you use to build a tool must be compatible with the pin kit. On Linux*, you can use gcc 3.4 or any later version. Note, however, that you cannot use gcc versions 4.5 or newer to compile Probe mode tools, since these versions create files with a new OS ABI version which is not compatible with the pin kit. You can also use Intel(R) C++ compiler. On Windows*, pin supports tools built with Intel(R) C++ compiler 10.1 and 11.1. It also supports tools built with the Microsoft* Visual Studio C++ compiler* version 14.0 (Visual Studio 2005, aka VC8), 15.0 (Visual Studio 2008, aka VC9) and 16.0 (Visual Studio 2010, aka VC10). Such tools require the VC8, VC9 or VC10 kit, respectively. 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 distributed with the kit.

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 There is a known problem of using pin on Linux systems that prevent the use of ptrace attach using the sysctl /proc/sys/kernel/yama/ptrace_scope. See the "Additional information for using Pin on Linux*" 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* "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 There are known problems using Pin with the Google Chrome web browser: On Windows, Pin may fail to attach to a running Chrome process. On Linux, Pin may crash when instrumenting Chrome. A possible workaround is to launch Chrome with the "--no-sandbox" command line switch.

o Pin will run on all 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

o Pin has not been tested on systems with non-Intel processors. Therefore, incompatible or proprietary instructions in non-Intel processors may cause Pin to function incorrectly. Any attempt to instrument code not supported by Intel processors may lead to failures.

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 To invoke the help message from pin on Windows*, you MUST specify some executable image after two dashes, even pin itself: pin -help -- pin

o Some APIs from older versions of Pin have been deprecated and replaced by more powerful, or simpler, interfaces in the current version of Pin. Usage of deprecated APIs in Pin Tools will trigger a compilation warning. You can #define PIN_DEPRECATED_WARNINGS=0 to disable these warnings. Please refer to the Pin Deprecated API section in the Pin User Guide for a list of the deprecated APIs and their replacements.

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.
    

Supported configurations

    Windows XP*, Windows Server* 2003, Windows Vista*, Windows Server* 2008
    and Windows 7* (except for UMS applications),   on Intel(R) IA-32 and
    Intel(R) 64 architecture.

Additional information for using Pin on Linux*

General issues

 There is a known problem of using Pin on Linux systems that prevent the use
 of ptrace attach via the sysctl /proc/sys/kernel/yama/ptrace_scope.
 In this case Pin is not able to use its default (parent) injection mode.
 To resolve this, either use the "-injection child" option or 
 set the kernel/yama/ptrace_scope sysctl to 0. 
 For more information regarding child injection, refer to the Injection 
 section in the Pin User Manual.
 
    

Supported configurations:

    New Pin features (such as attach/detach) and bug fixes have been found to work
    incorrectly on some old Linux OSs due to bugs in the Linux kernel fixed in more
    modern kernel versions. Therefore, pin is no longer supported on Linux distributions
    with kernel 2.4 such as RedHat EL3.

Linux tested configurations:

    +---------------------------------+----+-------+
    | OS                              |IA32|Intel64|
    +---------------------------------+----+-------+
    | Wind River Linux 4.0            | +  |       |
    | Red Hat Enterprise Linux 4      | +  |   +   |
    | Red Hat Enterprise Linux 5      | +  |   +   |
    | Red Hat Enterprise Linux 6      |    |   +   |
    | Red Hat Fedora 14               |    |   +   |
    | Red Hat Fedora 15               |    |   +   |
    | Red Hat Fedora 16               | +  |   +   |
    | Red Hat Fedora 17               |    |   +   |
    | SuSE Linux Enterprise Server 10 |    |   +   |
    | SuSE Linux Enterprise Server 11 | +  |   +   |
    | openSUSE 12.1                   | +  |       |
    | Ubuntu 10.04                    |    |   +   |
    | Ubuntu 12.04                    | +  |   +   |
    +---------------------------------+----+-------+
    

Additional information for using Pin on OSX*

THIS IS A TECH PREVIEW RELEASE

General issues

    o Probe mode is not yet supported on OSX.
    o There are known issues with the XPC mechanism added in OSX Lion.
    o Pin require the privileged task_for_pid system API, and is signed by
      an official Intel(R) certificate. When using pin through the system
      terminal, a security popup may appea