Qemu Vector Testing and Debugging

  1. Qemu Setup
    1. Build steps:
    2. Start Qemu
    3. Exiting Qemu
  2. Running GDB
    1. Use the following command to run GDB
  3. GDBGUI Setup
    1. Installing gdbgui
    2. Running gdbgui
    3. gdbgui window
  4. GDB Usage
    1. Some Useful GDB instructions
  5. Aliases for convenience
  6. Advanced Usage
    1. 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

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
  • 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.