Program Record/Replay Toolkit

Product Overview

This toolkit is called Program Record/Replay Toolkit.

The current version is 1.0 and was created on February 15, 2013.

Program Record/Replay Toolkit is built upon the Pin dynamic binary instrumentation system. It is a re-distribution of the latest/reasonably recent Pin kit for Linux with some additions for making Pin-based analyses repeatable. The additions include a library and a header file that provide an API for making Pintools enabled for recording a program execution and doing analysis while replaying a program recording. Also included in the toolkit are example Pintools that are record/replay enabled and a number of scripts for recording, replaying, and doing replay-based analysis for finding and check-pointing representative regions ("PinPoints") of large applications.

Intel is releasing this toolkit so that developers can experiment with making their Pin-based analysis repeatable.

Installation

Download and unpack the toolkit. Set your PIN_KIT variable to point to that directory. You can also refer to the tools in the kit using full or relative paths. Do not rearrange the files or subdirectories in the unpacked kit. If you want to move the kit directory, move everything.

Prerequisites: Installation will only work on 64-bit Linux machines with gcc/g++ installed for both 32-bit and 64-bit compiles.

cd $PIN_KIT/extras/pinplay/examples
make

Making your Pintool record/replay enabled

Prerequisite:

Your tool should not be modifying control-flow of the test program (no PIN_ExecuteAt()).
It should not be using the IMG API in Pin.

Pintool source changes:

#include "pinplay.H"
PINPLAY_ENGINE pinplay_engine;
KNOB<BOOL> KnobPinPlayLogger(KNOB_MODE_WRITEONCE,
                      "pintool", "log", "0",
                      "Activate the pinplay logger");
KNOB<BOOL> KnobPinPlayReplayer(KNOB_MODE_WRITEONCE,
                      "pintool", "replay", "0",
                      "Activate the pinplay replayer");

main()
{
..
pinplay_engine.Activate(argc, argv,
      KnobPinPlayLogger, KnobPinPlayReplayer);
..
}

Makefile changes:

PINPLAY_HOME=$(PIN_KIT)/extras/pinplay/
PINPLAY_INCLUDE_HOME=$(PINPLAY_HOME)/include
PINPLAY_LIB_HOME=$(PINPLAY_HOME)/lib/$(TARGET_LONG)
EXT_LIB_HOME=$(PINPLAY_HOME)/lib-ext/$(TARGET_LONG)

CXXFLAGS += -I$(PINPLAY_INCLUDE_HOME)


linking: link in $(PINPLAY_LIB_HOME)/libpinplay.a,
    $(EXT_LIB_HOME)/libbz2.a, $(EXT_LIB_HOME)/libzlib.a

Pintool run command changes:

 pintool + pinplay logger:
 -------------------------

   % pin -t your-tool.so -log -log:basename pinball/foo -- test-app

 pintool + pinplay replayer:
 ---------------------------
   % pin -xyzzy -reserve_memory pinball/foo.address -t your-tool.so
	-replay -replay:basename pinball/foo -- $PIN_KIT/extrans/pinplay/bin/intel64/nullapp
     [for intel64 pinballs]

   % pin -xyzzy -reserve_memory pinball/foo.address -t your-tool.so
	-replay -replay:basename pinball/foo -- $PIN_KIT/extrans/pinplay/bin/ia32/nullapp
	[for ia32 pinballs]

Known issues

Please check all the Pin known issues in Pin documentation, they apply to PinPlay as well. In addition, the following are the currently known PinPlay issues:

Pintools that change application control flow (with PIN_ExecuteAt() for example) cannot work with replay for obvious reasons (replay faithfully follows the control-flow as captured during logging).
Use of Pin's IMG API will not work during replay as there is no "image" (actually only the dummy 'nullapp' image) available during replay.
Replaying of 32-bit pinballs on 64-bit Ubuntu does not work. Other 64-bit OSes (e.g. SLES or Red Hat) do not have this issue.
Replay-based tools have not been tested with Pin features such as versioning and buffering.
Sampling of multi-threaded programs has some known issues.

Related Publications

PinPlay: A Framework for Deterministic Replay and Reproducible Analysis of Parallel Programs; Harish Patil, Cristiano Pereira, Mack Stallcup, Gregory Lueck, James Cownie. CGO 2010. [CGO 2010 Best Paper Award Winner!]
Pin: Building Customized Program Analysis Tools with Dynamic Instrumentation; Chi-Keung Luk, Robert Cohn, Robert Muth, Harish Patil, Artur Klauser, Geoff Lowney, Steven Wallace, Vijay Janapa Reddi, and Kim Hazelwood. Proceedings of the 2005 ACM SIGPLAN conference on Programming language design and implementation.
Pinpointing Representative Portions of Large Intel® Itanium® Programs with Dynamic Instrumentation; Patil, H., Cohn, R., Charney, M., Kapoor, R., Sun, A., and Karunanidhi, A. In Proceedings of the 37th Annual IEEE/ACM international Symposium on Microarchitecture (Portland, Oregon, December 04 - 08, 2004).

WhatIf

WhatIf Software

Parallel Computing