pincpt Files

         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.