Pin Tutorial - Unicamp

Pin Tutorial

What is Instrumentation?A technique that inserts extra code intoa program to collect runtime informationInstrumentation approaches: Source instrumentation:– Instrument source programs Binary instrumentation:– Instrument executables directly1Pin Tutorial 2007

Why use Dynamic Instrumentation? No need to recompile or relink Discover code at runtime Handle dynamically-generated code Attach to running processes2Pin Tutorial 2007

Advantages of Pin InstrumentationEasy-to-use Instrumentation: Uses dynamic instrumentation– Do not need source code, recompilation, post-linkingProgrammable Instrumentation: Provides rich APIs to write in C/C your owninstrumentation tools (called Pintools)Multiplatform: Supports x86, x86-64, Itanium, Xscale Supports Linux, Windows, MacOSRobust: Instruments real-life applications: Database, web browsers, Instruments multithreaded applications Supports signalsEfficient: Applies compiler optimizations on instrumentation code3Pin Tutorial 2007

Using PinLaunch and instrument an application pin –t pintool –- applicationInstrumentation engine(provided in the kit)Instrumentation tool(write your own, or use oneprovided in the kit)Attach to and instrument an application pin –t pintool –pid 12344Pin Tutorial 2007

Pin Instrumentation APIsBasic APIs are architecture independent: Provide common functionalities like determining:– Control-flow changes– Memory accessesArchitecture-specific APIs e.g., Info about segmentation registers on IA32Call-based APIs: Instrumentation routines Analysis routines5Pin Tutorial 2007

Instrumentation vs. AnalysisConcepts borrowed from the ATOM tool:Instrumentation routines define whereinstrumentation is inserted e.g., before instruction Occurs first time an instruction is executedAnalysis routines define what to do wheninstrumentation is activated e.g., increment counter Occurs every time an instruction is executed6Pin Tutorial 2007

Pintool 1: Instruction Countsub 0xff, %edxcounter ;cmp %esi, %edxcounter ;jle L1 counter ;mov 0x1, %edicounter ;add 0x10, %eaxcounter ;7Pin Tutorial 2007

Pintool 1: Instruction Count Output /bin/lsMakefile imageload.out itrace proccountimageload inscount0 atrace itrace.out pin -t inscount0 -- /bin/lsMakefile imageload.out itrace proccountimageload inscount0 atrace itrace.outCount 4228388Pin Tutorial 2007

#include iostream #include "pin.h"ManualExamples/inscount0.cppUINT64 icount 0;void docount() { icount ; }analysis routinevoid Instruction(INS ins, void *v)instrumentation routine{INS InsertCall(ins, IPOINT BEFORE, (AFUNPTR)docount, IARG END);Same source code works on the 4 architectures}Pin automaticallyapplicationvoid Fini(INT32code, void saves/restores*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;}9Pin Tutorial 2007state

Pintool 2: Instruction TracePrint(ip);sub 0xff, %edxPrint(ip);cmp %esi, %edxPrint(ip);jle L1 Print(ip);mov 0x1, %ediPrint(ip);add 0x10, %eaxNeed to pass ip argument to the analysis routine (printip())10Pin Tutorial 2007

Pintool 2: Instruction Trace Output pin -t itrace -- /bin/lsMakefile imageload.out itrace proccountimageload inscount0 atrace itrace.out head -4 11Pin Tutorial 2007

ManualExamples/itrace.cpp#include stdio.h #include "pin.H"argument to analysis routineFILE * trace;void printip(void *ip) { fprintf(trace, "%p\n", ip); }analysis routineinstrumentation routinevoid Instruction(INS ins, void *v) {INS InsertCall(ins, IPOINT BEFORE, (AFUNPTR)printip,IARG INST PTR, IARG END);}void Fini(INT32 code, void *v) { fclose(trace); }int main(int argc, char * argv[]) {trace fopen("itrace.out", "w");PIN Init(argc, argv);INS AddInstrumentFunction(Instruction, 0);PIN AddFiniFunction(Fini, 0);PIN StartProgram();return 0;}12Pin Tutorial 2007

Examples of Arguments to AnalysisRoutineIARG INST PTR Instruction pointer (program counter) valueIARG UINT32 value An integer valueIARG REG VALUE register name Value of the register specifiedIARG BRANCH TARGET ADDR Target address of the branch instrumentedIARG MEMORY READ EA Effective address of a memory readAnd many more (refer to the Pin manual for details)13Pin Tutorial 2007

