Update instructions for running hello world under debugger

2021-12-11 10:09:26 +00:00 · 2021-12-11 10:09:26 +00:00 · cccc32fe16
parent abe1769929
commit cccc32fe16
1 changed files with 67 additions and 36 deletions
--- a/Readme.md
+++ b/Readme.md
@ -4,7 +4,7 @@ Hazard3 is a 3-stage RISC-V processor, implementing the `RV32I` instruction set

 * `M`: integer multiply/divide/modulo
 * `C`: compressed instructions
-* `A` : _(experimental)_ atomic memory operations, with AHB5 global exclusives
+* `A` : atomic memory operations, with AHB5 global exclusives
 * `Zicsr`: CSR access
 * `Zba`: address generation
 * `Zbb`: basic bit manipulation
@ -20,8 +20,6 @@ This repository also contains a compliant RISC-V Debug Module for Hazard3, which

 There is an [example SoC integration](example_soc/soc/example_soc.v), showing how these components can be assembled to create a minimal system with a JTAG-enabled RISC-V processor, some RAM and a serial port.

-_Note: the bit manipulation instructions don't have upstream compliance tests at time of writing. See [here](test/sim/bitmanip-random) for my constrained-random bitmanip tests run against spike, the RISC-V ISA simulator._
-
 The following are planned for future implementation:

 * Debug trigger unit (breakpoint-only)
@ -64,7 +62,6 @@ These instructions are for Ubuntu 20.04. You will need:
 - A recent Yosys build to process the Verilog. At least version `c2afcbe7`, which includes a workaround for a gtkwave string parsing issue. Latest master should be fine.
 - A `riscv32-unknown-elf-` toolchain to build software for the core
 - A native `clang` to build the simulator
