Bugs
How Do I Report Bugs?
Post your question to the Pinheads newsgroup. Provide as much information as possible so that we can reproduce the bug. What is the command line? What system are you running? What is the full name of the kit that you are using? On Linux*, do the following:
cat /etc/*release*
Problems that can be reproduced using the sample tools in the kit are the easiest for us to reproduce.
I Get an Error that Pin App Terminated Abnormally Due to Signal
First, you can find out what each signal means by typing man 7 signal. Next, you can debug the problem using GDB* as described in the user manual.
My IPOINT_AFTER for an RTN Is Not Being Called
IPOINT_AFTER for RTN is implemented by instrumenting the ret instruction. Pin finds the ret by scanning the body of the function. Sometimes a procedure doesn’t return but instead jumps to another procedure that does the exit. To reliably instrument after a function has exited, you can replace the function with a wrapper function and put the before and after actions in the wrapper function.
Building PinTools
Can I Create Threads in My PinTool?
Yes, Pin provides an interface that allows PinTools to create and manage their own threads. For example, the PIN_SpawnInternalThread() function can be used to create a new tool's internal thread in the current process. See the Pin Thread API section in the Pin manual for detailed descriptions of this and other threading functions provided by Pin.
Note PinTools cannot link against the pthreads library, nor can they use pthreads functions on Linux*. The reason for this is that using pthreads in the tool would interfere with the pthreads library linked to the application (they both try to take over the same signal handlers). Similarly, PinTools should not use the Win32* threading API (such as CreateThread()) on Windows because it does not allow distinguishing between threads created by the application and the tool's internal threads.
Features
Does Pin Handle Multithreaded Programs?
Yes.
Does Pin Instrument Shared Libraries?
Yes.
Does Pin Handle Self-Modifying Code?
Yes.
Does Pin Handle Programs with Threads and Signals?
Pin can instrument all code, including threads and signals. It provides precise exception state in handlers; a handler cannot detect that the program is instrumented by looking at the context of the interrupted thread.
Does Pin Change the Application Code and Data Addresses?
Pin allocates memory in the address space of the application, and that may cause application code, shared libraries, and dynamically allocated data to move.
Note Recent Linux* kernels intentionally move the location of stack and dynamically allocated data from run to run, even if you are not using Pin. For systems based on RedHat*, you can work around this by running Pin as follows:
$ setarch i386 pin -t pintool -- app
setarch i386 tells the kernel to disable Address Space Layout Randomization.
General
Which CPU Do I Need to Run Pin?
Pin will run on all Intel® 64 architectures. An IA-32 architecture needs the following features:
- C8 - CMPXCHG8B
- SSE2
- FXSR - FXSAVE/FXRSTOR
Pentium III® processors do not have SSE2. Pentium IV® processors can run Pin. You can check the capabilities of your processor on Linux with the following command:
cat /proc/cpuinfo
Does Pin Support Third-Party CPUs?
Pin has not been tested on systems with third-party processors. Therefore, incompatible or proprietary instructions in third-party processors may cause Pin to function incorrectly. Any attempt to instrument code not supported by Intel processors may lead to failures.
Which Version of My Operating System Do I Need to Run Pin?
Pin has been validated on the following platforms:
- Linux
- CentOS* 7.8 and 8.2
- Fedora* 31 and 32
- openSUSE* 15.2
- SLES 11.4, 12.5, and 15.2
- Ubuntu* 18.04, 19.10, and 20.04
- macOS*
- macOS 10.14 and 10.15.
- Pin supports SIP-enabled machines when running on nonsystem code.
- Windows*
- Windows® 10 19H2, 20H1, and 20H2.
- Windows Server* 2016 and 2019.
Can Pin Instrument a 32-bit Application Running on a 64-bit Operating System?
Yes. You need to build the 32-bit version of the tool. For details, see the user guide.
How Can I Run SPEC Programs with Pin?
In your SPEC configuration file (one of the files in $SPEC/config), add the following two lines:
submit=/my/path/to/pin/Bin/pin -t /my/pin/tool -- $command use_submit_for_speed=yes
Now SPEC automatically runs Pin with benchmarks. Note that you need the full path name for your Pin and Pintool binaries.
Is Pin Open Source?
The instrumentation engine is not open source, but the example tools are open source. They have a Berkeley Software Distribution (BSD)-style license and can be redistributed in any form as long as you keep the copyright notice.
I Used Pin for My Latest Paper. What Citation Should I Include?
Chi-Keung Luk, Robert Cohn, Robert Muth, Harish Patil, Artur Klauser, Geoff Lowney, Steven Wallace, Vijay Janapa Reddi, Kim Hazelwood. "Pin: Building Customized Program Analysis Tools with Dynamic Instrumentation," Programming Language Design and Implementation (PLDI), Chicago, IL, June 2005, pp. 190-200.
Resources
Pin—A Dynamic Binary Instrumentation Tool
Pin—A Binary Instrumentation Tool—Downloads
pinheads@groups.io
Pin—A Binary Instrumentation Tool—Papers
Intel® X86 Encoder Decoder Software Library
Intel® Software Development Emulator
Pin—A Binary Instrumentation Tool—PinPoints
Program Record/Replay Toolkit
DrDebug: Deterministic Replay-based Debugging with Pin