Instrumentation PointsInstrument points relative to an instruction: Before (IPOINT BEFORE) After:– Fall-through edge (IPOINT AFTER)– Taken edge (IPOINT TAKEN BRANCH)count()count()14cmp%esi, %edx count()jle L1 mov L1 :mov 0x8,%edi 0x1, %ediPin Tutorial 2007

Instrumentation GranularityInstrumentation can be done at threedifferent granularities: Instruction Basic blocksub 0xff, %edx– A sequence of instructionscmp %esi, %edxterminated at a control-flowchanging instructionjle L1 – Single entry, single exit Tracemov 0x1, %edi– A sequence of basic blocksadd 0x10, %eaxterminated at anjmp L2 unconditional control-flow1 Trace, 2 BBs, 6 instschanging instruction– Single entry, multiple exits15Pin Tutorial 2007

Recap of Pintool 1: Instruction Countcounter ;sub 0xff, %edxcounter ;cmp %esi, %edxcounter ;jle L1 counter ;mov 0x1, %edicounter ;add 0x10, %eaxStraightforward, but the counting can be more efficient16Pin Tutorial 2007

Pintool 3: Faster Instruction Countcounter 3sub 0xff, %edxcmp%esi, %edxjle L1 counter 2mov 0x1, %ediadd17 0x10, %eaxPin Tutorial 2007basic blocks (bbl)

ManualExamples/inscount1.cpp#include stdio.h #include "pin.H“UINT64 icount 0;analysis routinevoid docount(INT32 c) { icount c; }void Trace(TRACE trace, void *v) { instrumentation routinefor (BBL bbl TRACE BblHead(trace);BBL Valid(bbl); bbl BBL Next(bbl)) {BBL InsertCall(bbl, IPOINT BEFORE, (AFUNPTR)docount,IARG UINT32, BBL NumIns(bbl), IARG END);}}void Fini(INT32 code, void *v) {fprintf(stderr, "Count %lld\n", icount);}int main(int argc, char * argv[]) {PIN Init(argc, argv);TRACE AddInstrumentFunction(Trace, 0);PIN AddFiniFunction(Fini, 0);PIN StartProgram();return 0;}18Pin Tutorial 2007

Modifying Program BehaviorPin allows you not only to observe but alsochange program behaviorWays to change program behavior: Add/delete instructions Change register values Change memory values Change control flow19Pin Tutorial 2007

Instrumentation Library#include iostream #include "pin.H"UINT64 icount 0;Instruction counting Pin Tool#include iostream #include "pin.H"#include "instlib.H"VOID Fini(INT32 code, VOID *v) {std::cerr "Count " icount endl;INSTLIB::ICOUNT icount;}VOID docount() {icount ;}VOID Fini(INT32 code, VOID *v) {cout "Count" icount.Count() endl;}VOID Instruction(INS ins, VOID *v) {int main(int argc,IARG END);char * argv[]) {INS InsertCall(ins, IPOINT BEFORE,(AFUNPTR)docount,PIN Init(argc, argv);}PIN AddFiniFunction(Fini, 0);int main(int argc, char * argv[]) {icount.Activate();PIN Init(argc, argv);INS AddInstrumentFunction(Instruction,PIN StartProgram();0);return0;PIN AddFiniFunction(Fini, 0);}PIN StartProgram();return 0;}20Pin Tutorial 2007

Useful InstLib abstractions ICOUNT– # of instructions executed FILTER– Instrument specific routines or libraries only ALARM– Execution count timer for address, routines, etc. FOLLOW CHILD– Inject Pin into new process created by parent process TIME WARP– Preserves RDTSC behavior across executions CONTROL– Limit instrumentation address ranges21Pin Tutorial 2007

Useful InstLib ALARM Example22Pin Tutorial 2007

Debugging Pintools1. Invoke gdb with your pintool (don’t “run”) gdb inscount0(gdb)2. In another window, start your pintool withthe “-pause tool” flag pin –pause tool 5 –t inscount0 -- /bin/lsPausing to attach to pid 320173. Go back to gdb window:a) Attach to the processb) “cont” to continue execution; can set breakpoints as usual(gdb) attach 32017(gdb) break main(gdb) cont23Pin Tutorial 2007

24Pin Tutorial gccgobmk200%xalancbmksjengperlbenchRelative to NativePin OverheadSPEC Integer 2006180%160%140%120%

Adding User 264refgccxalancbmksjenggobmkPin Tutorial 2007mcfPinPin e to Native800%

Instrumentation Driven SimulationFast exploratory studies Instrumentation native execution Simulation speeds at MIPSCharacterize complex applications E.g. Oracle, Java, parallel data-mining appsSimple to build instrumentation tools Tools can feed simulation models in real time Tools can gather instruction traces for later use26Pin Tutorial 2007

