Add Renode debugging instructions
Including some steps for debugging in Renode + GDB as well as performing
an objdump on an elf to view the readable (non-machine code) assembly instructions.
Change-Id: Ia28ccbb5d256ebedf677435d75ef4894c21c3a17
diff --git a/CreateSpringbokVectorUnitTest.md b/CreateSpringbokVectorUnitTest.md
index 6aeb8ba..859efce 100644
--- a/CreateSpringbokVectorUnitTest.md
+++ b/CreateSpringbokVectorUnitTest.md
@@ -1,17 +1,22 @@
# Create Springbok Vector Unit Test
-* [Step 0: Repo Sync and Build Prequisites](#step-0_-repo-sync-and-build-prequisites)
-* [Step 1: Select Instruction and Update Tracker](#step-1_select-instruction-and-update-tracker)
-* [Step 2: Create operation definition in `${ROOTDIR}/sw/vec/softrvv/include`](#step-2_create-operation-definition-in)
-* [Step 3: Add the header to softrvv.h](#step-3_-add-the-header-to-softrvv_h)
-* [Step 4: Add main test entry within the CMakeLists.txt](#step-4_-add-main-test-entry-within-the-cmakelists_txt)
-* [Step 5: Create subtest](#step-5_-create-subtest)
+* [Step 0: Repo Sync and Build Prequisites](#step-0:-repo-sync-and-build-prequisites)
+* [Step 1: Select Instruction and Update Tracker](#step-1:-select-instruction-and-update-tracker)
+* [Step 2: Create operation definition in `${ROOTDIR}/sw/vec/softrvv/include`](#step-2:-create-operation-definition-in-`${rootdir}/sw/vec/softrvv/include`)
+* [Step 3: Add the header to softrvv.h](#step-3:-add-the-header-to-softrvv.h)
+* [Step 4: Add main test entry within the CMakeLists.txt](#step-4:-add-main-test-entry-within-the-cmakelists.txt)
+* [Step 5: Create subtest](#step-5:-create-subtest)
* [Add brief softrvv test](#add-brief-softrvv-test)
* [Add this smaller test to a 2nd Cmake file](#add-this-smaller-test-to-a-2nd-cmake-file)
-* [Step 6: Build and Run Tests](#step-6_-build-and-run-tests)
-* [Step 7 (optional): view generated code](#step-7-optional_view-generated-code)
-* [Step 8: Mark Tests as Passing](#step-8_-mark-tests-as-passing)
-* [Step 9: Git Commit](#step-9_-git-commit)
+* [Step 6.1: Build and Run Elf with Renode/Qemu](#step-6.1:-build-and-run-elf-with-renode/qemu)
+ * [Run Elf with Renode](#run-elf-with-renode)
+ * [Run Elf with Qemu](#run-elf-with-qemu)
+* [Step 6.2 (Optional): Debug Elf with Renode/Qemu and gdb](#step-6.2-(optional):-debug-elf-with-renode/qemu-and-gdb)
+* [Step 6.3 (Optional): Object dump with binutils](#step-6.3-(optional):-object-dump-with-binutils)
+* [Step 7: Build and Run CTests](#step-7:-build-and-run-ctests)
+* [Step 8 (optional): view generated code](#step-8-(optional):-view-generated-code)
+* [Step 9: Mark Tests as Passing](#step-9:-mark-tests-as-passing)
+* [Step 10: Git Commit](#step-10:-git-commit)
## Step 0: Repo Sync and Build Prequisites
@@ -152,20 +157,93 @@
-Xlinker --defsym=__itcm_length__=128K
```
-## Step 6: Build and Run Tests
+## Step 6.1: Build and Run Elf with Renode/Qemu
-Tests must be run from the `${ROOTDIR}/out/springbok` directory.
+`cd` into the root directory (`cd $ROOTDIR`), and build the elf with:
+
+```sh
+m springbok
+```
+
+### Run Elf with Renode
+
+From the root directory, run `sim_springbok`
+
+```sh
+sim_springbok ./out/springbok/tests/vadd_test.elf
+```
+
+This will run the single elf, and if there is an error, can give useful
+information, such as the PC and MTVAL associated with any illegal instruction.
+
+### Run Elf with Qemu
+
+From the root directory, run `qemu_sim_springbok`
+
+```sh
+qemu_sim_springbok ./out/springbok/tests/vadd_test.elf
+```
+
+## Step 6.2 (Optional): Debug Elf with Renode/Qemu and gdb
+
+To debug an elf, open two console sessions in the `$ROOTDIR`, in one run start a simulator
+(either `sim_springbok` or `qemu_sim_springbok`):
+
+Start Renode simulation:
+```sh
+sim_springbok ./out/springbok/tests/vadd_test.elf debug
+```
+Alternatively, start Qemu Simulation:
+
+```sh
+qemu_sim_springbok ./out/springbok/tests/vadd_test.elf debug
+```
+
+Now, in the other console session run the following command to start a gdb session:
+
+```sh
+cache/toolchain/bin/riscv32-unknown-elf-gdb -ex "target remote :3333" out/springbok/tests/vadd_test.elf
+```
+
+First, in the Renode session, type `start`.
+
+Then, in the gdb session, type the following,
+
+```sh
+layout split
+b main
+```
+
+and step through as usual with GDB.
+
+## Step 6.3 (Optional): Object dump with binutils
+
+Sadly, gdb cannot presently decode RVV machine code into assembly instructions.
+
+However, the objdump __is__ able to decode the RVV machine code into assembly.
+To do this, obtain the program counter for the RVV machine code in question, then perform an objdump.
+
+Run this on the elf (while in the `$ROOTDIR`):
+```sh
+cache/toolchain_iree_rv32imf/bin/riscv32-unknown-elf-objdump -d out/springbok/tests/vadd_test.elf | less
+```
+
+Then search for the PC for any instruction of interest.
+
+## Step 7: Build and Run CTests
+
+CTests must be run from the `${ROOTDIR}/out/springbok` directory.
`cd ${ROOTDIR}/out/springbok`
-Next, using Regex in the quoted section, select qemu, renode, and/or other operations
+Next, using Regex in the quoted section, select Qemu, Renode, and/or other operations
to include in a test run:
```sh
m springbok && ctest --verbose -R ".*vadd.*" --gtest_color=yes
```
-## Step 7 (optional): view generated code
+## Step 8 (optional): view generated code
Code for the main test was autogenerated, however by `cd`'ing into the following directory, one can inspect the generated code.
@@ -173,7 +251,7 @@
${ROOTDIR}/out/springbok/tests/generated/
```
-## Step 8: Mark Tests as Passing
+## Step 9: Mark Tests as Passing
Note: at minimum, one's test should be expected to pass in Qemu. Since Renode vec support is WIP, a unit test failing may indicate problem in the Renode implementation.
@@ -183,7 +261,7 @@
2. Mark whether the unit test passes in Renode
3. Mark the instruction "Springbok Unit Test" as "implemented"
-## Step 9: Git Commit
+## Step 10: Git Commit
At this point there are two commitable chunks:
