Merge pull request #237 from antmicro/63923-add-simulation-debugging-…

…chapter Update documentation
chipsalliance · Sep 30, 2024 · 0274d92 · 0274d92
2 parents aae4eb7 + 49414f1
commit 0274d92
Show file tree

Hide file tree

Showing 34 changed files with 191 additions and 6 deletions.
diff --git a/docs/source/adaptations.md b/docs/source/adaptations.md
@@ -12,7 +12,7 @@ Unless otherwise noted, all read/write control/status registers must have WARL (
 ## Machine Interrupt Enable (mie) and Machine Interrupt Pending (mip) Registers
 
 The standard RISC-V `mie` and `mip` registers hold the machine interrupt enable and interrupt pending bits, respectively.
-Since VeeR EL2 only supports machine mode, all supervisor- and user-specific bits are not implemented.
+Since VeeR EL2 only supports machine and user mode, all supervisor-specific bits are not implemented.
 In addition, the `mie/mip` registers also host the platform-specific local interrupt enable/pending bits (shown with a gray background in {numref}`tab-machine-interrupt-enable-register` and {numref}`tab-machine-interrupt-pending-register` below).
 
 The `mie` register is a standard read/write CSR.

diff --git a/docs/source/debugging.md b/docs/source/debugging.md
@@ -1334,12 +1334,12 @@ This register is mapped to the standard read/write CSR address space.
   - 0
 * - s
   - 4
-  - Not implemented (VeeR EL2 is M-mode only)
+  - Not implemented
   - R
   - 0
 * - u
   - 3
-  - Not implemented (VeeR EL2 is M-mode only)
+  - Not implemented
   - R
   - 0
 * - execute
@@ -1437,12 +1437,12 @@ This register is mapped to the standard read/write CSR address space.
   - 0
 * - ebreaks
   - 13
-  - Not implemented (VeeR EL2 is M-mode only)
+  - Not implemented
   - R
   - 0
 * - ebreaku
   - 12
-  - Not implemented (VeeR EL2 is M-mode only)
+  - Not implemented
   - R
   - 0
 * - stepie

diff --git a/docs/source/img/19-riscv_pmp_block_diagram.png b/docs/source/img/19-riscv_pmp_block_diagram.png
diff --git a/docs/source/img/1_1_bus2core_clock_ratio.png b/docs/source/img/1_1_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_2_bus2core_clock_ratio.png b/docs/source/img/1_2_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_3_bus2core_clock_ratio.png b/docs/source/img/1_3_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_4_bus2core_clock_ratio.png b/docs/source/img/1_4_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_5_bus2core_clock_ratio.png b/docs/source/img/1_5_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_6_bus2core_clock_ratio.png b/docs/source/img/1_6_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_7_bus2core_clock_ratio.png b/docs/source/img/1_7_bus2core_clock_ratio.png
diff --git a/docs/source/img/1_8_bus2core_clock_ratio.png b/docs/source/img/1_8_bus2core_clock_ratio.png
diff --git a/docs/source/img/activity_states.png b/docs/source/img/activity_states.png
diff --git a/docs/source/img/breakpoint_timing.png b/docs/source/img/breakpoint_timing.png
diff --git a/docs/source/img/clock_reset_timing.png b/docs/source/img/clock_reset_timing.png
diff --git a/docs/source/img/clock_timing.png b/docs/source/img/clock_timing.png
diff --git a/docs/source/img/comparator.png b/docs/source/img/comparator.png
diff --git a/docs/source/img/core_complex.png b/docs/source/img/core_complex.png
diff --git a/docs/source/img/core_pipeline.png b/docs/source/img/core_pipeline.png
diff --git a/docs/source/img/csr_timing.png b/docs/source/img/csr_timing.png
diff --git a/docs/source/img/debug_csrs.png b/docs/source/img/debug_csrs.png
diff --git a/docs/source/img/ecc_mem_diag.png b/docs/source/img/ecc_mem_diag.png
diff --git a/docs/source/img/gateway.png b/docs/source/img/gateway.png
diff --git a/docs/source/img/gateway_diagram.png b/docs/source/img/gateway_diagram.png
diff --git a/docs/source/img/interrupt_chaining.png b/docs/source/img/interrupt_chaining.png
diff --git a/docs/source/img/logo.png b/docs/source/img/logo.png
diff --git a/docs/source/img/multicore_csr_timing.png b/docs/source/img/multicore_csr_timing.png
diff --git a/docs/source/img/openocd-jtag.png b/docs/source/img/openocd-jtag.png
diff --git a/docs/source/img/pic_diagram.png b/docs/source/img/pic_diagram.png
diff --git a/docs/source/img/riscv-dv-flow.png b/docs/source/img/riscv-dv-flow.png
diff --git a/docs/source/img/vei.png b/docs/source/img/vei.png
diff --git a/docs/source/index.md b/docs/source/index.md
@@ -26,4 +26,6 @@ errata
 physical-memory-protection
 user-mode
 verification
+simulation-debugging
+tock
 ```
diff --git a/docs/source/overview.md b/docs/source/overview.md
@@ -1,6 +1,6 @@
 # Core Overview
 
-This chapter provides a high-level overview of the VeeR EL2 core and core complex. VeeR EL2 is a machinemode (M-mode) only, 32-bit CPU small core which supports RISC-V's integer (I), compressed instruction (C), multiplication and division (M), and instruction-fetch fence, CSR, and subset of bit manipulation instructions (Z) extensions. The core contains a 4-stage, scalar, in-order pipeline.
+This chapter provides a high-level overview of the VeeR EL2 core and core complex. VeeR EL2 is a machinemode (M-mode) and usermode (U-mode), 32-bit CPU small core which supports RISC-V's integer (I), compressed instruction (C), multiplication and division (M), and instruction-fetch fence, CSR, and subset of bit manipulation instructions (Z) extensions. The core contains a 4-stage, scalar, in-order pipeline.
 
 ## Features
 

diff --git a/docs/source/simulation-debugging.md b/docs/source/simulation-debugging.md
@@ -0,0 +1,57 @@
+# Interactive Debugging in Simulation
+
+It is possible to perform a debugging session through a virtual JTAG interface with the VeeR EL2 Core running in simulation.
+This allows the user to exercise JTAG usage scenarios using actual debugging tools instead of unit tests written for JTAG logic.
+The feature was added to the VeeR EL2 Core with [Pull Request #211](https://github.com/chipsalliance/Cores-VeeR-EL2/pull/211).
+
+The principle of operation is a JTAG probe RTL model which communicates with the host via DPI.
+This is illustrated in {numref}`fig-openocd-jtag`:
+
+:::{figure-md} fig-openocd-jtag
+![](img/openocd-jtag.png)
+
+OpenOCD JTAG
+:::
+
+Currently the probe model implements the `remote_bitbang` protocol of [OpenOCD](https://openocd.org/), allowing the tool to interact with simulation.
+The protocol operates over a TCP/IP connection or a UNIX socket.
+An appropriate server and protocol decoder runs on the host machine and communicates with the simulation via DPI to set/read JTAG signal states.
+The entire flow is transparent to the debugging tools and to the user.
+
+The probe model has been integrated into the testbench.
+It is active every time the testbench is run; there is no need for any additional action.
+To run a testbench, execute, for example:
+
+```bash
+make -C run -f ${RV_ROOT}/tools/Makefile verilator-build program.hex TEST=infinite_loop \
+    CONF_PARAMS="-set openocd_test"
+```
+
+The `RV_ROOT` variable in the snippet above is the path to the root of the Cores-VeeR-EL2 repository.
+
+To keep the simulation running continuously, the `infinite_loop` test program has been added.
+The program consists of two nested loops running continuously.
+
+Then, to connect to a running simulation via OpenOCD, you can use the configs available in the `testbench/openocd_scripts` directory:
+
+```bash
+cd testbench/openocd_scripts
+openocd -d2 -f verilator-rst.cfg jtag_cg.tcl
+```
+
+`jtag_cg.ctl` is an OpenOCD script that performs JTAG access tests.
+These include core register access and memory access.
+The configuration is passed by `verilator-rst.cfg`.
+It includes `sim-jtagdpi.cfg` and `veer-el2-rst.cfg`.
+`sim-jtagdpi.cfg` contains a JTAG adapter configuration.
+`veer-el2-rst.cfg` configures the target for OpenOCD.
+The test involves the CPU core held permanently in reset.
+Moreover, a [customized version of OpenOCD](https://github.com/antmicro/openocd/tree/riscv-nohalt) had to be used, as the stock version performs target CPU examination by default which is not possible when in reset.
+
+### Automation
+
+In the `.github/scripts` directory of the [VeeR](https://github.com/chipsalliance/Cores-VeeR-EL2) repository, you can find a helper `openocd_test.sh` script that is responsible for launching simulation, executing an OpenOCD script as a test and terminating it.
+The script is used in CI.
+
+The script assumes that both the verilated simulation and the CPU program binary are already built.
+You can find a usage example in the GitHub Action workflow definition: `.github/workflows/test-openocd.yml`.
diff --git a/docs/source/tock.md b/docs/source/tock.md
@@ -0,0 +1,126 @@
+# Running Tock OS
+
+This chapter describes the steps necessary to build a [Tock OS](https://github.com/tock/tock) application for the VeeR EL2 core, along with instructions for running it in simulation using [Verilator](https://github.com/verilator/verilator).
+
+## Prerequisites
+
+Install build dependencies:
+
+```
+apt install curl make build-essential gcc-riscv64-unknown-elf wget unzip python3-pip
+```
+
+To compile Tock, you need a Rust toolchain installer called `rustup`:
+
+```
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+For detailed information on installing Tock OS, refer to the project's [documentation](https://book.tockos.org/).
+
+## Fetching sources
+
+```
+git clone https://github.com/tock/tock.git
+cd tock
+```
+
+## Running simulation in Verilator
+
+In order to compile Tock OS and start simulation, run:
+
+```
+make -C boards/veer_el2_sim sim
+```
+
+The expected output is:
+
+```
+VerilatorTB: Start of sim
+mem_signature_begin = 00000000
+mem_signature_end   = 00000000
+mem_mailbox         = D0580000
+VeeR EL2 initialisation complete.
+Entering main loop.
+```
+
+## Running simulation in Verilator with applications
+
+### Building Tock
+
+In order to compile Tock, run:
+
+```
+make -C boards/veer_el2_sim
+```
+
+### Building an application
+
+```
+git clone https://github.com/tock/libtock-c.git
+make -C libtock-c/examples/c_hello -j$(nproc)
+```
+
+### Providing a verilog file for simulation
+
+The testbench for Verilator requires a single file with a program (`program.hex`), so it's necessary to combine the kernel and applications into a single binary first.
+
+You can use Tockloader to create a binary file representing flash with the kernel, and then install the application:
+
+```
+tockloader flash --board veer_el2_sim --flash-file ./veer_el2_sim.bin --address 0x20000000 ./target/riscv32imc-unknown-none-elf/release/veer_el2_sim.bin
+tockloader install --board veer_el2_sim --arch rv32imc --flash-file ./veer_el2_sim.bin libtock-c/examples/c_hello/build/c_hello.tab
+riscv64-unknown-elf-objcopy --change-addresses 0x20000000 -I binary -O verilog veer_el2_sim.bin program.hex
+```
+
+Now `program.hex` is ready for use in simulation.
+
+### Starting simulation in Verilator
+
+Clone the Cores-VeeR-EL2 repository:
+
+```
+git clone https://github.com/chipsalliance/Cores-VeeR-EL2.git
+cd Cores-VeeR-EL2
+git switch --detach da1042557
+```
+
+Increase the maximum number of cycles in simulation:
+
+```
+sed -i 's/parameter MAX_CYCLES = 2_000_000;/parameter MAX_CYCLES = 10_000_000;/g' testbench/tb_top.sv
+```
+
+You can build a testbench using these commands:
+
+```
+export RV_ROOT=$(pwd)
+make -C tools CONF_PARAMS='-set build-axi4 -set user_mode=1 -set reset_vec=0x20000000' verilator-build
+```
+
+Make sure the program you want to run is placed in the current working directory and named `program.hex`:
+
+```
+cp ../program.hex .
+```
+
+In order to start the simulation, run:
+
+```
+./tools/obj_dir/Vtb_top
+```
+
+The output should look like this:
+
+```
+VerilatorTB: Start of sim
+
+mem_signature_begin = 00000000
+mem_signature_end   = 00000000
+mem_mailbox         = D0580000
+VeeR EL2 initialisation complete.
+Entering main loop.
+Hello World!
+```
+
+The execution trace will be located in `exec.log`.