- (For debug) a recent build of [riscv-openocd](https://github.com/riscv/riscv-openocd) with the `remote-bitbang` protocol enabled. A recent version of upstream openocd should also work.

 ## Yosys

@ -91,22 +88,9 @@ The multilib build is strongly recommended -- getting a RV32IMC standard library

 This build will also install an appropriate gdb as `riscv32-unknown-elf-gdb`.

-## riscv-openocd
-
-```bash
-cd /tmp
-git clone https://github.com/riscv/riscv-openocd.git
-cd riscv-openocd
-./bootstrap
-# Prefix is optional
-./configure --enable-remote-bitbang --enable-ftdi --program-prefix=riscv-
-make -j $(nproc)
-sudo make install
-```
-
 ## Actually Running Hello World

-Build the simulator (CXXRTL):
+Make sure you have done a _recursive_ clone of the Hazard3 repository. Build the CXXRTL-based simulator:

 ```bash
 cd hazard3
@ -128,36 +112,83 @@ All going well you should see something like:

 ```
 $ make
-riscv32-unknown-elf-gcc -march=rv32imc -Os ../common/init.S main.c -T ../common/memmap.ld -I../common -o hellow.elf
-riscv32-unknown-elf-objcopy -O binary hellow.elf hellow.bin
-riscv32-unknown-elf-objdump -h hellow.elf > hellow.dis
-riscv32-unknown-elf-objdump -d hellow.elf >> hellow.dis
-../tb_cxxrtl/tb hellow.bin hellow_run.vcd --cycles 100000
+mkdir -p tmp/
+riscv32-unknown-elf-gcc -march=rv32imc -Os ../common/init.S main.c -T ../common/memmap.ld -I../common -o tmp/hellow.elf
+riscv32-unknown-elf-objcopy -O binary tmp/hellow.elf tmp/hellow.bin
+riscv32-unknown-elf-objdump -h tmp/hellow.elf > tmp/hellow.dis
+riscv32-unknown-elf-objdump -d tmp/hellow.elf >> tmp/hellow.dis
+../tb_cxxrtl/tb --bin tmp/hellow.bin --vcd tmp/hellow_run.vcd --cycles 100000
 Hello world from Hazard3 + CXXRTL!
 CPU requested halt. Exit code 123
-Ran for 638 cycles
+Ran for 601 cycles
 ```

-This will have created a waveform dump called `hellow_run.vcd` which you can view with GTKWave:
+This will have created a waveform dump called `tmp/hellow_run.vcd` which you can view with GTKWave:

 ```bash
-gtkwave hellow_run.vcd
+gtkwave tmp/hellow_run.vcd
 ```

-## Loading Hello World with Debugger
+# Loading Hello World with the Debugger

-Build a simulator with debug hardware included
+Invoking the simulator built in the previous step, with no arguments, shows the following usage message:
+
+```
+$ ./tb 
+At least one of --bin or --port must be specified.
+Usage: tb [--bin x.bin] [--vcd x.vcd] [--dump start end] [--cycles n] [--port n]
+    --bin x.bin      : Flat binary file loaded to address 0x0 in RAM
+    --vcd x.vcd      : Path to dump waveforms to
+    --dump start end : Print out memory contents from start to end (exclusive)
+                       after execution finishes. Can be passed multiple times.
+    --cycles n       : Maximum number of cycles to run before exiting.
+                       Default is 0 (no maximum).
+    --port n         : Port number to listen for openocd remote bitbang. Sim
+                       runs in lockstep with JTAG bitbang, not free-running.
+```
+
+This simulator contains:
+
+- Hardware:
+	- The processor
+	- A Debug Module (DM)
+	- A JTAG Debug Transport Module (DTM)
+- Software:
+	- RAM model
+	- Routines for loading binary files, dumping VCDs
+	- Routines for bitbanging the JTAG DTM through a TCP socket
+
+Running hello world in the previous section used the `--bin` argument to load the linked hello world executable directly into the testbench's RAM. If we invoke the simulator with the `--port` argument, it will instead wait for a connection on that port, and then accept JTAG bitbang commands in OpenOCD's `remote-bitbang` format. The simulation runs in lockstep with the JTAG bitbanging, for more predictable results.
+
+We need to build a copy of `riscv-openocd` before going any further. OpenOCD's role is to translate the abstract debug commands issued by gdb, e.g. "set the program counter to address `x`", to more concrete operations, e.g. "shift this JTAG DR".
+
+## Building riscv-openocd
+
+We need a recent build of [riscv-openocd](https://github.com/riscv/riscv-openocd) with the `remote-bitbang` protocol enabled.

 ```bash
-# hazard3/test/sim/openocd
-cd ../openocd
-make
+cd /tmp
+git clone https://github.com/riscv/riscv-openocd.git
+cd riscv-openocd
+./bootstrap
+# Prefix is optional
+./configure --enable-remote-bitbang --enable-ftdi --program-prefix=riscv-
+make -j $(nproc)
+sudo make install
 ```

-You're going to want three terminal tabs in this directory. In the first of them type:
+## Loading and Running

+You're going to want three terminal tabs in the `tb_cxxrtl` directory.
+
+```bash
+cd hazard3/test/sim/tb_cxxrtl
 ```
-./tb
+
+In the first of them type:
+
+```bash
+./tb --port 9824
 ```

 You should see something like
@ -166,7 +197,7 @@ You should see something like
 Waiting for connection on port 9824
 ```

-The simulation won't start until openocd connects to the JTAG bitbang socket. In your second terminal in the same directory, start riscv-openocd:
+The simulation will start once OpenOCD connects. In your second terminal in the same directory, start riscv-openocd:

 ```bash
 riscv-openocd -f openocd.cfg
@ -183,7 +214,7 @@ Info : JTAG tap: hazard3.cpu tap/device found: 0xdeadbeef (mfg: 0x777 (<unknown>
 Info : datacount=1 progbufsize=2
 Info : Disabling abstract command reads from CSRs.
 Info : Examined RISC-V core; found 1 harts
-Info :  hart 0: XLEN=32, misa=0x40001104
+Info :  hart 0: XLEN=32, misa=0x40801105
 Info : starting gdb server for hazard3.cpu on 3333
 Info : Listening on port 3333 for gdb connections
 Info : Listening on port 6666 for tcl connections
@ -199,7 +230,7 @@ set confirm off
 # Connect to openocd on its default port:
 target extended-remote localhost:3333
 # Load hello world, and check that it loaded correctly
-file ../hellow/hellow.elf
+file ../hellow/tmp/hellow.elf
 load
 compare-sections
 # The processor will quit the simulation when after returning from main(), by