README.md

   1 RISC-V ISA Simulator
   2 ======================
   3
   4 Author  : Andrew Waterman, Yunsup Lee
   5
   6 Date    : June 19, 2011
   7
   8 Version : (under version control)
   9
  10 About
  11 -------------
  12
  13 The RISC-V ISA Simulator implements a functional model of one or more
  14 RISC-V processors.
  15
  16 Build Steps
  17 ---------------
  18
  19 We assume that the RISCV environment variable is set to the RISC-V tools
  20 install path, and that the riscv-fesvr package is installed there.
  21
  22     $ mkdir build
  23     $ cd build
  24     $ ../configure --prefix=$RISCV --with-fesvr=$RISCV
  25     $ make
  26     $ [sudo] make install
  27
  28 Compiling and Running a Simple C Program
  29 -------------------------------------------
  30
  31 Install spike (see Build Steps), riscv-gnu-toolchain, and riscv-pk.
  32
  33 Write a short C program and name it hello.c.  Then, compile it into a RISC-V
  34 ELF binary named hello:
  35
  36     $ riscv64-unknown-elf-gcc -o hello hello.c
  37
  38 Now you can simulate the program atop the proxy kernel:
  39
  40     $ spike pk hello
  41
  42 Simulating a New Instruction
  43 ------------------------------------
  44
  45 Adding an instruction to the simulator requires two steps:
  46
  47   1.  Describe the instruction's functional behavior in the file
  48       riscv/insns/<new_instruction_name>.h.  Examine other instructions
  49       in that directory as a starting point.
  50
  51   2.  Add the opcode and opcode mask to riscv/opcodes.h.  Alternatively,
  52       add it to the riscv-opcodes package, and it will do so for you:
  53
  54          $ cd ../riscv-opcodes
  55          $ vi opcodes       // add a line for the new instruction
  56          $ make install
  57
  58   3.  Rebuild the simulator.
  59
  60 Interactive Debug Mode
  61 ---------------------------
  62
  63 To invoke interactive debug mode, launch spike with -d:
  64
  65     $ spike -d pk hello
  66
  67 To see the contents of an integer register (0 is for core 0):
  68
  69     : reg 0 a0
  70
  71 To see the contents of a floating point register:
  72
  73     : fregs 0 ft0
  74
  75 or:
  76
  77     : fregd 0 ft0
  78
  79 depending upon whether you wish to print the register as single- or double-precision.
  80
  81 To see the contents of a memory location (physical address in hex):
  82
  83     : mem 2020
  84
  85 To see the contents of memory with a virtual address (0 for core 0):
  86
  87     : mem 0 2020
  88
  89 You can advance by one instruction by pressing <enter>. You can also
  90 execute until a desired equality is reached:
  91
  92     : until pc 0 2020                   (stop when pc=2020)
  93     : until mem 2020 50a9907311096993   (stop when mem[2020]=50a9907311096993)
  94
  95 Alternatively, you can execute as long as an equality is true:
  96
  97     : while mem 2020 50a9907311096993
  98
  99 You can continue execution indefinitely by:
 100
 101     : r
 102
 103 At any point during execution (even without -d), you can enter the
 104 interactive debug mode with `<control>-<c>`.
 105
 106 To end the simulation from the debug prompt, press `<control>-<c>` or:
 107
 108     : q