README.md

   1 # cavatools
   2 RISC-V instruction set simulator and performance analysis tools
   3 ===============================================================
   4
   5 An instruction-set interpretator that produces execution trace in shared memory,
   6 and an example collection of simulators and analysis programs for pipeline and cache
   7 performance evaluation.  You can write your own simulation/analysis programs.
   8 Cavatools can also be retargetted to other RISC-like architectures.
   9
  10
  11 ###  Getting the sources
  12
  13 The repository is on GitHub:
  14     $ git clone https://github.com/pete2222/cavatools
  15
  16
  17
  18 ###  Prerequisites
  19
  20 The Berkeley Softfloat-3e package has been included in this repository.
  21 Make install expects ~/bin, ~/lib, ~/include to exit.
  22
  23
  24
  25 ###  Installation
  26
  27 To build Cavatools:
  28 ```
  29     $ cd cavatools
  30     $ make install
  31 ```
  32
  33 will create the following files:
  34 ```
  35     ~/bin/caveat       - instruction set interpreter
  36     ~/bin/traceinfo    - prints and summarizes trace from caveat
  37     ~/bin/pipesim      - very simple pipelined machine simulator
  38     ~/bin/cachesim     - general cache simulator, can be L1, L2, I, D, I+D...
  39 ```
  40
  41 In addition, header files are installed in
  42 ```
  43     ~/include/cava/
  44 ```
  45 and the caveat trace handling library in
  46 ```
  47     ~/lib/libcava.a
  48 ```
  49
  50
  51 ###  Running Cavatools
  52
  53 Programs should be compiled -static using riscv-gnu-toolchain Linux libc:
  54 ```
  55     $ riscv64-unknown-linux-gnu-gcc -static ... testpgm.c -o testpgm
  56 ```
  57
  58 To run without tracing:
  59 ```
  60     $ caveat testpgm <any number of flags and arguments to testpgm>
  61 ```
  62
  63 To see instruction trace run this in one window:
  64 ```
  65     $ caveat --out=bufname testpgm <any number of flags and arguments to testpgm>
  66 ```
  67 and this in another window:
  68 ```
  69     $ traceinfo --in=bufname --list testpgm
  70 ```
  71 The shared memory buffer 'bufname' appears in /dev/shm while processes are running.
  72
  73 There is a pipeline simulator and a cache simulator.  Run the following command lines in separate windows for more clarity:
  74 ```
  75     $ caveat --trace=b1 testpgm &
  76     $ pipesim --in=b1 --out=b2 --visible testpgm &
  77     $ cachesim --in=b2 --out=b3 --filter=rw &
  78     $ traceinfo --in=b3 --paraver=10000 --cutoff=3 testgpm > trace.prv
  79 ```
  80 produces a BSC Paraver trace of 10000 cycles with instruction stall events of 3 or more cycles, plus all cache misses.  In this simulation pipesim has a built-in L1 data cache, and cachesim is modeling an L2 cache, all with default parameters.
  81
  82 In the future there will be a presentation slide deck and a brief paper describing
  83 how to use the example analysis tools.