X-Git-Url: https://git.libre-soc.org/?p=riscv-isa-sim.git;a=blobdiff_plain;f=README.md;h=018c7d3eadfe823050eb18862d14c6fa5aa0b9fb;hp=ce078b3589b8e53fa06f7a62d362e3aedf1733f0;hb=HEAD;hpb=092f378fb207d9378118c8b39c90f2b45833c862

diff --git a/README.md b/README.md
index ce078b3..018c7d3 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,22 @@
-RISC-V ISA Simulator
-======================
-
-Author  : Andrew Waterman, Yunsup Lee
-
-Date    : June 19, 2011
-
-Version : (under version control)
+Spike RISC-V ISA Simulator
+============================
 
 About
 -------------
 
-The RISC-V ISA Simulator implements a functional model of one or more
+Spike, the RISC-V ISA Simulator, implements a functional model of one or more
 RISC-V processors.
 
+Spike is named after the golden spike used to celebrate the completion of the
+US transcontinental railway.
+
 Build Steps
 ---------------
 
 We assume that the RISCV environment variable is set to the RISC-V tools
 install path, and that the riscv-fesvr package is installed there.
 
+    $ apt-get install device-tree-compiler
     $ mkdir build
     $ cd build
     $ ../configure --prefix=$RISCV --with-fesvr=$RISCV
@@ -67,15 +65,15 @@ To invoke interactive debug mode, launch spike with -d:
 To see the contents of an integer register (0 is for core 0):
 
     : reg 0 a0
-    
+
 To see the contents of a floating point register:
 
     : fregs 0 ft0
-    
+
 or:
-  
+
     : fregd 0 ft0
-    
+
 depending upon whether you wish to print the register as single- or double-precision.
 
 To see the contents of a memory location (physical address in hex):
@@ -106,3 +104,120 @@ interactive debug mode with `<control>-<c>`.
 To end the simulation from the debug prompt, press `<control>-<c>` or:
 
     : q
+
+Debugging With Gdb
+------------------
+
+An alternative to interactive debug mode is to attach using gdb. Because spike
+tries to be like real hardware, you also need OpenOCD to do that. OpenOCD
+doesn't currently know about address translation, so it's not possible to
+easily debug programs that are run under `pk`. We'll use the following test
+program:
+```
+$ cat rot13.c 
+char text[] = "Vafgehpgvba frgf jnag gb or serr!";
+
+// Don't use the stack, because sp isn't set up.
+volatile int wait = 1;
+
+int main()
+{
+    while (wait)
+        ;
+
+    // Doesn't actually go on the stack, because there are lots of GPRs.
+    int i = 0;
+    while (text[i]) {
+        char lower = text[i] | 32;
+        if (lower >= 'a' && lower <= 'm')
+            text[i] += 13;
+        else if (lower > 'm' && lower <= 'z')
+            text[i] -= 13;
+        i++;
+    }
+
+    while (!wait)
+        ;
+}
+$ cat spike.lds 
+OUTPUT_ARCH( "riscv" )
+
+SECTIONS
+{
+  . = 0x10010000;
+  .text : { *(.text) }
+  .data : { *(.data) }
+}
+$ riscv64-unknown-elf-gcc -g -Og -o rot13-64.o -c rot13.c
+$ riscv64-unknown-elf-gcc -g -Og -T spike.lds -nostartfiles -o rot13-64 rot13-64.o
+```
+
+To debug this program, first run spike telling it to listen for OpenOCD:
+```
+$ spike --rbb-port=9824 -m0x10000000:0x20000 rot13-64
+Listening for remote bitbang connection on port 9824.
+```
+
+In a separate shell run OpenOCD with the appropriate configuration file:
+```
+$ cat spike.cfg 
+interface remote_bitbang
+remote_bitbang_host localhost
+remote_bitbang_port 9824
+
+set _CHIPNAME riscv
+jtag newtap $_CHIPNAME cpu -irlen 5 -expected-id 0x10e31913
+
+set _TARGETNAME $_CHIPNAME.cpu
+target create $_TARGETNAME riscv -chain-position $_TARGETNAME
+
+gdb_report_data_abort enable
+
+init
+halt
+$ openocd -f spike.cfg
+Open On-Chip Debugger 0.10.0-dev-00002-gc3b344d (2017-06-08-12:14)
+...
+riscv.cpu: target state: halted
+```
+
+In yet another shell, start your gdb debug session:
+```
+tnewsome@compy-vm:~/SiFive/spike-test$ riscv64-unknown-elf-gdb rot13-64
+GNU gdb (GDB) 7.12.50.20170505-git
+Copyright (C) 2016 Free Software Foundation, Inc.
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
+and "show warranty" for details.
+This GDB was configured as "--host=x86_64-pc-linux-gnu --target=riscv64-unknown-elf".
+Type "show configuration" for configuration details.
+For bug reporting instructions, please see:
+<http://www.gnu.org/software/gdb/bugs/>.
+Find the GDB manual and other documentation resources online at:
+<http://www.gnu.org/software/gdb/documentation/>.
+For help, type "help".
+Type "apropos word" to search for commands related to "word"...
+Reading symbols from rot13-64...done.
+(gdb) target remote localhost:3333
+Remote debugging using localhost:3333
+0x000000001001000a in main () at rot13.c:8
+8           while (wait)
+(gdb) print wait
+$1 = 1
+(gdb) print wait=0
+$2 = 0
+(gdb) print text
+$3 = "Vafgehpgvba frgf jnag gb or serr!"
+(gdb) b 23
+Breakpoint 1 at 0x10010064: file rot13.c, line 23.
+(gdb) c
+Continuing.
+
+Breakpoint 1, main () at rot13.c:23
+23          while (!wait)
+(gdb) print wait
+$4 = 0
+(gdb) print text
+...
+```