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     $ apt-get install device-tree-compiler
  23     $ mkdir build
  24     $ cd build
  25     $ ../configure --prefix=$RISCV --with-fesvr=$RISCV
  26     $ make
  27     $ [sudo] make install
  28
  29 Compiling and Running a Simple C Program
  30 -------------------------------------------
  31
  32 Install spike (see Build Steps), riscv-gnu-toolchain, and riscv-pk.
  33
  34 Write a short C program and name it hello.c.  Then, compile it into a RISC-V
  35 ELF binary named hello:
  36
  37     $ riscv64-unknown-elf-gcc -o hello hello.c
  38
  39 Now you can simulate the program atop the proxy kernel:
  40
  41     $ spike pk hello
  42
  43 Simulating a New Instruction
  44 ------------------------------------
  45
  46 Adding an instruction to the simulator requires two steps:
  47
  48   1.  Describe the instruction's functional behavior in the file
  49       riscv/insns/<new_instruction_name>.h.  Examine other instructions
  50       in that directory as a starting point.
  51
  52   2.  Add the opcode and opcode mask to riscv/opcodes.h.  Alternatively,
  53       add it to the riscv-opcodes package, and it will do so for you:
  54
  55          $ cd ../riscv-opcodes
  56          $ vi opcodes       // add a line for the new instruction
  57          $ make install
  58
  59   3.  Rebuild the simulator.
  60
  61 Interactive Debug Mode
  62 ---------------------------
  63
  64 To invoke interactive debug mode, launch spike with -d:
  65
  66     $ spike -d pk hello
  67
  68 To see the contents of an integer register (0 is for core 0):
  69
  70     : reg 0 a0
  71
  72 To see the contents of a floating point register:
  73
  74     : fregs 0 ft0
  75
  76 or:
  77
  78     : fregd 0 ft0
  79
  80 depending upon whether you wish to print the register as single- or double-precision.
  81
  82 To see the contents of a memory location (physical address in hex):
  83
  84     : mem 2020
  85
  86 To see the contents of memory with a virtual address (0 for core 0):
  87
  88     : mem 0 2020
  89
  90 You can advance by one instruction by pressing <enter>. You can also
  91 execute until a desired equality is reached:
  92
  93     : until pc 0 2020                   (stop when pc=2020)
  94     : until mem 2020 50a9907311096993   (stop when mem[2020]=50a9907311096993)
  95
  96 Alternatively, you can execute as long as an equality is true:
  97
  98     : while mem 2020 50a9907311096993
  99
 100 You can continue execution indefinitely by:
 101
 102     : r
 103
 104 At any point during execution (even without -d), you can enter the
 105 interactive debug mode with `<control>-<c>`.
 106
 107 To end the simulation from the debug prompt, press `<control>-<c>` or:
 108
 109     : q
 110
 111 Debugging With Gdb
 112 ------------------
 113
 114 An alternative to interactive debug mode is to attach using gdb. When invoked
 115 with '--gdb-port <port>' spike will listen on the given TCP port.  It's
 116 possible to attach with gdb (that has riscv support compiled in) by entering
 117 `target remote localhost:<port>` in gdb. For example, in one shell run:
 118 ```
 119 spike --gdb-port 9824 pk tests/debug
 120 ```
 121
 122 Then in a second shell you may do something like:
 123 ```
 124 tnewsome@compy-vm:~/SiFive/riscv-isa-sim$ $RISCV/bin/riscv64-unknown-elf-gdb tests/debug
 125 GNU gdb (GDB) 7.11.50.20160212-git
 126 Copyright (C) 2016 Free Software Foundation, Inc.
 127 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 128 This is free software: you are free to change and redistribute it.
 129 There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
 130 and "show warranty" for details.
 131 This GDB was configured as "--host=x86_64-pc-linux-gnu --target=riscv64-unknown-elf".
 132 Type "show configuration" for configuration details.
 133 For bug reporting instructions, please see:
 134 <http://www.gnu.org/software/gdb/bugs/>.
 135 Find the GDB manual and other documentation resources online at:
 136 <http://www.gnu.org/software/gdb/documentation/>.
 137 For help, type "help".
 138 Type "apropos word" to search for commands related to "word"...
 139 Reading symbols from tests/debug...done.
 140 (gdb) target remote localhost:9824
 141 Remote debugging using localhost:9824
 142 0x00000000000101f0 in main ()
 143     at /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c:20
 144 20          while (i)
 145 (gdb) p i
 146 $1 = 42
 147 (gdb) list
 148 15          volatile int i = 42;
 149 16          const char *text = "constant\n";
 150 17          int threshold = 7;
 151 18
 152 19          // Wait for the debugger to get us out of this loop.
 153 20          while (i)
 154 21              ;
 155 22
 156 23          printf("%s", text);
 157 24          for (int y=0; y < 10; y++) {
 158 (gdb) p i=0
 159 $2 = 0
 160 (gdb) b print_row
 161 Breakpoint 1 at 0x10178: file /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c, line 7.
 162 (gdb) c
 163 Continuing.
 164
 165 Breakpoint 1, print_row (length=0)
 166     at /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c:7
 167 7           for (int x=0; x<length; x++) {
 168 (gdb) c
 169 Continuing.
 170
 171 Breakpoint 1, print_row (length=1)
 172     at /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c:7
 173 7           for (int x=0; x<length; x++) {
 174 (gdb) delete breakpoints
 175 Delete all breakpoints? (y or n) y
 176 (gdb) c
 177 Continuing.
 178 Remote connection closed
 179 (gdb)
 180 ```