- 1 - Copyright © 2006 Intel Corporation. All Rights Reserved. Using the Pin Instrumentation Tool for Computer Architecture Research Aamer Jaleel, Chi-Keung

- 1 -

Copyright © 2006 Intel Corporation. All Rights Reserved.

Using the Pin Instrumentation Tool Using the Pin Instrumentation Tool for Computer Architecture Researchfor Computer Architecture Research

Aamer Jaleel, Chi-Keung Luk, Bobbie Manne, Harish Aamer Jaleel, Chi-Keung Luk, Bobbie Manne, Harish PatilPatil

IntelIntel®® Corporation Corporation

June 17, 2006June 17, 2006

- 2 -


Introduction to PinIntroduction to Pin

CK LukCK Luk

- 3 -


Tutorial AgendaTutorial Agenda

1:30 – 2:15 Introduction to Pin

2:15 – 3:45Micro-architecture Studies Using Pin: Branch Predictors,Caches, & Simple Timing Models

2:45 – 3:30 Techniques for Speeding Up Pin Based Simulation

4:00 – 4:30 Performance Optimizations of Pin Tools

4:30 – 5:00 Fault Analysis Using Pin

3:30 – 4:00 Break

- 4 -


What is Instrumentation?What is Instrumentation?

A technique that inserts extra code into A technique that inserts extra code into a program to collect runtime a program to collect runtime informationinformation

Instrumentation approaches:Instrumentation approaches:

– Source instrumentation:Source instrumentation:• Instrument source programs

– Binary instrumentationBinary instrumentation::• Instrument executables directly

our approach

- 5 -


Example: Instruction CountExample: Instruction Count

subsub $0xff, %edx$0xff, %edx

cmpcmp %esi, %edx%esi, %edx

jlejle <L1><L1>

movmov $0x1, %edi$0x1, %edi

addadd $0x10, %eax$0x10, %eax

counter++;

counter++;

counter++;

counter++;

counter++;

- 6 -


Example: Instruction TraceExample: Instruction Trace



jlejle <L1><L1>



Print(ip);

Print(ip);

Print(ip);

Print(ip);

Print(ip);

- 7 -


Instrumentation vs. SimulationInstrumentation vs. Simulation

Advantages of Simulation:Advantages of Simulation:

– Detailed modeling of processorsDetailed modeling of processors

– Can model non-existing hardwareCan model non-existing hardware

Advantages of Instrumentation:Advantages of Instrumentation:

– Easy to prototypeEasy to prototype

– Fast to run (allowing complete runs)Fast to run (allowing complete runs)

- 8 -


How is Instrumentation used in How is Instrumentation used in Computer Architecture?Computer Architecture?

Trace GenerationTrace Generation

Branch Predictor and Cache ModelingBranch Predictor and Cache Modeling

Fault Tolerance StudyFault Tolerance Study

Emulating SpeculationEmulating Speculation

Emulating New InstructionsEmulating New Instructions

- 9 -


What is Pin?What is Pin? Easy-to-use Instrumentation:Easy-to-use Instrumentation:

– Uses dynamic instrumentation Uses dynamic instrumentation • Do not need source code, recompilation, post-linking

Programmable Instrumentation:Programmable Instrumentation:– Provides rich APIs to write in C/C++ your own instrumentation tools Provides rich APIs to write in C/C++ your own instrumentation tools

(called (called PintoolsPintools))

Multiplatform:Multiplatform:– Supports IA-32, EM64T, Itanium, XscaleSupports IA-32, EM64T, Itanium, Xscale

– Supports Linux, Windows, MacOSSupports Linux, Windows, MacOS

Robust:Robust:– Instruments real-life applicationsInstruments real-life applications

• Database, search engines, web browsers, …

– Instruments multithreaded applicationsInstruments multithreaded applications

Efficient:Efficient:– Applies compiler optimizations on instrumentation code Applies compiler optimizations on instrumentation code

- 10 -


How to use Pin?How to use Pin?

Launch and instrument an applicationLaunch and instrument an application

$ $ pinpin –t –t pintoolpintool –- –- applicationapplication

