Pin

 
Home
News
Downloads
Learn Pin
FAQ
Newsgroup

Wiki

User Contrib
Papers

Related

PinPoints
      

Frequently-Asked Questions

A) Bugs

How do I report bugs?

Please post to the Pinheads Newsgroup. Provide as much information as possible so that we can reproduce the bug. What is the command line? What is the system you are running on. On Linux do:

cat /etc/*release*
uname -a

What is the full name of the kit that you are using? 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.

I get this message: ./pin: error while loading shared libraries: cannot restore segment prot after reloc: Permission denied

This is SELinux. Try changing the context of the pin binary in the Bin directory:

chcon -t textrel_shlib_t Bin/pin

My IPOINT_AFTER for a 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 which does the exit. To reliably instrument after a function has exited. You can replace the function with a wrapper function, and put the before/after actions in the wrapper function.

B) Building PinTools

Can I statically link my pintool?

On linux, edit makefile.gnu.config:

# Select static or dynamic linking for tool
# only applies to unix
#PIN_DYNAMIC = -static
PIN_DYNAMIC = -ldl

On some Linux installations (primarily Mandrake) the static versions of the C++ and math libraries are not included by default. You will get the message:

/usr/bin/ld: cannot find -lstdc++

Installing the following RPMs will fix this issue: libstdc++5-static-devel and glibc-static-devel. Pin links to these two libraries statically, therefore they must be installed.

Can I statically link pin?

On linux:

cd Bin
make pin.static

Can I link my PinTool PIE to avoid address conflicts?

On linux:

make PIN_PIE=1 ...

Can I create threads in my PinTool?

PinTools can NOT link against the pthreads library nor can they use pthreads functions. The reason for this is that using pthreads in the tool would interfere with the pthreads library linked into the application. (E.g. they both try to take over the same signal handlers.) If you want to create a private thread in the tool, you can do this on Linux by calling the clone() system call directly so long as you create the thread with NO termination signal. To synchronize PinTool threads, use PIN_LOCK (not pthread_mutex_lock, etc.) The private thread should take measures to ensure it does not receive the application's signals. For example, do NOT use CLONE_THREAD in the clone() call, or block all signals on the private thread. There is currently no mechanism to create a private PinTool thread on Windows.

C) Features

Does Pin handle multi-threaded programs

Yes.

Does Pin instrument shared libraries?

Yes.

Does Pin handle self-modifying code?

Yes.

Does Pin handle programs with threads and signals?

Pin is able to 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 shared libraries and dynamically allocated data to move. If you use the option -separate_memory, pin will try to allocate its data at an address that is not normally used and will be less likely to perturb the application. On linux, you can statically link pin and tool. Eliminating pin and tool shared libraries will reduce the chance that pin alters the memory layout of an application.

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. On RedHat-based systems you can workaround this by running Pin as follows:

$ setarch i386 pin -t pintool -- app
setarch i386 tells the kernel to disable Address Space Layout Randomization.

Alternatively, you can permanently disable ASLR on your host machine by following the instructions listed here

D) General

What version of CPU do I need to run Pin?

Pin will run on all IA64 and Intel64 processors. A IA32 processor 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

What version of OS do I need to run Pin?

We believe pin works on these platforms:

  • Linux
    • All distributions. See the user guide section about linux libraries if you are using probe mode or are getting warnings about missing libraries.
  • Windows
    • Windows XP
    • Windows Server 2003
  • MacOs
    • Tiger

There are multiple kits for linux, how do I know which one to use?

The kit you use depends on the compiler you will use to compile the pintool. Check the compiler version number:

[root@vs-lin32-8 Virtual Machines]# /usr/bin/g++ -v 
Reading specs from /usr/lib/gcc/i386-redhat-linux/3.4.4/specs

And download the kit with the highest compiler version number for your compiler. For the example above, you would use the gcc3.4 kit.

Can pin instrument a 32 bit application running on a 64 bit OS?

Yes. You will have to build the 32 bit version of the tool. See the user manual.

How can I run spec programs with Pin?

In your SPEC config 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 will automatically run Pin with whatever benchmarks it runs. 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 BSD-style license, and can be redistributed in any form, as long as you keep the copyright notice.

What is the Pin license?

The license for Pin is included in the kit in a file called LICENSE and can be previewed here. The Pin kit includes some separately licensed software and its license is in a file called ExtLib/EXTLICENSE and can be previewed here.

The license for the Pin kit allows redistribution and does not restrict use. When you use the Pin kit to build a pintool, it will link statically with libelf and libdwarf. The libraries were written by a third party. For the convenience of pintool developers, we include these libraries in the Pin kit. They have a LGPL license. If you want to distribute a pintool, you are responsible for ensuring that you comply with the LGPL.

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.