Pincpt: A Tool For Checkpointing Architectural State

1 Introduction

Pincpt is a tool for checkpointing architectural state of an x86 application. The checkpoints are human-readable and are intended to initialize a user-mode CPU performance simulator. Currently pincpt only works with 32-bit Linux single-threaded applications.

2 Download

Pincpt is a SourceForge project. Go to the files section to download the latest release. SourceForge also hosts the documentation.

3 Dependences

Pincpt requires the Pin binary instrumentation tool. The preferred version is 2.8 (build 33586). Pincpt may require slight modifications to work with later versions of Pin due to the ever-changing Pin interface.

4 Building

To build pincpt, you will need to specify the Pin directory by either: setting the PIN_KIT variable in the environment, specifying it on the make command line, or putting it into the makefile directly.

5 Usage

pin -t /blah/pincpt/obj-ia32/pincpt.so [pincpt options] -- <application> <application arguments>

5.1 Options

-help: show all pincpt options
-o <dir>: output directory where the checkpoint will be written
-d <0 or 1>: unhelpful debug mode

In addition to the options above, pincpt uses the Pin controller interface for specifying when the checkpoint should be taken. This interface supports taking a checkpoint after a specified number of instructions, once a particular instruction is encountered, using a PinPoint file, etc.

5.2 Examples

Checkpoint ls after a 10000 instructions:

pin -t /blah/pincpt/obj-ia32/pincpt.so -skip 10000 -- /bin/ls

Often it's desirable to checkpoint a benchmark at some point in the source code (for example, after the initialization routine). This can be done by inserting a rarely used NOP at that point in the source code and telling pincpt to checkpoint at that instruction. In the example below, we use the rare NOP instruction xchg ecx, ecx which is encoded as 0x87c9.
```
pin -t /blah/pincpt/obj-ia32/pincpt.so -start_itext 87c9 -- benchmark
```

6 Checkpoint Format

Pincpt stores the checkpoint as a directory. Inside the directory, the main file contains the human readable part of the checkpoint and the .dat files contain compressed memory data.

The main file is in a hierarchical indented format (see example at the end). The supplied hconfig.* and gtree.* files provide a C interface for reading this hierachical format.

An example main file:

generator pincpt
processes
    process
        pid 8948
        cwd /tmp
        brk 0x822c000
        standard_streams
            stdin 0
            stdout 1
            stderr 2
        file_descriptors
            0
                path /dev/pts/13
                offset -1
                flags 0x8002
            1
                path /dev/pts/13
                offset -1
                flags 0x8002
            2
                path /dev/pts/13
                offset -1
                flags 0x8002
            3
                path /tmp/input
                offset 24576
                flags 0x0
            4
                path /tmp/output
                offset 36864
                flags 0x1
        threads
            thread
                tid 8948
                registers
                    edi 0x3
                    esi 0x20612
                    ebp 0xbfb12348
                    esp 0xbfb12310
                    ebx 0x270f
                    edx 0x80c24b0
                    ecx 0x400
                    eax 0x20
                    cs 0x73
                    ss 0x7b
                    ds 0x7b
                    es 0x7b
                    fs 0x0
                    gs 0x33
                    eflags 0x246
                    eip 0x8048350
                    mxcsr 0x1f80
                    fpcw 0x37f
                    fpsw 0x20
                    fptag 0x0
                    fpip_off 0xb682d68d
                    fpip_sel 0x73
                    fpopcode 0x55d
                    fpdp_off 0xbfb12328
                    fpdp_sel 0x7b
                    st0 0x00000000000000000000
                    st1 0x00000000000000000000
                    st2 0x00000000000000000000
                    st3 0x00000000000000000000
                    st4 0x00000000000000000000
                    st5 0x00000000000000000000
                    st6 0x3ffbccccccccccccd000
                    st7 0x3ffeeb42f1b3e44ab17d
                    ftw 0x0
                    mm0 0x0000000000000000
                    mm1 0x0000000000000000
                    mm2 0x0000000000000000
                    mm3 0x0000000000000000
                    mm4 0x0000000000000000
                    mm5 0x0000000000000000
                    mm6 0xccccccccccccd000
                    mm7 0xeb42f1b3e44ab17d
                    xmm0 0x00000000000000000000000000000000
                    xmm1 0x00000000000000000000000000000000
                    xmm2 0x00000000000000000000000000000000
                    xmm3 0x00000000000000000000000000000000
                    xmm4 0x00000000000000000000000000000000
                    xmm5 0x00000000000000000000000000000000
                    xmm6 0x00000000000000000000000000000000
                    xmm7 0x00000000000000000000000000000000
                signals
                    blocked
                    pending
                thread_local_storage
                    6
                        entry_number 6
                        base_addr 0x820a830
                        limit 1048575
                        seg_32bit 1
                        contents 0
                        read_exec_only 0
                        limit_in_pages 1
                        seg_not_present 0
                        useable 1
        memory
            range
                start 0x6b9000
                end 0x6d4000
                permissions rx
                mapped_to
                    path /lib/ld-2.5.so
                    offset 0x0
                data 0.dat
            range
                start 0x6d4000
                end 0x6d5000
                permissions rx
                mapped_to
                    path 1409042
                    offset 0x1
                data 1.dat
            range
                start 0xbfafe000
                end 0xbfb14000
                permissions rw
                data 2.dat
        environment
            "HOME=/u/blah"
            "EDITOR=ed"

7 Version History


Version	Changes
1.0a	Fixed bug affecting x87, MMX, and XMM register values.
1.0	Initial release.