Wavelet-Based Phase Classification
Ted Huffmire and Tim Sherwood
PACT 2006

This file describes how to use our wavelet-based
phase classification method. The file src.tar.gz
contains an archive of this directory.

1) The first step of the design flow is to use Pin to
instrument an application. The source code of our
pintool is contained in the file pintool.C
Our pintool outputs a trace of the memory accesses.
Since Linux does not allow files to be larger than 2GB,
we break the traces into a numbered sequence of files
that are roughly 600MB in size (about the size of a CD-ROM).

The format of the trace files is the following:
Instructions_Executed_Thus_Far Instruction_Pointer Memory_Address Size
For example:
8 0x45a76b 0x4bd960 4
(Note that the fields are space-delimited.)

For more information about installing and using Pin, 
visit their web site at the following URL: 
http://rogue.colorado.edu/pin/

2) The next step of the design flow is to analyze the trace file,
counting the number of L2 misses in each interval of execution.
The program "bb3" outputs this analysis:

% wget http://www.gurge.com/amd/old/java/GIFEncoder/src/GIFEncoder.java

% wget java.sun.com/developer/technicalArticles/Programming/sprintf/PrintfFormat.java

% javac *.java

% cat trace.out.gz | gunzip | java -ms512m -mx512m bb3 > trace.pc

3) The next step is to generate the "pictures" of the memory
phases. It clearly would have been more efficient to combine
steps 2) and 3) so that we only need to analyze the trace file once.

% cat trace.out.gz | gunzip | java -ms512m -mx512m cache NUM_INSTRUCTIONS

The number NUM_INSTRUCTIONS is the total number of instructions in the
trace file. You can determine this number by looking at the
last line of the trace file:

% cat trace.out.gz | gunzip | tail

The program should output two files, access_intensity.gif and 
l2intensity.gif. These are pictures of the memory accesses and L2 misses, 
respectively. The picture of the L2 misses is not needed by our
wavelet-based phase classification scheme, but it is useful 
for visualizing the L2 miss phases.

4) The next step is to analyze the picture of the memory accesses
using our wavelet-based scheme. You will need to have your 
X11 DISPLAY variable properly set.

% java app access_intensity.gif trace.pc

This will produce a file, wavelet.labels

5) Now we are ready to calculate the weighted standard deviation.

% java cov trace.pc wavelet.labels

6) The last step is optional. You may want to add color
to the picture of the memory accesses. The following
program assigns a unique color to each interval:

% java -ms512m -mx512m color_trace wavelet.labels access_intensity.gif 20

This will output a file, colorful.gif.
Rename this file to colorful_access.gif.
You can also add color to the picture of the L2 misses:

% java -ms512m -mx512m color_trace wavelet.labels l2intensity.gif 20

This will again output a file, colorful.gif.
Rename this file to colorful_l2.gif.