# Assignment3 Reindeer - RISCV RV32I[M] Soft CPU
###### tags: `Computer Architecture`
### How RISC-V Compliance Tests works?
According to the "RISC-V Compliance Tests" documentation, the goal of compliance tests is to check whether the processor under development meets the open RISC-V standards or not.

The Reindeer soft CPU uses an OCD to load code/data. And for the verilator simulation, a C++ testbench will replace the OCD.

Take `I-ADD-01.elf` for example, the testbench will invoke the toolchain (objdump, readelf) to extract code/data from sections of the .elf file. Then testbench will mimic the OCD bus to load the code/data into CPU's memory to compare it with the signatures and finish the compliance test.

The followings are some code segments of `tb_PulseRain_RV2T.cpp`, which plays an important role in the task of the compliance test. There are several steps for the testbench to accomplish the compliance test.

1.`tb_PulseRain_RV2T.cpp` process the .elf file to extract `_start`, `begin_signature` and `end_signature`.

2.Parse elf file to extract information for each section.

3.Create a UUT and Testbench instance

4.Reset the input signal of the UUT

5.Start to assert the signal and load text/data sections into UUT's memory

6.Matching signature while peeking the memory

After the compilance test is done, you can check if the signature is match or not.

### Why signature should be matched?
To ensure the processor work properly when executing different types of instructions.
### How Reindeer works with Verilator?
Nowadays, we use RTL languages such as Verilog to discribe hardware components to design an integrated circuit(IC). Since Reindeer is a soft CPU of Von Neumann architecture, you can say that it is a piece of RTL script.

On the other hand, Verilator "Verilates" the specified Verilog or SystemVerilog code by reading it, performing lint checks, and optionally inserting assertion checks and coverage-analysis points. It outputs single- or multi-threaded .cpp and .h files, the "Verilated" code.

This implies that we can use Verilator to "Verilates" Reindeer into C++ script. Different from verilog, which is hardware-oriented, C++ is more behavior-oriented. That is, the "Verilation" process lets us to check the Reindeer from a behavioral point of view.

With Verilator, we can write the testbench in C++ format instead of verilog. This makes the development of RISC-V processor much more intuitive.
### Advantages of 2 x 2 Pipeline
In the 2 x 2 layout, each stage is active every other clock cycle. For the even cycle, only IF and EXE stages are active, while for the odd cycle, only ID and MEM stages are active. This implies that only one instruction comes into pipeline for every two cycles.
* The IF and MEM stage always happen on different clock cycles, thus to avoid the structural hazard caused by the single port memory.
* Comparing to a 5-stage pipeline, Reindeer merges MEM and WB stage into one stage. So we don't need MEM/WB pipeline register anymore. On the other hand, since an instruction only come into pipeline every two cycles, there is no need to consider data hazard which only needs one-cycle stalled to be solved . So this could save us from implementing some forwarding units. These factors might potentially reduces the cost of implementing the processor.
* Since there are only two stages active seperately in the total four stages pipline for every clock cycle, we can be less concern about the hold time and setup time of the pipeline register. Thus, cycle time can also be reduced.
### “Hold and Load” and Bootstrapping
#### “Hold ” state
The soft CPU and the OCD can share the same UART port, as illustrated below. The RX signal goes to both the soft CPU and OCD, while the TX signal has to go through a mux. And that mux is controlled by the OCD.
After reset, the soft CPU will be put into a hold state, and it will have access to the UART TX port by default. But a valid debug frame sending from the host PC can let OCD to reconfigure the mux and switch the UART TX to OCD side, for which the memory can be accessed, and the control frames can be exchanged.
#### Loading image during Hold state
A new software image can be loaded into the memory during the CPU hold state.
After the memory is loaded with the new image, the OCD can setup the start-address of the soft CPU, and send start pulse to make the soft CPU active. At that point, the OCD can switch the UART TX back to the CPU side for CPU's output.
#### Bootstrapping
The testbench will mimic the OCD bus to load the code/data into CPU's memory. Afterwards, the start-address of the .elf file ("_start" or "__start" symbol) will be passed onto the CPU, and turn the CPU into active state.