Performance ModelsBranch Predictor Models: PC of conditional instructions Direction Predictor: Taken/not-taken information Target Predictor: PC of target instruction if takenCache Models: Thread ID (if multi-threaded workload) Memory address Size of memory operation Type of memory operation (Read/Write)Simple Timing Models: Latency information27Pin Tutorial 2007

Branch Predictor ModelAPI dataPinInstrumentation ToolAPI()BPSimPin ToolBranch instr infoInstrumentation RoutinesModelAnalysis RoutinesBPSim Pin Tool Instruments all branches Uses API to set up call backs to analysis routinesBranch Predictor Model: Detailed branch predictor simulator28Pin Tutorial 2007BP

BP ImplementationINSTRUMENTVOID ProcessBranch(ADDRINT PC, ADDRINT targetPC, bool BrTaken) {BP Info pred myBPU.GetPrediction( PC );if( pred.Taken ! BrTaken ) {// Direction Mispredicted}if( pred.predTarget ! targetPC ) {// Target Mispredicted}myBPU.Update( PC, BrTaken, targetPC);}VOID Instruction(INS ins, VOID *v){if( INS IsDirectBranchOrCall(ins) INS HasFallThrough(ins) )INS InsertCall(ins, IPOINT BEFORE, (AFUNPTR) ProcessBranch,ADDRINT, INS Address(ins),IARG UINT32, INS DirectBranchOrCallTargetAddress(ins),IARG BRANCH TAKEN, IARG END);}MAINANALYSISBranchPredictor myBPU;int main() {PIN Init();INS AddInstrumentationFunction(Instruction, 0);PIN StartProgram();}29Pin Tutorial 2007

Branch Predictor Performance - GCCBimodal not chosenBimodal In McFarling PredictorMcFarling PredictorBranch prediction accuracies range from 0-100%Branches are hard to predict in some phases Can simulate these regions alone by fast forwarding tothem in real time30Pin Tutorial 2007

Performance Model InputsBranch Predictor Models: PC of conditional instructions Direction Predictor: Taken/not-taken information Target Predictor: PC of target instruction if takenCache Models: Thread ID (if multi-threaded workload) Memory address Size of memory operation Type of memory operation (Read/Write)Simple Timing Models: Latency information31Pin Tutorial 2007

Cache SimulatorsAPI dataPinInstrumentation ToolCachePin ToolAPI()Mem Addr infoInstrumentation RoutinesCacheModelAnalysis RoutinesCache Pin Tool Instruments all instructions that reference memory Use API to set up call backs to analysis routinesCache Model: Detailed cache simulator32Pin Tutorial 2007

Cache ImplementationMAININSTRUMENTANALYSISCACHE t CacheHierarchy[MAX NUM THREADS][MAX NUM LEVELS];33VOID MemRef(int tid, ADDRINT addrStart, int size, int type) {for(addr addrStart; addr (addrStart size); addr LINE SIZE)LookupHierarchy( tid, FIRST LEVEL CACHE, addr, type);}VOID LookupHierarchy(int tid, int level, ADDRINT addr, int accessType){result cacheHier[tid][cacheLevel]- Lookup(addr, accessType );if( result CACHE MISS ) {if( level LAST LEVEL CACHE ) return;LookupHierarchy(tid, level 1, addr, accessType);}}VOID Instruction(INS ins, VOID *v){if( INS IsMemoryRead(ins) )INS InsertCall(ins, IPOINT BEFORE, (AFUNPTR) MemRef,IARG THREAD ID, IARG MEMORYREAD EA, IARG MEMORYREAD SIZE,IARG UINT32, ACCESS TYPE LOAD, IARG END);if( INS IsMemoryWrite(ins) )INS InsertCall(ins, IPOINT BEFORE, (AFUNPTR) MemRef,IARG THREAD ID, IARG MEMORYWRITE EA, IARG MEMORYWRITE SIZE,IARG UINT32, ACCESS TYPE STORE, IARG END);}int main() {PIN Init();INS AddInstrumentationFunction(Instruction, 0);Pin Tutorial 2007PIN StartProgram();}

Performance ModelsBranch Predictor Models: PC of conditional instructions Direction Predictor: Taken/not-taken information Target Predictor: PC of target instruction if takenCache Models: Thread ID (if multi-threaded workload) Memory address Size of memory operation Type of memory operation (Read/Write)Simple Timing Models: Latency information34Pin Tutorial 2007