From cccc32fe163726e3744077f96fdfd3d681473a0f Mon Sep 17 00:00:00 2001 From: Luke Wren Date: Sat, 11 Dec 2021 10:09:26 +0000 Subject: [PATCH] Update instructions for running hello world under debugger --- Readme.md | 103 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 36 deletions(-) diff --git a/Readme.md b/Readme.md index ef95d0d..e3cf594 100644 --- 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 ( 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