## Modify the assembly programs as new test case for Reindeer Simulation with Verilator
### Steps to generate .elf, .elf.objdump and .signature files
:::info
Prequisites: Prepare GNU Toolchain for RISC-V and configure $PATH as [assignment 2](https://hackmd.io/@sysprog/rJAufgHYS) did (Step1 and Step2).
:::
1. Clone `imperas-riscv-tests` repository from github to your file by inputting `git clone https://github.com/riscv-ovpsim/imperas-riscv-tests.git` to linux terminal

2. Modify the text of Makefile in the `imperas-riscv-tests` file as following:

3. Because the `riscvOVPsim.exe` is in a different directory, you need to add that path to the environment variable. For example, my `imperas-riscv-test` folder is located at the `root`. My command to set path is:
`PATH=$PATH:~/imperas-riscv-tests/riscv-ovpsim/bin/Linux64`

:::info
You can input the command `echo $PATH` to the terminal to check if the environment variables is correct or not.
:::
4. Put your .S file into `imperas-riscv-tests/riscv-tests-suite/rv32i/src` folder
Put your .reference_output file into `imperas-riscv-tests/riscv-tests-suite/rv32i/references` folder

5. Add your project name to the Makefrag file, which is located at the rv32i folder.

6. Now go to the the `imperas-riscv-tests` folder and input `make simulate verify`.
Then your .S file will be converted into 3 files. You can find it in the `work` folder.

### Specify the .S file for the compliance test
To write our own .S file, let's take a look at an example of a test case. Here is a code segment of file `I-ADD-01.S`:
:::info
* .S (capital S) stands for assembly code that must still pass through a pre-processor. That means it can have #include and #define among other macros. It can also be seeing as extension .sx
* .s (lower s) is pure assembly code that can be compiled into an object
:::
You can find that most of the marco be written in the .S file is `TEST_RR_OP`. In this example, the type of instruction being tested is `add`.

And the `TEST_RR_OP` marco can be found in `riscv_test_macros.h` header file.

Take the first test marco `TEST_RR_OP(add, x0, x31, x16, 0x0, -0x1, 0x0, x5, 0, x6)` for example, it will be parsed to:

TEST_CASE(x6, x0, 0x0, x5, 0,\
    li x31, MASK_XLEN(-0x1);\
    li x16, MASK_XLEN(0x0);\
    add x0, x31, x16;
    )

And can be further parsed to:

li x31, MASK_XLEN(-0x1);
li x16, MASK_XLEN(0x0);
add x0, x31, x16;
sw x0, 0(x5);
RVTEST_IO_ASSERT_GPR_EQ(x6, x0, 0x0)

To make it clearly, it means :

li reg1, MASK_XLEN(val1);
li reg2, MASK_XLEN(val2);
inst desreg, reg1, reg2;
sw desreg, 0(swreg);
RVTEST_IO_ASSERT_GPR_EQ(testreg, desreg, correctval)

According to the section `3.2. Process` in the [documentation](https://github.com/riscv/riscv-compliance/blob/master/doc/README.adoc#process).
:::info
* Use the `RVTEST` macros (defined in `compliance_io.h`) to make it easy to see the details of a Test’s execution. There are macros for assertions (`RVTEST_IO_ASSERT_GPR_EQ`) and tracing (`RVTEST_IO_WRITE_STR`) which are empty on targets that can not implement them.
:::
So`RVTEST_IO_ASSERT_GPR_EQ` function is to assert the signal in the CPU.

Therefore, I wrote my .S file as following:

#include "riscv_test_macros.h"
#include "compliance_test.h"
#include "compliance_io.h"

RV_COMPLIANCE_RV32M

RV_COMPLIANCE_CODE_BEGIN

	RVTEST_IO_INIT
	RVTEST_IO_ASSERT_GPR_EQ(x31, x0, 0x00000000)
	RVTEST_IO_WRITE_STR(x31, "# Test Begin\n")

	lw x18, num1
	lw x19, num2
	la x3, res_addr
	beqz x18, assign
	loop:
		mv x20, x19
	mod:
		sub x5, x18, x19 
		mv x18, x5 
		bgez x5, mod
		add x5, x18, x19
		mv x18, x20
		bnez x19, loop
	assign:
		mv x18, x19
	sw x18, 0(x3)
	
	RVTEST_IO_WRITE_STR(x31, "# Test End\n")
	RV_COMPLIANCE_HALT
	
RV_COMPLIANCE_CODE_END

# Input data section.
	.data

num1:
	.word 0x00000078 #decimal=120
num2:
	.word 0x0000004E #decimal=78

# Output data section.
RV_COMPLIANCE_DATA_BEGIN

res_addr:
	.fill 4, 4, -1


RV_COMPLIANCE_DATA_END

## Execute .elf file on the Reindeer
Put the 3 files I mentioned before into the `Reindeer/sim/compliance` folder.
Access the `Reindeer/sim/verilator` folder and input `make test GCD`.
The test bench load .text section of the .elf file into the memory. The memory address to store machine instructions is from 0x8000000 to 0x80000138.
## Using GTKwave to check the wave

### Signals/events inside Reindeer
Reindeer SoftCPU takes two clock cycles to fetch one instruction.
***
Register read and write only occurs in the even cycle.
***
Writing the .elf text section into the memory. In this case, machine instrction `0x34202f73` is write to the memory address `0x80000004`, `0x00800f93` is write to the `0x80000008`, and so on.