Instrumentation engine (provided in our kit)

Instrumentation tool

(write your own, or use one provided in our kit)

Attach to and instrument an applicationAttach to and instrument an application

$ $ pinpin –t –t pintoolpintool –pid –pid 12341234

- 11 -


Writing PintoolsWriting Pintools

- 12 -


Pin Instrumentation APIsPin Instrumentation APIs Basic APIs are architecture independent:Basic APIs are architecture independent:

– Provide common functionalities like determining:Provide common functionalities like determining:• Control-flow changes• Memory accesses

Architecture-specific APIsArchitecture-specific APIs– E.g., Info about segmentation registers on IA32 E.g., Info about segmentation registers on IA32

Call-based APIs:Call-based APIs:

– Instrumentation routinesInstrumentation routines

– Analysis routinesAnalysis routines

- 13 -


Instrumentation vs. Analysis Instrumentation vs. Analysis Concepts borrowed from the ATOM tool:Concepts borrowed from the ATOM tool:

InstrumentationInstrumentation routinesroutines define where define where instrumentation isinstrumentation is inserted inserted

– e.g. before instructione.g. before instruction

Occurs Occurs first timefirst time an instruction is executed an instruction is executed

Analysis routinesAnalysis routines define what to do when define what to do when instrumentation is instrumentation is activatedactivated

– e.g. increment countere.g. increment counter

Occurs Occurs every timeevery time an instruction is executed an instruction is executed

- 14 -


Pintool 1: Instruction CountPintool 1: Instruction Count



jlejle <L1><L1>



counter++;

counter++;

counter++;

counter++;

counter++;

- 15 -


Pintool 1: Instruction Count Pintool 1: Instruction Count OutputOutput

$ /bin/ls $ /bin/ls Makefile atrace.o imageload.out itrace Makefile atrace.o imageload.out itrace proccount Makefile.example imageload proccount Makefile.example imageload inscount0 itrace.o proccount.o atrace inscount0 itrace.o proccount.o atrace imageload.o inscount0.o itrace.outimageload.o inscount0.o itrace.out

$ pin -t inscount0 -- /bin/ls $ pin -t inscount0 -- /bin/ls Makefile atrace.o imageload.out itrace Makefile atrace.o imageload.out itrace proccount Makefile.example imageload proccount Makefile.example imageload inscount0 itrace.o proccount.o atrace inscount0 itrace.o proccount.o atrace imageload.o inscount0.o itrace.outimageload.o inscount0.o itrace.out

Count 422838 Count 422838

- 16 -


ManualExamples/inscount0.C

instrumentation routine

analysis routine

#include <iostream>#include "pin.h"

UINT64 icount = 0;

void docount() { icount++; } void Instruction(INS ins, void *v) { INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)docount, IARG_END);}

void Fini(INT32 code, void *v) { std::cerr << "Count " << icount << endl; }

int main(int argc, char * argv[]){ PIN_Init(argc, argv); INS_AddInstrumentFunction(Instruction, 0); PIN_AddFiniFunction(Fini, 0); PIN_StartProgram(); return 0;}

• Same source code works on the 4 architectures

• Pin automatically and efficiently saves/restores application state

- 17 -


Pintool 2: Instruction TracePintool 2: Instruction Trace



jlejle <L1><L1>



Print(ip);

Print(ip);

Print(ip);

Print(ip);

Print(ip);

• Need to pass an argument (ip) to the analysis routine (printip())

- 18 -


Pintool 2: Instruction Trace Pintool 2: Instruction Trace OutputOutput$ pin -t itrace -- /bin/ls $ pin -t itrace -- /bin/ls Makefile atrace.o imageload.out itrace Makefile atrace.o imageload.out itrace proccount Makefile.example imageload proccount Makefile.example imageload inscount0 itrace.o proccount.o atrace inscount0 itrace.o proccount.o atrace imageload.o inscount0.o itrace.outimageload.o inscount0.o itrace.out

$ head -4 itrace.out $ head -4 itrace.out

0x40001e90 0x40001e90

0x40001e91 0x40001e91

