Add gettng-started doc for QemuVectorTesting/Debug
Add setup steps, basic usage instructions, and bash_aliases for using
Qemu with rvv1.0, GDB, and how to step through adn check vector and scalar registers.
Change-Id: Iad59b1bd495cd9cd24616464b3080de6a2e2e3cb
diff --git a/QemuVectorTestingAndDebugging.md b/QemuVectorTestingAndDebugging.md
new file mode 100644
index 0000000..b0b50ef
--- /dev/null
+++ b/QemuVectorTestingAndDebugging.md
@@ -0,0 +1,106 @@
+# 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. [GDBGUI Setup](#gdbgui-setup)
+ 1. [Installating gdbgui](#installating-gdbgui)
+ 2. [Running gdbgui](#running-gdbgui)
+ 3. [gdbgui window](#gdbgui-window)
+3. [GDB Usage](#gdb-usage)
+ 1. [Some Useful GDB instructions](#some-useful-gdb-instructions)
+4. [Aliases for convenience](#aliases-for-convenience)
+5. [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`.
+
+## GDBGUI Setup
+
+### Installating gdbgui
+
+`python3 -m pip install gdbgui`
+
+### Running gdbgui
+
+Use the following command to begin gdbgui:
+
+```
+gdbgui -g '$ROOTDIR/out/host/toolchain_vp/bin/riscv32-unknown-elf-gdb /usr/local/google/home/gkielian/shodan/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`)
+
+
+
+
+## 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="gdbgui -g '$ROOTDIR/out/host/toolchain_vp/bin/riscv32-unknown-elf-gdb /usr/local/google/home/gkielian/shodan/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.
\ No newline at end of file
diff --git a/gdbgui.png b/gdbgui.png
new file mode 100644
index 0000000..3ae8c07
--- /dev/null
+++ b/gdbgui.png
Binary files differ
