Pin: Building Customized Program Analysis Tools with Dynamic Instrumentation Chi-Keung Luk Robert Cohn Robert Muth Harish Patil Artur Klauser Geoff Lowney Steven Wallace Vijay Janapa Reddi y Kim Hazelwood Intel Corporation yUniversity of Colorado Website httproguecoloradoeduPin Email pinprojectintelcom Abstract 1. Introduction Robust and powerful software instrumentation tools are essential As software complexity increases, instrumentation—a technique for program analysis tasks such as profiling, performance evalu- for inserting extra code into an application to observe its behavior— ation, and bug detection. To meet this need, we have developed is becoming more important. Instrumentation can be performed at a new instrumentation system called Pin. Our goals are to pro- various stages: in the source code, at compile time, post link time, vide easy-to-use, portable, transparent, and efficient instrumenta- or at run time. Pin is a software system that performs run-time tion. Instrumentation tools (called Pintools) are written in C/C++ binary instrumentation of Linux applications. using Pin’s rich API. Pin follows the model of ATOM, allowing the The goal of Pin is to provide an instrumentation platform for tool writer to analyze an application at the instruction level with- building a wide variety of program analysis tools for multiple archi- out the need for detailed knowledge of the underlying instruction tectures. As a result, the design emphasizes ease-of-use, portabil- set. The API is designed to be architecture independent whenever ity, transparency, efficiency, and robustness. This paper describes possible, making Pintools source compatible across different archi- the design of Pin and shows how it provides these features. tectures. However, a Pintool can access architecture-specific details Pin’s instrumentation is easy to use. Its user model is similar when necessary. Instrumentation with Pin is mostly transparent as to the popular ATOM [30] API, which allows a tool to insert calls the application and Pintool observe the application’s original, unin- to instrumentation at arbitrary locations in the executable. Users strumented behavior. Pin uses dynamic compilation to instrument do not need to manually inline instructions or save and restore executables while they are running. For efficiency, Pin uses sev- state. Pin provides a rich API that abstracts away the underlying eral techniques, including inlining, register re-allocation, liveness instruction set idiosyncrasies, making it possible to write portable analysis, and instruction scheduling to optimize instrumentation. instrumentation tools. The Pin distribution includes many sample This fully automated approach delivers significantly better instru- architecture-independent Pintools including profilers, cache simu- mentation performance than similar tools. For example, Pin is 3.3x lators, trace analyzers, and memory bug checkers. The API also faster than Valgrind and 2x faster than DynamoRIO for basic-block allows access to architecture-specific information. counting. To illustrate Pin’s versatility, we describe two Pintools Pin provides efficient instrumentation by using a just-in-time in daily use to analyze production software. Pin is publicly avail- (JIT) compiler to insert and optimize code. In addition to some able for Linux platforms on four architectures: IA32 (32-bit x86), standard techniques for dynamic instrumentation systems includ- EM64T (64-bit x86), ItaniumR , and ARM. In the ten months since ing code caching and trace linking, Pin implements register re- Pin 2 was released in July 2004, there have been over 3000 down- allocation, inlining, liveness analysis, and instruction scheduling to loads from its website. optimize jitted code. This fully automated approach distinguishes Pin from most other instrumentation tools which require the user’s Categories and Subject Descriptors D.2.5 [Software Engineer- assistance to boost performance. For example, Valgrind [22] re- ing]: Testing and Debugging-code inspections and walk-throughs, lies on the tool writer to insert special operations in their in- debugging aids, tracing; D.3.4 [Programming Languages]: Processors- termediate representation in order to perform inlining; similarly compilers, incremental compilers DynamoRIO [6] requires the tool writer to manually inline and save/restore application registers. General Terms Languages, Performance, Experimentation Another feature that makes Pin efficient is process attaching Keywords Instrumentation, program analysis tools, dynamic com- and detaching. Like a debugger, Pin can attach to a process, in- pilation strument it, collect profiles, and eventually detach. The application only incurs instrumentation overhead during the period that Pin is attached. The ability to attach and detach is a necessity for the in- strumentation of large, long-running applications. Pin’s JIT-based instrumentation defers code discovery until run time, allowing Pin to be more robust than systems that use static Permission to make digital or hard copies of all or part of this work for personal or instrumentation or code patching. Pin can seamlessly handle mixed classroom use is granted without fee provided that copies are not made or distributed for profit or commercial advantage and that copies bear this notice and the full citation code and data, variable-length instructions, statically unknown in- on the first page. To copy otherwise, to republish, to post on servers or to redistribute direct jump targets, dynamically loaded libraries, and dynamically to lists, requires prior specific permission and/or a fee. generated code. PLDI’05 June 12–15,2005,Chicago,Illinois,USA. Pin preserves the original application behavior by providing in- Copyright c 2005 ACM 1-59593-080-9/05/0006 $5.00. strumentation transparency. The application observes the same ad- dresses (both instruction and data) and same values (both register trace and memory) as it would in an uninstrumented execution. Trans- FILE parency makes the information collected by instrumentation more Print a memory write record RecordMemWriteVOID ip VOID addr UINT size relevant and is also necessary for correctness. For example, some VOID W p dn ip addr size applications unintentionally access data beyond the top of stack, so fprintftracep Pin and the instrumentation do not modify the application stack. Pin’s first generation, Pin 0, supports ItaniumR . The recently- Called for every instruction released second generation, Pin 2, extends the support to four1 InstructionINS ins VOID v architectures: IA32 (32-bit x86) [14], EM64T (64-bit x86) [15], VOID instruments writes using a predicated call ItaniumR [13], and ARM [16]. Pin 2 for Itanium R is still under ie the call happens iff the store is development. actually executed Pin has been gaining popularity both inside and outside of Intel, if INSIsMemoryWriteins with more than 3000 downloads since Pin 2 was first released INSInsertPredicatedCal l IPOINTBEFORE AFUNPTRRecordMemWrite in July 2004. This paper presents an in-depth description of Pin, ins IARGMEMORYWRITEEA and is organized as follows. We first give an overview of Pin’s IARGINSTPTR IARGEND instrumentation capability in Section 2. We follow by discussing IARGMEMORYWRITESIZE design and implementation issues in Section 3. We then evaluate in Section 4 the performance of Pin’s instrumentation and compare it mainint argc char argv against other tools. In Section 5, we discuss two sample Pintools int argv used in practice. Finally, we relate Pin to other work in Section 6 PINInitargc fopenatraceout w and conclude in Section 7. trace INSAddInstrumentFunctio nI nstr uct ion PINStartProgram Never returns 2. Instrumentation with Pin return The Pin API makes it possible to observe all the architectural state of a process, such as the contents of registers, memory, and Figure 1. A Pintool for tracing memory writes. control flow. It uses a model similar to ATOM [30], where the user adds procedures (as known as analysis routines in ATOM’s notion) InsertPredicatedCall RecordMemWrite to the application process, and writes instrumentation routines to INS ensures that is determine where to place calls to analysis routines. The arguments invoked only if the memory instruction is predicated true. to analysis routines can be architectural state or constants. Pin Note that the same source code works on all architectures. The also provides a limited ability to alter the program behavior by user does not need to know about the bundling of instructions on allowing an analysis routine to overwrite application registers and Itanium, the various addressing modes on each architecture, the application memory. different forms of predication supported by Itanium and ARM, x86 Instrumentation is performed by a just-in-time (JIT) compiler. string instructions that can write a variable-size memory area, or The input to this compiler is not bytecode, however, but a native ex- x86 instructions like push that can implicitly write memory. ecutable. Pin intercepts the execution of the first instruction of the Pin provides a comprehensive API for inspection and instru- executable and generates (“compiles”) new code for the straight- mentation. In this particular example, instrumentation is done one line code sequence starting at this instruction. It then transfers con- instruction at a time. It is also possible to inspect whole traces, trol to the generated sequence. The generated code sequence is al- procedures, and images when doing instrumentation. The