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].
[SourceForge project]: http://sourceforge.net/projects/pincpt/
[files section]: http://sourceforge.net/projects/pincpt/files/
[documentation]: http://pincpt.sourceforge.net/
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.
[Pin]: http://www.pintool.org
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.
[controller]: http://www.cs.virginia.edu/kim/publicity/pin/docs/33586/Pin/html/group__CONTROLLER.html
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.
