========================================================================================
Pin is a tool for the instrumentation of programs. It supports Linux* and Windows* executables for IA-32, Intel(R) 64, and IA-64 architectures.
Pin allows a tool to insert arbitrary code (written in C or C++) in arbitrary places in the executable. The code is added dynamically while the executable is running. This also makes it possible to attach Pin to an already running process.
Pin provides a rich API that abstracts away the underlying instruction set idiosyncracies and allows context information such as register contents to be passed to the injected code as parameters. Pin automatically saves and restores the registers that are overwritten by the injected code so the application continues to work. Limited access to symbol and debug information is available as well.
Pin includes the source code for a large number of example instrumentation tools like basic block profilers, cache simulators, instruction trace generators, etc. It is easy to derive new tools using the examples as a template.
Table of Contents
========================================================================================
The only code ever executed is the generated code. The original code is only used for reference. When generating code, Pin gives the user an opportunity to inject their own code (instrumentation).
These two components are instrumentation and analysis code. Both components live in a single executable, a Pintool. Pintools can be thought of as plugins that can modify the code generation process inside Pin.
The Pintool registers callback routines with Pin that are called from Pin whenever new code needs to be generated. This routine represents the instrumentation component. It inspects the code to be generated, investigates its static properties, and decides if and where to inject calls to analysis code. Those calls can target arbitrary functions inside the Pintool. Pin makes sure that register state is saved and restored as necessary and allow arguments to be passed to the functions.
Pin and the Pintool control a program starting with the very first instruction. For executables compiled with shared libraries this implies that the execution of the dynamic loader and all shared libraries will be visible to the Pintool.
When writing tools, it is more important to tune the analysis code than the instrumentation code. This is because the instrumentation is executed once, but analysis code is called many times.
Trace instrumentation lets the Pintool inspect and instrument an executable one trace at a time. Traces usually begin at the target of a taken branch and end with an unconditional branch, including calls and returns. Pin guarantees that a trace is only entered at the top, but it may contain multiple exits. If a branch joins the middle of a trace, Pin constructs a new trace that begins with the branch target. Pin breaks the trace into basic blocks, BBLs. A BBL is a single entrance, single exit sequence of instructions. Branches to the middle of a bbl begin a new trace and hence a new BBL. It is often possible to insert a single analysis call for a BBL, instead of one analysis call for every instruction. Reducing the number of analysis calls makes instrumentation more efficient. Trace instrumentation utilizes the TRACE_AddInstrumentFunction API call.
As a convenience for Pintool writers, Pin also offers an instruction instrumentation mode which lets the tool inspect and instrument an executable a single instruction at a time. This is essentially identical to trace instrumentation where the Pintool writer has been freed from the responsibilty of iterating over the instructions inside a trace. As decribed under trace instrumentation, certain BBLs and the instructions inside of them may be generated (and hence instrumented) multiple times. Instruction instrumentation utilizes the INS_AddInstrumentFunction API call.
Sometimes, however, it can be useful to look at different granularity than a trace. For this purpose Pin offers two additional modes: image and routine instrumentation. These modes are implemented by "caching" instrumentation requests and hence incur a space overhead.
Image instrumentation lets the Pintool inspect and instrument an entire image, IMG, when it is first loaded. A Pintool can walk the sections, SEC, of the image, the routines, RTN, of a section, and the instructions, INS of a routine. Instrumentation can be inserted so that it is executed before or after a routine is executed, or before or after an instruction is executed. Image instrumentation utilizes the IMG_AddInstrumentFunction API call. Image instrumentation depends on symbol information to determine routine boundaries hence PIN_InitSymbols must be called before PIN_Init.
Routine instrumentation lets the Pintool inspect and instrument an entire routine before the first time it is called. A Pintool can walk the instructions of a routine. There is not enough information available to break the instructions into BBLs. Instrumentation can be inserted so that it is executed before or after a routine is executed, or before or after an instruction is executed. Routine instrumentation can be more efficient than image instrumentation in space and time when the only a small number of the routines in an image are executed. Routine instrumentation utilizes the RTN_AddInstrumentFunction API call. Instrumentation of routine exits does not work reliably in the presence of tail calls or when return instructions cannot reliably be detected.
========================================================================================
To illustrate how to write Pintools, we present some simple examples. In the web based version of the manual, you can click on a function in the Pin API to see its documentation.
docount before every instruction. When the program exits, it prints the count to stderr.Here is how to run it and the output:
$ pin -t inscount0.so -- /bin/ls Makefile atrace.o imageload.out itrace proccount Makefile.example imageload inscount0 itrace.o proccount.o atrace imageload.o inscount0.o itrace.out Count 422838 $
The example can be found in source/tools/ManualExamples/inscount0.cpp
#include <iostream> #include <fstream> #include "pin.H" // The running count of instructions is kept here // make it static to help the compiler optimize docount static UINT64 icount = 0; // This function is called before every instruction is executed VOID docount() { icount++; } // Pin calls this function every time a new instruction is encountered VOID Instruction(INS ins, VOID *v) { // Insert a call to docount before every instruction, no arguments are passed INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)docount, IARG_END); } KNOB<string> KnobOutputFile(KNOB_MODE_WRITEONCE, "pintool", "o", "inscount.out", "specify output file name"); // This function is called when the application exits VOID Fini(INT32 code, VOID *v) { // Write to a file since cout and cerr maybe closed by the application ofstream OutFile; OutFile.open(KnobOutputFile.Value().c_str()); OutFile.setf(ios::showbase); OutFile << "Count " << icount << endl; OutFile.close(); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { // Initialize pin PIN_Init(argc, argv); // Register Instruction to be called to instrument instructions INS_AddInstrumentFunction(Instruction, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
docount, the analysis procedure. In this example, we show how to pass arguments. When calling an analysis procedure, Pin allows you to pass the instruction pointer, current value of registers, effective address of memory operations, constants, etc. For a complete list, see IARG_TYPE.With a small change, we can turn the instruction counting example into a Pintool that prints the address of every instruction that is executed. This tool is useful for understanding the control flow of a program for debugging, or in processor design when simulating an instruction cache.
We change the arguments to INS_InsertCall to pass the address of the instruction about to be executed. We replace docount with printip, which prints the instruction address. It writes it output to to the file itrace.out.
This is how to run it and look at the output:
$ pin -t itrace.so -- /bin/ls Makefile atrace.o imageload.out itrace proccount Makefile.example imageload inscount0 itrace.o proccount.o atrace imageload.o inscount0.o itrace.out $ head itrace.out 0x40001e90 0x40001e91 0x40001ee4 0x40001ee5 0x40001ee7 0x40001ee8 0x40001ee9 0x40001eea 0x40001ef0 0x40001ee0 $
The example can be found in source/tools/ManualExamples/itrace.cpp
#include <stdio.h> #include "pin.H" FILE * trace; // This function is called before every instruction is executed // and prints the IP VOID printip(VOID *ip) { fprintf(trace, "%p\n", ip); } // Pin calls this function every time a new instruction is encountered VOID Instruction(INS ins, VOID *v) { // Insert a call to printip before every instruction, and pass it the IP INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)printip, IARG_INST_PTR, IARG_END); } // This function is called when the application exits VOID Fini(INT32 code, VOID *v) { fprintf(trace, "#eof\n"); fclose(trace); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { trace = fopen("itrace.out", "w"); // Initialize pin PIN_Init(argc, argv); // Register Instruction to be called to instrument instructions INS_AddInstrumentFunction(Instruction, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
In this example, we show how to do more selective instrumentation by examining the instructions. This tool generates a trace of all memory addresses referenced by a program. This is also useful for debugging and for simulating a data cache in a processor.
We only instrument instructions that read or write memory. We also use INS_InsertPredicatedCall instead of INS_InsertCall to avoid generating references to instructions that are predicated and the predicate is false (predication is only relevant for IA-64 ISA).
Since the instrumentation functions are only called once and the analysis functions are called every time an instruction is executed, it is much faster to only instrument the memory operations, as compared to the previous instruction trace example that instruments every instruction.
Here is how to run it and the sample output:
$ pin -t pinatrace.so -- /bin/ls Makefile atrace.o imageload.o inscount0.o itrace.out Makefile.example atrace.out imageload.out itrace proccount atrace imageload inscount0 itrace.o proccount.o $ head pinatrace.out 0x40001ee0: R 0xbfffe798 0x40001efd: W 0xbfffe7d4 0x40001f09: W 0xbfffe7d8 0x40001f20: W 0xbfffe864 0x40001f20: W 0xbfffe868 0x40001f20: W 0xbfffe86c 0x40001f20: W 0xbfffe870 0x40001f20: W 0xbfffe874 0x40001f20: W 0xbfffe878 0x40001f20: W 0xbfffe87c $
The example can be found in source/tools/ManualExamples/pinatrace.cpp
/* * This file contains an ISA-portable PIN tool for tracing memory accesses. */ #include <stdio.h> #include "pin.H" FILE * trace; // Print a memory read record VOID RecordMemRead(VOID * ip, VOID * addr) { fprintf(trace,"%p: R %p\n", ip, addr); } // Print a memory write record VOID RecordMemWrite(VOID * ip, VOID * addr) { fprintf(trace,"%p: W %p\n", ip, addr); } // Is called for every instruction and instruments reads and writes VOID Instruction(INS ins, VOID *v) { // instruments loads using a predicated call, i.e. // the call happens iff the load will be actually executed // (this does not matter for ia32 but arm and ipf have predicated instructions) if (INS_IsMemoryRead(ins)) { INS_InsertPredicatedCall( ins, IPOINT_BEFORE, (AFUNPTR)RecordMemRead, IARG_INST_PTR, IARG_MEMORYREAD_EA, IARG_END); } // instruments stores using a predicated call, i.e. // the call happens iff the store will be actually executed if (INS_IsMemoryWrite(ins)) { INS_InsertPredicatedCall( ins, IPOINT_BEFORE, (AFUNPTR)RecordMemWrite, IARG_INST_PTR, IARG_MEMORYWRITE_EA, IARG_END); } } VOID Fini(INT32 code, VOID *v) { fprintf(trace, "#eof\n"); fclose(trace); } int main(int argc, char *argv[]) { PIN_Init(argc, argv); trace = fopen("pinatrace.out", "w"); INS_AddInstrumentFunction(Instruction, 0); PIN_AddFiniFunction(Fini, 0); // Never returns PIN_StartProgram(); return 0; }
If you invoke it on ls, you would see this output:
$ pin -t imageload.so -- /bin/ls Makefile atrace.o imageload.o inscount0.o proccount Makefile.example atrace.out imageload.out itrace proccount.o atrace imageload inscount0 itrace.o trace.out $ cat imageload.out Loading /bin/ls Loading /lib/ld-linux.so.2 Loading /lib/libtermcap.so.2 Loading /lib/i686/libc.so.6 Unloading /bin/ls Unloading /lib/ld-linux.so.2 Unloading /lib/libtermcap.so.2 Unloading /lib/i686/libc.so.6 $
The example can be found in source/tools/ManualExamples/imageload.cpp
// // This tool prints a trace of image load and unload events // #include <stdio.h> #include "pin.H" FILE * trace; // Pin calls this function every time a new img is loaded // It can instrument the image, but this example does not // Note that imgs (including shared libraries) are loaded lazily VOID ImageLoad(IMG img, VOID *v) { fprintf(trace, "Loading %s, Image id = %d\n", IMG_Name(img).c_str(), IMG_Id(img)); } // Pin calls this function every time a new img is unloaded // You can't instrument an image that is about to be unloaded VOID ImageUnload(IMG img, VOID *v) { fprintf(trace, "Unloading %s\n", IMG_Name(img).c_str()); } // This function is called when the application exits // It prints the name and count for each procedure VOID Fini(INT32 code, VOID *v) { fclose(trace); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { trace = fopen("imageload.out", "w"); // Initialize symbol processing PIN_InitSymbols(); // Initialize pin PIN_Init(argc, argv); // Register ImageLoad to be called when an image is loaded IMG_AddInstrumentFunction(ImageLoad, 0); // Register ImageUnload to be called when an image is unloaded IMG_AddUnloadFunction(ImageUnload, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
The example can be found in source/tools/ManualExamples/inscount1.cpp
#include <iostream> #include <fstream> #include "pin.H" // The running count of instructions is kept here // make it static to help the compiler optimize docount static UINT64 icount = 0; // This function is called before every block VOID docount(INT32 c) { icount += c; } // Pin calls this function every time a new basic block is encountered // It inserts a call to docount VOID Trace(TRACE trace, VOID *v) { // Visit every basic block in the trace for (BBL bbl = TRACE_BblHead(trace); BBL_Valid(bbl); bbl = BBL_Next(bbl)) { // Insert a call to docount before every bbl, passing the number of instructions BBL_InsertCall(bbl, IPOINT_BEFORE, (AFUNPTR)docount, IARG_UINT32, BBL_NumIns(bbl), IARG_END); } } KNOB<string> KnobOutputFile(KNOB_MODE_WRITEONCE, "pintool", "o", "inscount.out", "specify output file name"); // This function is called when the application exits VOID Fini(INT32 code, VOID *v) { // Write to a file since cout and cerr maybe closed by the application ofstream OutFile; OutFile.open(KnobOutputFile.Value().c_str()); OutFile.setf(ios::showbase); OutFile << "Count " << icount << endl; OutFile.close(); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { // Initialize pin PIN_Init(argc, argv); // Register Instruction to be called to instrument instructions TRACE_AddInstrumentFunction(Trace, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
Executing the tool and sample output:
$ pin -t proccount.so -- /bin/grep proccount.cpp Makefile
proccount_SOURCES = proccount.cpp
$ head proccount.out
Procedure Image Address Calls Instructions
_fini libc.so.6 0x40144d00 1 21
__deregister_frame_info libc.so.6 0x40143f60 2 70
__register_frame_info libc.so.6 0x40143df0 2 62
fde_merge libc.so.6 0x40143870 0 8
__init_misc libc.so.6 0x40115824 1 85
__getclktck libc.so.6 0x401157f4 0 2
munmap libc.so.6 0x40112ca0 1 9
mmap libc.so.6 0x40112bb0 1 23
getpagesize libc.so.6 0x4010f934 2 26
$
The example can be found in source/tools/ManualExamples/proccount.cpp
// // This tool counts the number of a routine is executed and counts // the number of instructions executed in a routine // #include <fstream> #include <iomanip> #include <string.h> #include "pin.H" // Holds instruction count for a single procedure typedef struct RtnCount { string _name; string _image; ADDRINT _address; RTN _rtn; UINT64 _rtnCount; UINT64 _icount; struct RtnCount * _next; } RTN_COUNT; // Linked list of instruction counts for each routine RTN_COUNT * RtnList = 0; // This function is called before every instruction is executed VOID docount(UINT64 * counter) { (*counter)++; } const char * StripPath(const char * path) { const char * file = strrchr(path,'/'); if (file) return file+1; else return path; } // Pin calls this function every time a new rtn is executed VOID Routine(RTN rtn, VOID *v) { // Allocate a counter for this routine RTN_COUNT * rc = new RTN_COUNT; // The RTN goes away when the image is unloaded, so save it now // because we need it in the fini rc->_name = RTN_Name(rtn); rc->_image = StripPath(IMG_Name(SEC_Img(RTN_Sec(rtn))).c_str()); rc->_address = RTN_Address(rtn); rc->_icount = 0; rc->_rtnCount = 0; // Add to list of routines rc->_next = RtnList; RtnList = rc; RTN_Open(rtn); // Insert a call at the entry point of a routine to increment the call count RTN_InsertCall(rtn, IPOINT_BEFORE, (AFUNPTR)docount, IARG_PTR, &(rc->_rtnCount), IARG_END); // For each instruction of the routine for (INS ins = RTN_InsHead(rtn); INS_Valid(ins); ins = INS_Next(ins)) { // Insert a call to docount to increment the instruction counter for this rtn INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)docount, IARG_PTR, &(rc->_icount), IARG_END); } RTN_Close(rtn); } // This function is called when the application exits // It prints the name and count for each procedure VOID Fini(INT32 code, VOID *v) { ofstream count("proccount.out"); count << setw(23) << "Procedure" << " " << setw(15) << "Image" << " " << setw(18) << "Address" << " " << setw(12) << "Calls" << " " << setw(12) << "Instructions" << endl; for (RTN_COUNT * rc = RtnList; rc; rc = rc->_next) { if (rc->_icount > 0) count << setw(23) << rc->_name << " " << setw(15) << rc->_image << " " << setw(18) << hex << rc->_address << dec <<" " << setw(12) << rc->_rtnCount << " " << setw(12) << rc->_icount << endl; } } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { // Initialize symbol table code, needed for rtn instrumentation PIN_InitSymbols(); // Initialize pin PIN_Init(argc, argv); // Register Routine to be called to instrument rtn RTN_AddInstrumentFunction(Routine, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
The example can be found in source/tools/ManualExamples/staticcount.cpp
// // This tool prints a trace of image load and unload events // #include <stdio.h> #include "pin.H" // Pin calls this function every time a new img is loaded // It can instrument the image, but this example merely // counts the number of static instructions in the image VOID ImageLoad(IMG img, VOID *v) { UINT32 count = 0; for (SEC sec = IMG_SecHead(img); SEC_Valid(sec); sec = SEC_Next(sec)) { for (RTN rtn = SEC_RtnHead(sec); RTN_Valid(rtn); rtn = RTN_Next(rtn)) { // Prepare for processing of RTN, an RTN is not broken up into BBLs, // it is merely a sequence of INSs RTN_Open(rtn); for (INS ins = RTN_InsHead(rtn); INS_Valid(ins); ins = INS_Next(ins)) { count++; } // to preserve space, release data associated with RTN after we have processed it RTN_Close(rtn); } } fprintf(stderr, "Image %s has %d instructions\n", IMG_Name(img).c_str(), count); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { // prepare for image instrumentation mode PIN_InitSymbols(); // Initialize pin PIN_Init(argc, argv); // Register ImageLoad to be called when an image is loaded IMG_AddInstrumentFunction(ImageLoad, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
The example can be found in source/tools/ManualExamples/detach.cpp
#include <stdio.h> #include "pin.H" #include <iostream> // This tool shows how to detach Pin from an // application that is under Pin's control. UINT64 icount = 0; #define N 10000 VOID docount() { icount++; // Release control of application if 10000 // instructions have been executed if ((icount % N) == 0) { PIN_Detach(); } } VOID Instruction(INS ins, VOID *v) { INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR)docount, IARG_END); } VOID ByeWorld(VOID *v) { std::cerr << endl << "Detached at icount = " << N << endl; } int main(int argc, char * argv[]) { PIN_Init(argc, argv); // Callback function to invoke for every // execution of an instruction INS_AddInstrumentFunction(Instruction, 0); // Callback functions to invoke before // Pin releases control of the application PIN_AddDetachFunction(ByeWorld, 0); // Never returns PIN_StartProgram(); return 0; }
In probe mode, the application and the replacement routine are run natively. This improves performance, but it puts more responsibility on the tool writer. Probes can only be placed on RTN boundaries.
Many of the PIN APIs that are available in JIT mode are not applicable in Probe mode. In particular, the Pin thread APIs are not supported in Probe mode, because Pin has no information about the threads when the application is run natively. For more information, check the RTN API documentation.
The tool writer must guarantee that there is not jump target where the probe is placed. A probe is five bytes long on IA-32 architecture, seven bytes long on Intel(R) 64 architecture, and one bundle on IA-64 architecture.
Also, it is the tool writer's responsibility to ensure that no thread is currently executing the code where a probe is inserted. Tool writers are encouraged to insert probes when an image is loaded to avoid this problem. Pin will automatically remove the probes when an image is unloaded.
When using probes, Pin must be started with the PIN_StartProgramProbed() API.
Note that on newer Linux OSes, additional libraries must be installed to use probe mode. See Libraries for Linux for further information.
The example can be found in source/tools/ManualExamples/replacesigprobed.cpp. To build this test, execute:
$ make replacesigprobed.test
// Replace an original function with a custom function defined in the tool using // probes. The replacement function has a different signature from that of the // original replaced function. #include "pin.H" #include <iostream> using namespace std; typedef VOID * ( *FP_MALLOC )( size_t ); // This is the replacement routine. // VOID * NewMalloc( FP_MALLOC orgFuncptr, UINT32 arg0, ADDRINT returnIp ) { // Normally one would do something more interesting with this data. // cout << "NewMalloc (" << hex << ADDRINT ( orgFuncptr ) << ", " << dec << arg0 << ", " << hex << returnIp << ")" << endl << flush; // Call the relocated entry point of the original (replaced) routine. // VOID * v = orgFuncptr( arg0 ); return v; } // Pin calls this function every time a new img is loaded. // It is best to do probe replacement when the image is loaded, // because only one thread knows about the image at this time. // VOID ImageLoad( IMG img, VOID *v ) { // See if malloc() is present in the image. If so, replace it. // RTN rtn = RTN_FindByName( img, "malloc" ); if (RTN_Valid(rtn)) { cout << "Replacing malloc in " << IMG_Name(img) << endl; // Define a function prototype that describes the application routine // that will be replaced. // PROTO proto_malloc = PROTO_Allocate( PIN_PARG(void *), CALLINGSTD_DEFAULT, "malloc", PIN_PARG(int), PIN_PARG_END() ); // Replace the application routine with the replacement function. // Additional arguments have been added to the replacement routine. // RTN_ReplaceSignatureProbed(rtn, AFUNPTR(NewMalloc), IARG_PROTOTYPE, proto_malloc, IARG_ORIG_FUNCPTR, IARG_FUNCARG_ENTRYPOINT_VALUE, 0, IARG_RETURN_IP, IARG_END); // Free the function prototype. // PROTO_Free( proto_malloc ); } } // Initialize and start Pin in Probe mode. // int main( INT32 argc, CHAR *argv[] ) { // Initialize symbol processing // PIN_InitSymbols(); // Initialize pin // PIN_Init( argc, argv ); // Register ImageLoad to be called when an image is loaded // IMG_AddInstrumentFunction( ImageLoad, 0 ); // Start the program in probe mode, never returns // PIN_StartProgramProbed(); return 0; }
========================================================================================
The examples in the previous section have introduced a number of ways to register call back functions via the Pin API:
The extra parameter val (shared by all the registration functions) will be passed to fun as its second argument whenever it is "called back". This is a standard mechanism used in GUI programming with call backs.
If this feature is not needed, it is safe to pass 0 for val when registering a call back. The expected use of val is to pass a pointer to an instance of a class. Since val is a generic pointer, fun must cast it back to an object before dereferencing the pointer.
========================================================================================
An application and a tool are invoked as follows:
pin [pin-option]... -t [toolname] [tool-options]... -- [application] [application-option]..
These are a few of the Pin options are currently available. See Command Line Switches for the complete list.
The tool-options follow immediately after the tool specification and depend on the tool used.
Everything following the -- is the command line for the application.
For example, to apply the itrace example (Instruction Address Trace (Instruction Instrumentation)) to a run of the "ls" program:
pin -t itrace.so -- /bin/ls
To get a listing of the available command line options for Pin:
pin -help
To get a listing of the available command line options for the itrace example:
pin -t itrace.so -help -- /bin/ls
Note that in the last case /bin/ls is necessary on the command line but will not be executed.
An application and a tool are invoked in "mixed-mode" as follows:
pin [pin-option]... -t64 <64-bit toolname> -t <32-bit toolname> [tool-options]... -- <application> [application-option]..
See source/tools/CrossIa32Intel64/makefile for further information.
The file "pin" is a script that expects the Pin binary "pinbin" to be in the architecture-specific "bin" subdirectory (i.e. intel64/bin). The "pin" script distinguishes the 32-bit version of the Pin binary from the 64-bit version of the Pin binary by using the -p32/-p64 switches, respectively. Today, the 32-bit version of the Pin binary is invoked, and the path of the 64-bit version of Pin is passed as an argument using the -p64 switch. However, one could change this to invoke the 64-bit version of the Pin binary, and pass the 32-bit version of the Pin binary as an argument using the -p32 switch.
See Libraries for Linux for more information about the environment variables that are set up in the "pin" script.
IMPORTANT: The description about invoking assumes that the application is a program binary (and not a shell script). If your application is invoked indirectly (from a shell script or using 'exec') then you need to change the actual invocation of the program binary by prefixing it with pin/pintool options. Here's one way of doing that:
# Track down the actual application binary, say it is 'application_binary'. % mv application_binary application_binary.real # Write a shell script named 'application_binary' with the following contents. # (change 'itrace' to your desired tool) #!/bin/sh pin -t itrace.so -- application_binary.real $*
After you do this, whenever 'application_binary' is invoked indirectly (from some shell script or using 'exec'), the real binary will get invoked with the right pin/pintool options.
========================================================================================
When running an application under the control of Pin and a Pintool there are two different programs residing in the address space. The application, and the Pin instrumentation engine together with your Pintool. The pintool is normally a shared object loaded by Pin. This section describes how to use gdb to find bugs in a Pintool. You cannot run Pin directly from gdb since Pin uses the debugging API to start the application. Instead, you must invoke Pin from the command line with the -pause_tool switch, and use gdb to attach to the Pin process from another window. The -pause_tool n switch makes Pin print out the process identifier (pid) and pause for n seconds.
Option 1 is to use full path to the tool when running pin.
Option 2 is to tell gdb to load the debugging information of the tool. Pin prompts with the exact gdb command to be used in this case.
To check that gdb loaded the debugging info to the tool use the command "info sharedlibrary" and you should see that gdb has read the symbols for your tool (as in the example below).
(gdb) info sharedlibrary From To Syms Read Shared Object Library 0x001b3ea0 0x001b4d80 Yes /lib/libdl.so.2 0x003b3820 0x00431d74 Yes /usr/intel/pkgs/gcc/4.2.0/lib/libstdc++.so.6 0x0084f4f0 0x00866f8c Yes /lib/i686/libm.so.6 0x00df8760 0x00dffcc4 Yes /usr/intel/pkgs/gcc/4.2.0/lib/libgcc_s.so.1 0x00e5fa00 0x00f60398 Yes /lib/i686/libc.so.6 0x40001c50 0x4001367f Yes /lib/ld-linux.so.2 0x008977f0 0x00af7784 Yes ./dcache.so
For example, if your tool is called opcodemix and the application is /bin/ls, you can use gdb as described below. The following example is for the Intel(R) 64 Linux platform. Substitute "ia32" or "ia64" for the IA-32 architecture or IA-64 architecture.
Change directory to the directory where your tool resides, and start gdb with pin, but do not use the run command:
$ /usr/bin/gdb ../../../intel64/bin/pinbin GNU gdb Red Hat Linux (6.3.0.0-1.132.EL4rh) Copyright 2004 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "x86_64-redhat-linux-gnu"...Using host libthread_db library "/lib64/tls/libthread_db.so.1" (gdb)
In another window, start your application with the -pause_tool switch:
$ ../../../intel64/bin/pinbin -pause_tool 10 -t obj-intel64/opcodemix.so -- /bin/ls Pausing to attach to pid 28769 To load the tool's debug info to gdb use: add-symbol-file .../source/tools/SimpleExamples/obj-intel64/opcodemix.so 0x2a959e9830
Then go back to gdb and attach to the process:
(gdb) attach 28769 Attaching to program: .../intel64/bin/pinbin, process 28769 0x000000314b38f7a2 in ?? () (gdb)
Now, you should tell gdb to load the Pintool debugging information, by copying the debugging message we got when invoking pin with the -pause_tool switch..
(gdb) add-symbol-file .../source/tools/SimpleExamples/obj-intel64/opcodemix.so 0x2a959e9830
add symbol table from file ".../source/tools/SimpleExamples/obj-intel64/opcodemix.so" at
.text_addr = 0x2a959e9830
(y or n) y
Reading symbols from .../source/tools/SimpleExamples/obj-intel64/opcodemix.so...done.
(gdb)
Now, instead of using the gdb run command, you use the cont command to continue execution. You can also set breakpoints as normal:
(gdb) b opcodemix.cpp:447 Breakpoint 1 at 0x2a959ecf60: file opcodemix.cpp, line 447. (gdb) cont Continuing. Breakpoint 1, main (argc=7, argv=0x3ff00f12f8) at opcodemix.cpp:447 447 int main(int argc, CHAR *argv[]) (gdb)
If the program does not exit, then you should detach so gdb will release control:
(gdb) detach Detaching from program: .../intel64/bin/pinbin, process 28769 (gdb)
If you recompile your program and then use the run command, gdb will notice that the binary has been changed and reread the debug information from the file. This does not always happen automatically when using attach. In this case you must use the "add-symbol-file" command again to make gdb reread the debug information.
========================================================================================
Pin provides a mechanism to write messages from a Pintool to a logfile. To use this capability, call the LOG() API with your message. The default filename is pintool.log, and it is created in the currently working directory. Use the -logfile switch after the tool name to change the path and file name of the log file.
LOG( "Replacing function in " + IMG_Name(img) + "\n" ); LOG( "Address = " + hexstr( RTN_Address(rtn)) + "\n" ); LOG( "Image ID = " + decstr( IMG_Id(img) ) + "\n" );
========================================================================================
The way a Pintool is written can have great impact on the performace of the tool, i.e. how much it slows down the applications it is instrumenting. This section demonstrates some techniques that can be used to improve tool performance. Let's start with an example. The following piece of code is derived from the source/tools/SimpleExamples/edgcnt.cpp:
The instrumentation component of the tool is show below
VOID Instruction(INS ins, void *v) { ... if ( [ins is a branch or a call instruction] ) { INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR) docount2, IARG_INST_PTR, IARG_BRANCH_TARGET_ADDR, IARG_BRANCH_TAKEN, IARG_END); } ... }
The analysis component looks like this:
VOID docount2( ADDRINT src, ADDRINT dst, INT32 taken )
{
if(!taken) return;
COUNTER *pedg = Lookup( src,dst );
pedg->_count++;
}
The purpose of the tool is to count how often each controlflow changing edge in the control flowgraph is traversed. The tool considers both calls and branches but for brevity we will not mention branches in our description. The tool works as follows: The instrumentation component instruments each branch with a call to docount2. As parameters we pass in the origin and the target of the branch and whether the branch was taken or not. Branch origin and target represent of the source and destination of the controlflow edges. If a branch is not taken the controlflow does not change and hence the analysis routine returns right away. If the branch is taken we use the src and dst parameters to look up the counter associated with this edge (Lookup will create a new one if this edge has not been seen before) and increment the counter. Note, that the tool could have been simplified somewhat by using IPOINT_TAKEN_BRANCH option with INS_InsertCall().
VOID docount( COUNTER *pedg, INT32 taken )
{
if( !taken ) return;
pedg->_count++;
}
And the instrumentation will be somewhat more complex:
VOID Instruction(INS ins, void *v) { ... if (INS_IsDirectBranchOrCall(ins)) { COUNTER *pedg = Lookup( INS_Address(ins), INS_DirectBranchOrCallTargetAddress(ins) ); INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR) docount, IARG_ADDRINT, pedg, IARG_BRANCH_TAKEN, IARG_END); } else { INS_InsertCall(ins, IPOINT_BEFORE, (AFUNPTR) docount2, IARG_INST_PTR, IARG_BRANCH_TARGET_ADDR, IARG_BRANCH_TAKEN, IARG_END); } ... }
VOID docount( COUNTER *pedg, INT32 taken )
{
pedg->_count += taken;
}
There is now no question whether docount() will be inlined or not.
#include <iostream> #include <fstream> #include "pin.H" // The running count of instructions is kept here // make it static to help the compiler optimize docount static UINT64 icount = 0; // This function is called before every block // Use the fast linkage for calls VOID PIN_FAST_ANALYSIS_CALL docount(ADDRINT c) { icount += c; } // Pin calls this function every time a new basic block is encountered // It inserts a call to docount VOID Trace(TRACE trace, VOID *v) { // Visit every basic block in the trace for (BBL bbl = TRACE_BblHead(trace); BBL_Valid(bbl); bbl = BBL_Next(bbl)) { // Insert a call to docount for every bbl, passing the number of instructions. // IPOINT_ANYWHERE allows Pin to schedule the call anywhere in the bbl to obtain best performance. // Use a fast linkage for the call. BBL_InsertCall(bbl, IPOINT_ANYWHERE, AFUNPTR(docount), IARG_FAST_ANALYSIS_CALL, IARG_UINT32, BBL_NumIns(bbl), IARG_END); } } KNOB<string> KnobOutputFile(KNOB_MODE_WRITEONCE, "pintool", "o", "inscount.out", "specify output file name"); // This function is called when the application exits VOID Fini(INT32 code, VOID *v) { // Write to a file since cout and cerr maybe closed by the application ofstream OutFile; OutFile.open(KnobOutputFile.Value().c_str()); OutFile.setf(ios::showbase); OutFile << "Count " << icount << endl; OutFile.close(); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { // Initialize pin PIN_Init(argc, argv); // Register Instruction to be called to instrument instructions TRACE_AddInstrumentFunction(Trace, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
Another call linkage optimization is to eliminate the frame pointer. We recommend using -fomit-frame-pointer to compile tools with gcc. See the gcc documentation for an explanation of what it does. The standard Pintool makefiles include -fomit-frame-pointer. Like PIN_FAST_ANALYSIS_CALL, the benefit is largest for small analysis functions. Debuggers rely on frame pointers to display stack traces, so eliminate this option when trying to debug a PinTool. If you are using a standard PinTool makefile, you can do this by overriding the definition of OPT on the command line with
make OPT=-O0
/* * This file contains a Pintool for sampling the IPs of instruction executed. * It serves as an example of a more efficient way to write analysis routines * that include conditional tests. * Currently, it works on IA-32 and Intel(R) 64 architectures. */ #include <stdio.h> #include <stdlib.h> #include "pin.H" FILE * trace; const INT32 N = 100000; const INT32 M = 50000; INT32 icount = N; /* * IP-sampling could be done in a single analysis routine like: * * VOID IpSample(VOID *ip) * { * --icount; * if (icount == 0) * { * fprintf(trace, "%p\n", ip); * icount = N + rand() % M; * } * } * * However, we break IpSample() into two analysis routines, * CountDown() and PrintIp(), to facilitate Pin inlining CountDown() * (which is the much more frequently executed one than PrintIp()). */ ADDRINT CountDown() { --icount; return (icount==0); } // The IP of the current instruction will be printed and // the icount will be reset to a random number between N and N+M. VOID PrintIp(VOID *ip) { fprintf(trace, "%p\n", ip); // Prepare for next period icount = N + rand() % M; // random number from N to N+M } // Pin calls this function every time a new instruction is encountered VOID Instruction(INS ins, VOID *v) { // CountDown() is called for every instruction executed INS_InsertIfCall(ins, IPOINT_BEFORE, (AFUNPTR)CountDown, IARG_END); // PrintIp() is called only when the last CountDown() returns a non-zero value. INS_InsertThenCall(ins, IPOINT_BEFORE, (AFUNPTR)PrintIp, IARG_INST_PTR, IARG_END); } // This function is called when the application exits VOID Fini(INT32 code, VOID *v) { fprintf(trace, "#eof\n"); fclose(trace); } // argc, argv are the entire command line, including pin -t <toolname> -- ... int main(int argc, char * argv[]) { trace = fopen("isampling.out", "w"); // Initialize pin PIN_Init(argc, argv); // Register Instruction to be called to instrument instructions INS_AddInstrumentFunction(Instruction, 0); // Register Fini to be called when the application exits PIN_AddFiniFunction(Fini, 0); // Start the program, never returns PIN_StartProgram(); return 0; }
In the above example, the original analysis routine IpSample() has a conditional control-flow change. It is rewritten into two analysis routines: CountDown() and PrintIp(). CountDown() is the simpler one of the two, which doesn't have control-flow change. It also performs the original conditional test and returns the test result. We use the conditional instrumentaton APIs INS_InsertIfCall() and INS_InsertThenCall() to tell Pin that tbe analysis routine specified by an INS_InsertThenCall() (i.e. PrintIp() in this example) is executed only if the result of the analysis routine specified by the previous INS_InsertIfCall() (i.e. CountDown() in this example) is non-zero. Now CountDown(), the common case, can be inlined by Pin, and only once a while does Pin need to execute PrintIp(), the non-inlined case.
========================================================================================
To install a kit, unpack a kit and change to the directory:
$ tar zxf pin-2.4-20148-gcc.3.4.6-ia32_intel64-linux.tar.gz $ cd pin-2.4-20148-gcc.3.4.6-ia32_intel64-linux
Build and test the examples from the manual
$ cd source/tools/ManualExamples/
$ make test
/usr/bin/g++ -c -Wall -Werror -Wno-unknown-pragmas -g -O3 -fomit-frame-pointer
-DBIGARRAY_MULTIPLIER=1 -DUSING_XED -g -fno-strict-aliasing -I../Include
-I../InstLib -I../../../extras/xed2-intel64/include -I../../../source/include
-I../../../source/include/gen -DTARGET_IA32E -DHOST_IA32E -fPIC -DTARGET_LINUX
-o obj-intel64/inscount0.o inscount0.cpp
/usr/bin/g++ -g -shared -Wl,-Bsymbolic -Wl,--version-script=../../../source/include/pintool.ver
-L../Lib/ -L../ExtLib/ -L../../../extras/xed2-intel64/lib -L../../../intel64/lib
-L../../../intel64/lib-ext -o obj-intel64/inscount0.so obj-intel64/inscount0.o
-L../Lib/ -L../ExtLib/ -L../../../extras/xed2-intel64/lib -L../../../intel64/lib
-L../../../intel64/lib-ext -lpin -lxed -ldwarf -lelf -ldl -gtouch inscount0.tested
touch inscount0.failed
touch obj-intel64/inscount0.so.makefile.copy; rm obj-intel64/inscount0.so.makefile.copy
../../../pin -slow_asserts -t obj-intel64/inscount0.so -- /bin/cp makefile obj-intel64/inscount0.so.makefile.copy
cmp makefile obj-intel64/inscount0.so.makefile.copy
rm obj-intel64/inscount0.so.makefile.copy; rm inscount0.failed
<etc.>
Run one of the sample tools from the installed directory. Use "obj-ia32" for the IA-32 architecture, "obj-intel64" for the Intel(R) 64 architecture, and "obj-ia64" for the IA-64 architecture.
$ ../Bin/pin -t obj-intel64/pinatrace.so -- /bin/ls _insprofiler.cpp atrace.out inscount0.o itrace.cpp proccount atrace imageload.cpp inscount1.cpp itrace.o proccount.cpp atrace.cpp inscount0 insprofiler.cpp itrace.out proccount.o atrace.o inscount0.cpp itrace makefile proccount.out $ head pinatrace.out 0x40001ee0: R 0xbfffe1e8 0x40001efd: W 0xbfffe224 0x40001f09: W 0xbfffe228 0x40001f20: W 0xbfffe2b4 0x40001f20: W 0xbfffe2b8 0x40001f20: W 0xbfffe2bc 0x40001f20: W 0xbfffe2c0 0x40001f20: W 0xbfffe2c4 0x40001f20: W 0xbfffe2c8 0x40001f20: W 0xbfffe2cc $
To write your own tool, copy one of the example directories and edit the makefile to add your tool. The sample tool MyPinTool is recommended. This tool allows you to build either inside or outside the Pin environment.
========================================================================================
An example of the Visual Studio 2005* project that builds pin tool in the Visual Studio IDE can be found in the MyPinTool directory.
Enter this directory and open MyPinTool.vcproj project or MyPinTool.sln solution. To build the tool, press "Build Solution" (F7).
To run an application, instrumented by MyPinTool, press "Start Without Debugging" (Ctrl-F5). You can select another application and change tool's switches in the "MyPinTool Properties->Debugging" page.
You can use MyPinTool as a template for your own project. Please, look carefully at the compilation and linking switches in the MyPinTool property pages. Mandatory switches can be found in the ms.flags file in the kit's source directory. Following are some of them:
/MT link to static CRT library. Using
CRT DLL could cause conflict with
the application using the same DLL.
/EHs- /EHa- disable exception handling in the tool,
otherwise it could interfere in the
application's exception handling.
/wd4530 turn off the warning about not having
/EHsc turned on, while using STL.
/EXPORT:main main function of the tool has to be exported
/ENTRY:.... tool DLL should be initialized by pin.lib
/NODEFAULTLIB do not link and use any system library except
for those listed explicitly to avoid conflicts
with an application using the same library
/BASE:.... helps to avoid layout conflicts with DLLs linked
to the application
To build all tool examples:
nmake
To run all tests:
nmake test
To delete build targets and results of tests:
nmake clean
To build specific tool example:
cd SimpleExamples
..\nmake opcodemix.dll
To test specific tool:
cd SimpleExamples
..\nmake opcodemix.test
Notice, "nmake" in the above commands is the nmake.bat file from the kit's root directory. To invoke nmake.exe directly, you must specify the makefile as the input file:
nmake.exe /F Nmakefile
Otherwise, instead of Nmakefile, nmake.exe will find the GNU "makefile" file that resides in the same directory.
When considering this configuration, take into account that multi-DLL Pin tool may increase memory fragmentation and cause layout conflicts with application images. If there is no compelling reasons for using multiple DLLs, build your tool as a single DLL to reduce the risk of memory conflicts.
Limitations and instructions:
========================================================================================
Pin on Windows uses dbghelp.dll by Microsoft* to provide symbolic information. This DLL is not distributed with the kit. In order to get support for symbolic information in Pin, you have to download the "Debugging Tools For Windows*" package, version 6.8.4.0 from http://www.microsoft.com/whdc/devtools/debugging/default.mspx. Use "Debugging Tools For Windows* 32-bit Version" for IA-32 architectures and "Debugging Tools For Windows* - Native X64" for Intel(R) 64 architectures. Distribution of the debugging tools is provided in .msi format which must be installed to extract a single file. Copy dbghelp.dll from the package into "ia32\bin" or "intel64\bin" directory of the Pin kit. This directory should already contain pin.exe and pinvm.dll files.
========================================================================================
libc libm libdl ld-linux*
and g++ libraries:
libstdc++ libgcc_s
If your system does not have the runtime libraries required for gcc3.4 or later(/usr/lib/libstdc++.so.6), then we recommend that you install them. Installing the compiler will install the runtime libraries. If that is not possible, then we provide the libraries and a method to use them from a local directory. If you want to use a probe based tool, then you cannot use the default glibc that comes with recent linux distributions. We provide the libraries and a method to use them from a local directory.
tproj> tar zxf pin-2.4-20350-gcc.3.4.6-ia32_intel64-linux.tar.gz tproj> cd pin-2.4-20350-gcc.3.4.6-ia32_intel64-linux tproj/pin-2.4-20350-gcc.3.4.6-ia32_intel64-linux> tar zxf ../pin-jit-runtime.tar.gz
The file "pin" is a script that will set up the environment to find the libraries you installed from pin-jit-runtime.tar.gz. These directories will be searched first, followed by directories that are on the LD_LIBRARY_PATH.
If you need to change the directory structure or copy pin to a different directory, then you must understand the following. The file "pin" is a script that expects the binary "pinbin" to be in the architecture-specific "bin" subdirectory (i.e. ia32/bin). The script expects the libraries to be found in the architecture-specific "runtime" subdirectory (i.e. ia32/runtime). If you need a different directory structure, you can edit the pin script. The pin binary does not make assumptions about the directory structure.
We try to keep the libraries in pin-jit-runtime.tar.gz up to date so you can use the latest version of gcc. If you have problems with undefined symbols at runtime, then our libraries are probably too old for your compiler. You may need to copy the libstdc++ and libgcc_s from your build system to the appropriate directory.
The pin-probe-runtime requires using header files from glibc 2.3.4 and gcc 3.4.2 for compiling tools. The simplest way to do this is to install red hat el4 or one of its clones (c.g. centos) and use the system compiler.
ia32/runtime/glibc/ ia32/runtime/libgcc_s.so.1@ ia32/runtime/libstdc++.so.6.0.9* ia32/runtime/libgcc_s-3.4.6-20060404.so.1* ia32/runtime/libstdc++.so.6@ ia32/runtime/libgcc_s.so@ ia32/runtime/libstdc++.so.6.0.3*
The "ia32" subdirectory is used for the IA-32 architecture. Similarly, "intel64" is used for the Intel(R) 64 architecture, and "ia64" is used for the IA-64 architecture.
We have to modify the library paths so pin can find its libraries, but we don't want to affect the application. Pin uses these environment variables to control library paths.
PIN_VM_LD_LIBRARY_PATH - LD_LIBRARY_PATH will be set to this value before starting vm or binary tool
PIN_LD_RESTORE_REQUIRED - Tells injector, vm, or binary tool that it must restore the loader environment variables at startup, using the following variables.
PIN_APP_LD_LIBRARY_PATH - LD_LIBRARY_PATH is restored to this value. If PIN_LD_RESTORE_REQUIRED is set, but this variable is not, then LD_LIBRARY_PATH will be unset.
PIN_APP_LD_ASSUME_KERNEL - LD_ASSUME_KERNEL is restored to this value. If PIN_LD_RESTORE_REQUIRED is set, but this variable is not, then LD_ASSUME_KERNEL will be unset.
The pin injector starts an application and then injects a vm into the address space of an application, and runs the application in the vm. The vm requires a binary, which we call "pinbin". The injector happens to be the same binary as the vm. When an injector starts up from the command line by invoking "pin", it needs the g++ libraries. If they are not in the standard place, then LD_LIBRARY_PATH must be set to point to them. The injector must use the standard glibc so don't point the LD_LIBRARY_PATH to the glibc that we redistribute.
When an injector starts a vm, it must setup the library path by using PIN_LD_LIBRARY_PATH. This should point to the g++ libraries. If you are using probe mode, then it should also point to the glibc files.
We don't want the application using any pin libraries so we restore the LD_LIBRARY_PATH before invoking the application by using PIN_LD_RESTORE_REQUIRED, PIN_OLD_LD_LIBRARY_PATH, and PIN_OLD_LD_ASSUME_KERNEL.
See MIXED-MODE for more information on invoking Pin on Intel(R) 64 Architectures.
========================================================================================
See the README file in the kit for specific information about compiler version and other limitations. If your compiler is not compatible with the kit, send mail to [email protected].
Pin on Windows does not separate DLLs loaded by the tool from the application DLLs - it uses the same system loader. In order to avoid isolation problems, Pin tool should not load any DLL that can be shared with the application. For the same reason, Pin tool should avoid static links to any common DLL, except for those listed in PIN_COMMON_LIBS (see source.flags file).
In probe mode, the application runs natively, and the probe is placed in the original code. If a tool replaces a function shared by the tool and the application, an undesirable behavior may occur. For example, if a tool replaces EnterCriticalSection() with an analysis routine that calls printf(), this could result in an infinite loop, because printf() can also call EnterCriticalSection(). The application would call EnterCriticalSection(), and the control flow would go to the replacement routine, and it would call EnterCriticalSection() (via printf) which would call the replacement routine, and so on.
========================================================================================
Send bugs and questions to [email protected]. Complete bug reports that are easy to reproduce are fixed faster, so try to provide as much information as possible. Include: kit number, your OS version, compiler version. Try to reproduce the problem in a simple example that you can send us.
========================================================================================
The information in this manual is subject to change without notice and Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may appear in this document or any software that may be provided in association with this document. This document and the software described in it are furnished under license and may only be used or copied in accordance with the terms of the license. No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted by this document. The information in this document is provided in connection with Intel products and should not be construed as a commitment by Intel Corporation.
EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life saving, life sustaining, critical control or safety systems, or in nuclear facility applications.
Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompat- ibilities arising from future changes to them.
The software described in this document may contain software defects which may cause the product to deviate from published specifications. Current characterized software defects are available on request.
Intel, the Intel logo, Intel SpeedStep, Intel NetBurst, Intel NetStructure, MMX, Intel386, Intel486, Celeron, Intel Centrino, Intel Xeon, Intel XScale, Itanium, Pentium, Pentium II Xeon, Pentium III Xeon, Pentium M, and VTune are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
Other names and brands may be claimed as the property of others.
Copyright 2004-2009, Intel Corporation.
========================================================================================