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 G=$GUEST H=$HOST
  31 ```
  32
  33 Allowed GUEST values: riscv64, ppc or ppc64.
  34 Allowed HOST values: amd64.
  35
  36 will create the following files:
  37 ```
  38     ~/bin/caveat       - instruction set interpreter
  39     ~/bin/traceinfo    - prints and summarizes trace from caveat
  40     ~/bin/pipesim      - very simple pipelined machine simulator
  41     ~/bin/cachesim     - general cache simulator, can be L1, L2, I, D, I+D...
  42 ```
  43
  44 In addition, header files are installed in
  45 ```
  46     ~/include/cava/
  47 ```
  48 and the caveat trace handling library in
  49 ```
  50     ~/lib/libcava.a
  51 ```
  52
  53
  54 ###  Running Cavatools
  55
  56 Programs should be compiled -static using riscv-gnu-toolchain Linux libc:
  57 ```
  58     $ riscv64-unknown-linux-gnu-gcc -static ... testpgm.c -o testpgm
  59 ```
  60
  61 To run without tracing:
  62 ```
  63     $ caveat testpgm <any number of flags and arguments to testpgm>
  64 ```
  65
  66 To see instruction trace run this in one window:
  67 ```
  68     $ caveat --out=bufname testpgm <any number of flags and arguments to testpgm>
  69 ```
  70 and this in another window:
  71 ```
  72     $ traceinfo --in=bufname --list testpgm
  73 ```
  74 The shared memory buffer 'bufname' appears in /dev/shm while processes are running.
  75
  76 There is a pipeline simulator and a cache simulator.  Run the following command lines in separate windows for more clarity:
  77 ```
  78     $ caveat --trace=b1 testpgm &
  79     $ pipesim --in=b1 --out=b2 --visible testpgm &
  80     $ cachesim --in=b2 --out=b3 --filter=rw &
  81     $ traceinfo --in=b3 --paraver=10000 --cutoff=3 testgpm > trace.prv
  82 ```
  83 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.
  84
  85 In the future there will be a presentation slide deck and a brief paper describing
  86 how to use the example analysis tools.