0x40001ee4 0x40001ee4

0x40001ee5 0x40001ee5

- 19 -


ManualExamples/itrace.Cargument to analysis routine

analysis routine


#include <stdio.h>#include <stdio.h>

#include "pin.H"#include "pin.H"

FILE * trace;FILE * trace;

void printip(void *ip) { fprintf(trace, "%p\n", ip); }void printip(void *ip) { fprintf(trace, "%p\n", ip); }

void Instruction(INS ins, void *v) {void Instruction(INS ins, void *v) {

INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)printip, INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)printip, IARG_INST_PTR, IARG_END); IARG_INST_PTR, IARG_END);

}}

void Fini(INT32 code, void *v) { fclose(trace); }void Fini(INT32 code, void *v) { fclose(trace); }

int main(int argc, char * argv[]) {int main(int argc, char * argv[]) {

trace = fopen("itrace.out", "w");trace = fopen("itrace.out", "w");

PIN_Init(argc, argv);PIN_Init(argc, argv);

INS_AddInstrumentFunction(Instruction, 0);INS_AddInstrumentFunction(Instruction, 0);

PIN_AddFiniFunction(Fini, 0);PIN_AddFiniFunction(Fini, 0);

PIN_StartProgram();PIN_StartProgram();

return 0;return 0;

}}

- 20 -


Examples of Arguments to Examples of Arguments to Analysis RoutineAnalysis Routine

IARG_INST_PTRIARG_INST_PTR

– Instruction pointer (program counter) valueInstruction pointer (program counter) value

IARG_UINT32 <value>IARG_UINT32 <value>

– An integer valueAn integer value

IARG_REG_VALUE <register name>IARG_REG_VALUE <register name>

– Value of the register specifiedValue of the register specified

IARG_BRANCH_TARGET_ADDRIARG_BRANCH_TARGET_ADDR

– Target address of the branch instrumentedTarget address of the branch instrumented

IARG_MEMORY_READ_EAIARG_MEMORY_READ_EA

– Effective address of a memory readEffective address of a memory read

And many more … (refer to the Pin manual for details)And many more … (refer to the Pin manual for details)

- 21 -


Instrumentation PointsInstrumentation Points

Instrument points relative to an instruction:Instrument points relative to an instruction:

– Before (IPOINT_BEFORE)Before (IPOINT_BEFORE)

– After: After: • Fall-through edge (IPOINT_AFTER)•Taken edge (IPOINT_TAKEN)

cmp %esi, %edx

jle <L1>

mov $0x1, %edi

<L1>: mov $0x8,%edi

count()

count()

count()

- 22 -


Instrumentation GranularityInstrumentation Granularity

Instrumentation with Pin can be done at 3 Instrumentation with Pin can be done at 3 different granularities:different granularities:

– InstructionInstruction

– Basic blockBasic block• A sequence of instructions terminated at a (conditional

or unconditional) control-flow changing instruction• Single entry, single exit

– TraceTrace• A sequence of basic blocks terminated at an

unconditional control-flow changing instruction• Single entry, multiple exits

sub $0xff, %edxcmp %esi, %edxjle <L1>

mov $0x1, %ediadd $0x10, %eaxjmp <L2>

1 Trace, 2 basic blocks, 6 insts

- 23 -


Recap of Pintool 1: Instruction Recap of Pintool 1: Instruction CountCount

sub $0xff, %edx

cmp %esi, %edx

jle <L1>

mov $0x1, %edi

add $0x10, %eax

counter++;counter++;

counter++;

counter++;

counter++;

• Straightforward, but the counting can be more efficient

- 24 -


Pintool 3: Faster Instruction Pintool 3: Faster Instruction CountCount

sub $0xff, %edx

cmp %esi, %edx

jle <L1>

mov $0x1, %edi

add $0x10, %eax

counter += 3

counter += 2basic blocks (bbl)

- 25 -


ManualExamples/inscount1.C#include <stdio.h>#include <stdio.h>

#include "pin.H“#include "pin.H“

UINT64 icount = 0;UINT64 icount = 0;

