PIN 2.6 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.9.3.113. 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 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.9.3.113 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-2009, Intel Corporation.