/*
	README file for building Memtrace tool, EPRSD compressor and Replay tool
	Author: Sandeep Budanur Ramanna
	E-mail: sbudanu@ncsu.edu
	North Carolina State University
	Created on Sep 09 2010
*/

This README file will inside the ./ScalaMemTrace folder after unzipping ./ScalaMemTrace.tgz file.

//////////////////////////////////////////////////////////////////////////////////
			To build Memtrace Pin tool
//////////////////////////////////////////////////////////////////////////////////
1)
a) Install Pin binary instrumentation tool. Refer www.pintool.org for the instructions.
b) Install MPICH2 message passing (MPI) library. Refer http://www.mcs.anl.gov/research/projects/mpich2/. 

2) Install Wisconsin stackwlaker library. Refer http://www.paradyn.org/html/stackwalker1.1-features.html.
Also refer "WiscLibInstallChanges.txt" to get help on installation. If Wisconsin stackwalker is not used,
this step can be skipped. However, it is recommended to install Wisconsin stackwalker library before instrumenting
any benchmark as it provides more accurate stack signatures than ver0 (naive) stackwalk.

Modify the file "makefile" to add the path where Wisconsin stackwalker library was installed.
e.g: If Wisconsin stackwalker library was installed in a local directory called 'Wisc_Stackwalk'
#Wisconsin Stackwalker changes - start
EXTRA_LIBS = -lcommon -lstackwalk -lsymtabAPI 
EXTRA_INCPATHS = -I./Wisc_Stackwalk/stackwalkAPI/src/include
EXTRA_LPATHS = -L. -L./Wisc_Stackwalk/stackwalkAPI/src/x86_64-unknown-linux2.4/lib
EXTRA_FLAGS = -Wall
#Wisconsin Stackwalker changes - end


3) Copy unzipped folder "ScalaMemTrace" to the folder /home/.../pin-2.7-31933-gcc.3.4.6-ia32_intel64-linux/source/tools/
inside Pin.

4) run $cd /home/.../pin-2.7-31933-gcc.3.4.6-ia32_intel64-linux/source/tools/ScalaMemTrace

5) run $make - this builds Memtrace Pin tool (.../obj_intel64/memtrace.so) ONLY.

6) To instrument binaries and generate traces, run the following command
mpirun -np 4 ../../../intel64/bin/pinbin -t ./obj-intel64/memtrace.so -- ./thread_sample_omp
Here, thread_sample_omp is the benchmark(executable) being instrumented. The traces will be saved in
trace<NUM>.txt, where <NUM> starts from 0 to (no. of processes - 1). For example, in the above command,
there are 4 MPI processes resulting in 4 trace files - trace0.txt, trace1.txt, ... trace3.txt.
These trace files can be created as pipes using "mknod" command if traces are to be read by the
compressor on the fly. The EPRSD compressor reads these files to generate EPRSD compressed files.
Building the EPRSD compressor is explained in the following section.


//////////////////////////////////////////////////////////////////////////////////
			To build EPRSD compressor
//////////////////////////////////////////////////////////////////////////////////
1) run $make --makefile=prsdcomp.mk
This creates a binary file "prsd_comp".

2)run $mpirun -np 4 prsd_comp > dump
If 4 MPI processes were used to instrument a benchmark and generate traces, use the same
number of MPI processes to run the compressor. The logs are redirected to a file called 
'dump' in this example. The EPRSDs are stored in file "prsd0.txt".

Files: myprsdtlib.h  myqueue.cpp  prsd_comp  prsd_comp.cpp  prsdcomp.mk  replay.cpp  replay.mk  sigt.cpp  types.h


//////////////////////////////////////////////////////////////////////////////////
			To build Replay tool
//////////////////////////////////////////////////////////////////////////////////
1) run $make --makefile=replay.mk

2) run $replay prsd0.txt > dump
The replayed traces are redirected to a file called 'dump'

Files: replay.cpp, myprsdtlib.h, types.h


//////////////////////////////////////////////////////////////////////////////////
			File Information			
//////////////////////////////////////////////////////////////////////////////////
memtrace.cpp -> Pin tool to generate memory traces

To enable the use of Wisconsin stackwalker library, define the following macro and recompile the code.
Ver0 is used if the following macro is not defined.
#define WISC_STACKWALK_ENABLED 1

To enable per-function stackwalk, define the following macro and recompile the code. If the following
macro is not defined, per-instruction stackwalk is used.
#define OPTIMIZED_STACKWALK_ENABLED 1
>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
myprsdtlib.h -> EPRSD template library

To use signature tree implementation, define the following macro and recompile. If not defined, 
normal pair-wise signature comparison is used.
#define SIGTREE_ENABLED

>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
sigt.cpp -> Signature Tree library
prsd_comp.cpp -> MPI implementation of the EPRSD compressor
replay.cpp -> Replay tool
sigtree.cpp -> Sample code to test Signature Tree
myqueue.cpp -> Linked list templates
format.h -> specifies file I/O formats used in fprintf() and fscanf()
types.h -> contains the data types used