void docount(INT32 c) { icount += c; }void docount(INT32 c) { icount += c; }

void Trace(TRACE trace, void *v) {void Trace(TRACE trace, void *v) {

for (for (BBLBBL bbl = bbl = TRACE_BblHead(trace);TRACE_BblHead(trace);

BBL_Valid(bbl); bbl = BBL_Next(bbl)) { BBL_Valid(bbl); bbl = BBL_Next(bbl)) {

BBL_InsertCall(bbl, IPOINT_BEFORE, (AFUNPTR)docount, BBL_InsertCall(bbl, IPOINT_BEFORE, (AFUNPTR)docount,

IARG_UINT32, BBL_NumIns(bbl),IARG_UINT32, BBL_NumIns(bbl), IARG_END); IARG_END);

}}

}}

void Fini(INT32 code, void *v) { void Fini(INT32 code, void *v) {

fprintf(stderr, "Count %lld\n", icount);fprintf(stderr, "Count %lld\n", icount);

}}

int main(int argc, char * argv[]) {int main(int argc, char * argv[]) {

PIN_Init(argc, argv);PIN_Init(argc, argv);

TRACE_AddInstrumentFunction(Trace, 0);TRACE_AddInstrumentFunction(Trace, 0);

PIN_AddFiniFunction(Fini, 0);PIN_AddFiniFunction(Fini, 0);

PIN_StartProgram();PIN_StartProgram();

return 0;return 0;

}}

analysis routine


- 26 -


Modifying Program BehaviorModifying Program Behavior

Pin allows you not only observing but Pin allows you not only observing but also changing program behavioralso changing program behavior

Ways to change program behavior:Ways to change program behavior:

– Add/delete instructionsAdd/delete instructions

– Change register valuesChange register values

– Change memory valuesChange memory values

– Change control flowChange control flow

- 27 -


Example: Emulation of LoadsExample: Emulation of Loads

sub $0x11c,%esp

mov 0xc(%ebp),%eax

add $0x128, %eax

mov 0x8(%ebp),%edi

xor %eax, %edi

- 28 -


Example: Emulation of LoadsExample: Emulation of Loads

sub $0x11c,%esp

mov 0xc(%ebp),%eax

add $0x128, %eax

mov 0x8(%ebp),%edi

xor %eax, %edi

EmulateLoad(%ebp+0xc, %eax)

EmulateLoad(%ebp+0x8, %edi)

- 29 -


Emulation of Loads Emulation of Loads

$ pin -t emuload -- /bin/ls

Emulate loading from addr 0xbfffe188Emulate loading from addr 0x40016ae0Emulate loading from addr 0x40016c74Emulate loading from addr 0x40016c7cEmulate loading from addr 0x40016c84…_insprofiler.C imageload imageload.out insprofiler.C proccount.C atrace.C

- 30 -


SimpleExamples/emuload.C#include <stdio.h>#include "pin.H"#include "pin_isa.H"#include <iostream>

// Move from memory to registerADDRINT DoLoad(ADDRINT * addr) { cout << "Emulate loading from addr " << addr << endl; return *addr;}

