QemuVectorTestingAndDebugging.md

# Qemu Vector Testing and Debugging

1. [Qemu Setup](#qemu-setup)
	1. [Build steps:](#build-steps)
	2. [Start Qemu](#start-qemu)
	3. [Exiting Qemu](#exiting-qemu)
2. [Running GDB](#running-gdb)
	1. [Use the following command to run GDB](#use-the-following-command-to-run-gdb)
3. [GDBGUI Setup](#gdbgui-setup)
	1. [Installing gdbgui](#installing-gdbgui)
	2. [Running gdbgui](#running-gdbgui)
	3. [gdbgui window](#gdbgui-window)
4. [GDB Usage](#gdb-usage)
	1. [Some Useful GDB instructions](#some-useful-gdb-instructions)
5. [Aliases for convenience](#aliases-for-convenience)
6. [Advanced Usage](#advanced-usage)
	1. [Debugging Qemu](#debugging-qemu)

## Qemu Setup

### Build steps:

```
source build/setup.sh
m tools
m qemu
```

### Start Qemu

Use the following command to start qemu with debugging:

```
qemu-system-riscv32 -M opentitan -kernel $ROOTDIR/out/shodan/build-out/sw_shodan/device/examples/hello_vector/hello_vector_sim_verilator.elf -bios $ROOTDIR/out/shodan/build-bin/sw/device/boot_rom/boot_rom_fpga_nexysvideo.elf  -nographic -cpu rv32,x-v=true,vlen=512,vext_spec=v1.0 -s -S
```

Notes on above command:

-  `-s` - starts the gdb server
-  `-S` - waits on execution for a client to connect

The above commands can be omitted to run qemu without starting a gdb server.

### Exiting Qemu

To exit qemu, in the same teriminal, press `Ctrl-a` then `Ctrl-x`.

## Running GDB

### Use the following command to run GDB

Run GDB to create a gdb session in the CLI:

```
$ROOTDIR/cache/toolchain_vp/bin/riscv32-unknown-elf-gdb $ROOTDIR/out/shodan/build-bin/sw/device/examples/hello_vector/hello_vector_sim_verilator.elf --eval-command "target remote :1234"
```

## GDBGUI Setup

### Installing gdbgui

`python3 -m pip install gdbgui`

### Running gdbgui

Use the following command to begin gdbgui:

```
export PURE_PYTHON=1; gdbgui -g "$ROOTDIR/out/host/toolchain_vp/bin/riscv32-unknown-elf-gdb $ROOTDIR/out/shodan/build-bin/sw/device/examples/hello_vector/hello_vector_sim_verilator.elf --eval-command \"target remote :1234\""
```

### gdbgui window

lower left window takes conventional gdb commands.

To start, set up a breakpoint (e.g. `b main`), then hit continue (`c`)

![image of gdbgui](./gdbgui.png)

## GDB Usage

With one of the gdb methods working, you can now step through and check
register contents.

### Some Useful GDB instructions

- `break main` (or `b main` for short) - makes a breakpoint at the main, more
  info [here](https://ftp.gnu.org/old-gnu/Manuals/gdb/html_node/gdb_27.html)
- `continue` (or `c` for short) - runs until breakpoint
- `step` (or `s` for short) - runs one more line, will "step into" subroutines
- `next` (or `n` for short) - runs one more line, will "step over" subroutines
- `info reg` - print all registers
- `info reg a1` - print scalar register a1
- `info vector` - print all vector registers and vector csr's

## Aliases for convenience

First source `build/setup.sh` to set up the enviroment in the respective
terminal, and then these aliases can speed up the workflow:

```
alias run_gdb="$ROOTDIR/cache/toolchain_vp/bin/riscv32-unknown-elf-gdb $ROOTDIR/out/shodan/build-bin/sw/device/examples/hello_vector/hello_vector_sim_verilator.elf --eval-command \"target remote :1234\""
alias run_gdb_gui="export PURE_PYTHON=1; gdbgui -g '$ROOTDIR/cache/toolchain_vp/bin/riscv32-unknown-elf-gdb $ROOTDIR/out/shodan/build-bin/sw/device/examples/hello_vector/hello_vector_sim_verilator.elf --eval-command \"target remote :1234\"'"
alias run_qemu="qemu-system-riscv32 -M opentitan -kernel $ROOTDIR/out/shodan/build-out/sw_shodan/device/examples/hello_vector/hello_vector_sim_verilator.elf -bios $ROOTDIR/out/shodan/build-bin/sw/device/boot_rom/boot_rom_fpga_nexysvideo.elf  -nographic -cpu rv32,x-v=true,vlen=512,vext_spec=v1.0 -s -S"
```

## Advanced Usage

### Debugging Qemu

```
gdb --eval-command "b helper_vsetvl" --eval-command "run" --args qemu-system-riscv32 -s -S -nographic -cpu rv32,x-v=true,vlen=512,vext_spec=v1.0,s=true,mmu=true  -M opentitan -kernel out/shodan/build-out/sw_shodan/device/examples/hello_vector/hello_vector_sim_verilator.elf -bios out/shodan/build-bin/sw/device/boot_rom/boot_rom_fpga_nexysvideo.elf -nographic
```

Above starts up qemu with the debugger and breaks the simulator on the
`vsetvl` instruction so that you can check the state of the cpu.

This may be useful when debugging qemu itself.