# Welcome to the 2nd Cache Replacement Championship!

If you have not already done so, plase join the CRC-2 mailing 
list by sending an empty email to:

crc-2+subscribe@googlegroups.com

You do not need to have a Google email account - you only need to 
subscribe to the mailing list. When prompted, type in your email
address that you want use for the CRC-2 subscription.

This mailing list will be used for any announcements regarding the 
competition, any simulation infrastructure updates, and participants 
may post questions or report problems.

You must provide a single .cc (or .c) file for your replacement policy.  
There are two example replacement policies (LRU and SRRIP [Jaleel et al. ISCA '10]) 
in the example directory. Refer to them to learn how to interface with 
the Champsim Simulator.

# How to compile

For the championship, your replacement policy's performance will be measured in 
four configurations:

1. Single core with 2MB LLC without a prefetcher (lib/config1.a)
2. Single core with 2MB LLC with L1/L2 data prefetchers (lib/config2.a)
3. A 4-core configuration with 8MB of shared LLC without a prefetcher (lib/config3.a)
4. A 4-core configuration with 8MB of shared LLC with L1/L2 data prefetchers (lib/config4.a)

We also provide config5 and config6 that have a larger 8MB LLC on config1 
and config2 respectively. You can use these configurations to calculate the 
normalized weighted speedup for multi-core system. Note that config5 and config6 
will not be tested in the final competition.

Compile your replacement policy file with pre-compiled libraries:
```
$ g++ -Wall --std=c++11 -o lru-config1 example/lru.cc lib/config1.a
$ g++ -Wall --std=c++11 -o lru-config2 example/lru.cc lib/config2.a
$ g++ -Wall --std=c++11 -o lru-config3 example/lru-8MB.cc lib/config3.a
$ g++ -Wall --std=c++11 -o lru-config4 example/lru-8MB.cc lib/config4.a
$ g++ -Wall --std=c++11 -o lru-config5 example/lru-8MB.cc lib/config5.a
$ g++ -Wall --std=c++11 -o lru-config6 example/lru-8MB.cc lib/config6.a
```
We used g++ (Ubuntu 4.8.4-2ubuntu1~14.04.3) to compile the example codes. 

# How to run

The ChampSim Simulator requires three parameters:

-warmup_instructions <number>
Use this to specify the length of the warmup period. After the warmup
period is over, the IPC statistics are reset, and the final reported
IPC metric will be calculated starting at this point.
Default value is 1,000,000.

-simulation_instructions <number>
Use this to specify how many instructions you want to execute after the
warmup period is over. After the simulation period is over, the simulator
will exit and IPC since the warmup period will be printed.
Default value is 10,000,000.

-hide_heartbeat
Use this to hide the heartbeat information that shows up every 1,000,000
instructions.

-traces
Use this to specify the instruction traces generated by using the ChampSim PIN tool.
For 4-core you must specify the name of trace files individually. 

For example, to run a single-core simulation using the default LRU replacement algorithm:
```
$ g++ -Wall --std=c++11 -o lru-config1 example/lru.cc lib/config1.a
$ ./lru-config1 -warmup_instructions 1000000 -simulation_instructions 10000000 -traces trace/bzip2_10M.trace.gz
```

To run a 4-core simulation using the LRU replacement algorithm:
```
$ g++ -Wall --std=c++11 -o lru-config3 example/lru-8MB.cc lib/config3.a
$ ./lru-config3 -warmup_instructions 1000000 -simulation_instructions 10000000 -traces trace/bzip2_10M.trace.gz trace/mcf_10M.trace.gz trace/libquantum_10M.trace.gz trace/xalancbmk_10M.trace.gz
```

# How to create traces

We have included 5 example traces, four from SPEC CPU 2006 and one from CloudSuite 2.0. 
These traces are short (10 million instructions), and do not necessarily cover the range of 
behaviors your replacement algorithm will likely see in the full competition trace list 
(not included). We STRONGLY recommend creating your own traces, covering
a wide variety of program types and behaviors.

You need to download Pin 3.0 (pin-3.0-76991-gcc-linux), and may require 
installing libdwarf.so, libelf.so, or other libraries, if you do not already 
have them. Please refer to the following link to download Pin 3.0.

https://software.intel.com/en-us/articles/pin-a-dynamic-binary-instrumentation-tool
https://software.intel.com/sites/landingpage/pintool/docs/76991/Pin/html/

The included Pin Tool tracer file (trace/champsim_tracer.cpp) can be used to generate new 
traces. Compile the tracer file with trace/make_tracer.sh and use your Pin Tool as follows.

**Use the Pin tool like this**
```
$ pin -t /path/to/ChampSim/tracer/obj-intel64/champsim_tracer.so -- <your program here>
```

The tracer has three options you can set:
```
-o
Specify the output file for your trace.
The default is champsim.trace

-s <number>
Specify the number of instructions to skip in the program before tracing begins.
The default value is 0.

-t <number>
The number of instructions to trace, after -s instructions have been skipped.
The default value is 1,000,000.
```
For example, you could trace 200,000 instructions of the program ls, after
skipping the first 100,000 instructions, with this command:
```
pin -t /path/to/ChampSim/tracer/obj-intel64/champsim_tracer.so -o traces/ls.trace -s 100000 -t 200000 -- ls
gzip ls.trace
```
Traces created with the champsim_tracer.so are 64 bytes per instruction,
but they generally compress down to 2-10 bytes per instruction using gzip.
ChampSim takes a gzip file as input with -traces argument.