VOID EmulateLoad(INS ins, VOID* v) { if (INS_Opcode(ins) == XEDICLASS_MOV && INS_IsMemoryRead(ins) &&

INS_OperandIsReg(ins, 0) && INS_OperandIsMemory(ins, 1)) {

// op0 <- *op1 INS_InsertCall(ins, IPOINT_BEFORE, AFUNPTR(DoLoad), IARG_MEMORYREAD_EA, IARG_RETURN_REGS, INS_OperandReg(ins, 0), IARG_END); INS_Delete(ins); }}

int main(int argc, char * argv[]) { PIN_Init(argc, argv); INS_AddInstrumentFunction(EmulateLoad, 0); PIN_StartProgram(); return 0;}

check if ins is a loadpass the load data

address to DoLoad()use DoLoad()’s return value

to modify the register which is the first operand of ins

remove ins (the original load)

- 31 -


Multithreading SupportMultithreading Support

Notify the pintool when a thread is Notify the pintool when a thread is created or exitedcreated or exited

Provide a “thread id” for pintools to Provide a “thread id” for pintools to identify a threadidentify a thread

Provide locks for pintools to access Provide locks for pintools to access shared data structures shared data structures

- 32 -


Example of Instrumenting Example of Instrumenting Multithreaded ProgramsMultithreaded Programs

$ pin –mt -t mtest –- threadCreating threadCreating threadJoined 0Joined 1$ cat mtest.out0x400109a8: 0thread begin 1 sp 0x80acc00 flags f000x40001d38: 1thread begin 3 sp 0x43305bd8 flags f210x40011220: 3thread begin 2 sp 0x42302bd8 flags f210x40010e15: 20x40005cdc: 2thread end 3 code 00x40005e90: 00x40005e90: 0thread end 2 code 0thread end 1 code 0

- 33 -


Tests/mtest.C

instrumentation routines

FILE * out;PIN_LOCK lock;

VOID TraceBegin(VOID * ip, UINT32 threadid) { GetLock(&lock, threadid+1); fprintf(out, "%p: %d\n", ip, threadid); ReleaseLock(&lock);}VOID Trace(TRACE trace, VOID *v) { TRACE_InsertCall(trace, IPOINT_BEFORE, AFUNPTR(TraceBegin), IARG_INST_PTR, IARG_THREAD_ID, IARG_END);}VOID ThreadBegin(UINT32 threadid, VOID * sp, int flags, VOID *v) { GetLock(&lock, threadid+1); fprintf(out, "thread begin %d sp %p flags %x\n",threadid, sp, flags); ReleaseLock(&lock);}VOID ThreadEnd(UINT32 threadid, INT32 code, VOID *v) { GetLock(&lock, threadid+1); fprintf(out, "thread end %d code %d\n",threadid, code); ReleaseLock(&lock);}VOID Fini(INT32 code, VOID *v) { fprintf(out, "Fini: code %d\n", code);}int main(INT32 argc, CHAR **argv) { InitLock(&lock); out = fopen("mtest.out", "w"); PIN_Init(argc, argv); PIN_AddThreadBeginFunction(ThreadBegin, 0); PIN_AddThreadEndFunction(ThreadEnd, 0); TRACE_AddInstrumentFunction(Trace, 0); PIN_AddFiniFunction(Fini, 0); PIN_StartProgram(); return 0;}

analysis routine

- 34 -


Debugging PintoolsDebugging Pintools1.1. Invoke gdb with your pintool (but don’t use “run”)Invoke gdb with your pintool (but don’t use “run”)

2.2. On another window, start your pintool with “-On another window, start your pintool with “-pause_tool”pause_tool”

3.3. Go back to gdb:Go back to gdb:

a)a) Attach to the processAttach to the process

b)b) Use “cont” to continue execution; can set breakpoints as Use “cont” to continue execution; can set breakpoints as usual usual

(gdb) attach 32017(gdb) break main(gdb) cont

$ pin –pause_tool 5 –t inscount0 -- /bin/lsPausing to attach to pid 32017

$ gdb inscount0(gdb)

- 35 -


ConclusionsConclusionsPinPin

Build your own architectural tools with Build your own architectural tools with easeease

Run on multiple platforms:Run on multiple platforms:

– IA-32, EM64T, Itanium, and XScaleIA-32, EM64T, Itanium, and XScale

– Linux, Windows, MacOSLinux, Windows, MacOS

Work on real-life applicationsWork on real-life applications

Efficient instrumentationEfficient instrumentation

- 36 -


Call For ActionCall For Action

Try it out!Try it out!Free download from:Free download from:

http://rogue.colorado.edu/pinhttp://rogue.colorado.edu/pin

* User manual, many example tools, * User manual, many example tools, tutorialstutorials

* ~7000 downloads since 2004 July* ~7000 downloads since 2004 July

Email: [email protected]

Group: http://groups.yahoo.com/group/pinheads/

Documents

- 1 - Copyright © 2006 Intel Corporation. All Rights Reserved. Using the Pin Instrumentation Tool for Computer Architecture Research Aamer Jaleel, Chi-Keung