Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update documentation #237

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/adaptations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
8 changes: 4 additions & 4 deletions docs/source/debugging.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
Binary file modified docs/source/img/19-riscv_pmp_block_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_1_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_2_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_3_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_4_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_5_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_6_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_7_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/1_8_bus2core_clock_ratio.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/activity_states.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/breakpoint_timing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/clock_reset_timing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/clock_timing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/comparator.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/core_complex.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/core_pipeline.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/csr_timing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/debug_csrs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/ecc_mem_diag.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/gateway.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/gateway_diagram.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/interrupt_chaining.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/multicore_csr_timing.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/source/img/openocd-jtag.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/source/img/pic_diagram.png
Binary file modified docs/source/img/riscv-dv-flow.png
Binary file modified docs/source/img/vei.png
2 changes: 2 additions & 0 deletions docs/source/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,6 @@ errata
physical-memory-protection
user-mode
verification
simulation-debugging
tock
```
2 changes: 1 addition & 1 deletion docs/source/overview.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
57 changes: 57 additions & 0 deletions docs/source/simulation-debugging.md
Original file line number Diff line number Diff line change
@@ -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`.
126 changes: 126 additions & 0 deletions docs/source/tock.md
Original file line number Diff line number Diff line change
@@ -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`.
Loading