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
 109
 110 Debugging With Gdb
 111 ------------------
 112
 113 An alternative to interactive debug mode is to attach using gdb. When invoked
 114 with '--gdb-port <port>' spike will listen on the given TCP port.  It's
 115 possible to attach with gdb (that has riscv support compiled in) by entering
 116 `target remote localhost:<port>` in gdb. For example, in one shell run:
 117 ```
 118 spike --gdb-port 9824 pk tests/debug
 119 ```
 120
 121 Then in a second shell you may do something like:
 122 ```
 123 tnewsome@compy-vm:~/SiFive/riscv-isa-sim$ $RISCV/bin/riscv64-unknown-elf-gdb tests/debug
 124 GNU gdb (GDB) 7.11.50.20160212-git
 125 Copyright (C) 2016 Free Software Foundation, Inc.
 126 License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
 127 This is free software: you are free to change and redistribute it.
 128 There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
 129 and "show warranty" for details.
 130 This GDB was configured as "--host=x86_64-pc-linux-gnu --target=riscv64-unknown-elf".
 131 Type "show configuration" for configuration details.
 132 For bug reporting instructions, please see:
 133 <http://www.gnu.org/software/gdb/bugs/>.
 134 Find the GDB manual and other documentation resources online at:
 135 <http://www.gnu.org/software/gdb/documentation/>.
 136 For help, type "help".
 137 Type "apropos word" to search for commands related to "word"...
 138 Reading symbols from tests/debug...done.
 139 (gdb) target remote localhost:9824
 140 Remote debugging using localhost:9824
 141 0x00000000000101f0 in main ()
 142     at /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c:20
 143 20          while (i)
 144 (gdb) p i
 145 $1 = 42
 146 (gdb) list
 147 15          volatile int i = 42;
 148 16          const char *text = "constant\n";
 149 17          int threshold = 7;
 150 18
 151 19          // Wait for the debugger to get us out of this loop.
 152 20          while (i)
 153 21              ;
 154 22
 155 23          printf("%s", text);
 156 24          for (int y=0; y < 10; y++) {
 157 (gdb) p i=0
 158 $2 = 0
 159 (gdb) b print_row
 160 Breakpoint 1 at 0x10178: file /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c, line 7.
 161 (gdb) c
 162 Continuing.
 163
 164 Breakpoint 1, print_row (length=0)
 165     at /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c:7
 166 7           for (int x=0; x<length; x++) {
 167 (gdb) c
 168 Continuing.
 169
 170 Breakpoint 1, print_row (length=1)
 171     at /home/tnewsome/SiFive/riscv-isa-sim/tests/debug.c:7
 172 7           for (int x=0; x<length; x++) {
 173 (gdb) delete breakpoints
 174 Delete all breakpoints? (y or n) y
 175 (gdb) c
 176 Continuing.
 177 Remote connection closed
 178 (gdb)
 179 ```