Add vector simulation setup instructions.
Add step-by-step instructions for setting up Henry's hellovector example,
and how to use the example framework to both add and simulate new vector opcodes.
Change-Id: If1fd6c5159ebcc5575a090370269e82476b3dc0f
diff --git a/RunningOpenTitanVectorSimulation.md b/RunningOpenTitanVectorSimulation.md
index 126857c..a6ba497 100644
--- a/RunningOpenTitanVectorSimulation.md
+++ b/RunningOpenTitanVectorSimulation.md
@@ -3,7 +3,7 @@
Follow setups in this document to build and run the following examples:
1. [OpenTitan Hello World Basic Example](#opentitan-hello-world-basic-example)
-2. [OpenTitan Hello World Vector Sim Example, WIP](#opentitan-hello-world-vector-sim-example-wip)
+2. [OpenTitan Hello World Vector Sim Example](#opentitan-hello-world-vector-sim-example)
Keep an eye on the file below for new build targets as they become available:
@@ -63,7 +63,6 @@
[More details in Renode's documentation](https://renode.readthedocs.io/en/latest/introduction/testing.html#running-the-robot-test-script)
-
### View Results of the Tests
Results of the robot-test-script will be found in the following files:
@@ -79,4 +78,115 @@
One can utilize `robot_output.xml` for scripts/programs which may want to parse
and act on results.
-## OpenTitan Hello World Vector Sim Example, WIP
+## OpenTitan Hello World Vector Sim Example
+
+How to run the HelloVector example and how to modify or add a new vector OpCode for Renode simulation.
+
+1. [Run OpenTitan HelloVector Renode Demo](#run-opentitan-hellovector-renode-demo)
+2. [Add or Modify Vector OpCodes and Simulate](#add-or-modify-vector-opcodes-and-simulate)
+
+### Run OpenTitan HelloVector Renode Demo
+
+#### Sync and set up environment
+
+```
+repo sync
+source ./build/setup.sh
+```
+
+#### Build tools
+
+```
+m tools
+```
+
+#### Build OpenTitan HelloVector Demo
+
+```
+m shodan_test_sw_bootrom
+m shodan_test_sw_hellovector
+```
+
+#### Start OpenTitan-HelloVector Renode Script
+
+```
+renode -e "i @sim/config/shodan_hellovector.resc; start"
+```
+
+### Add or Modify Vector OpCodes and Simulate
+
+To add or modify the functionality of an opcode, we will be modifying the following files:
+
+`$ROOTDIR/sim/renode/src/Infrastructure/src/Emulator/Cores/tlib/arch/riscv/translate.c`
+`$ROOTDIR/sim/renode/src/Infrastructure/src/Emulator/Cores/tlib/arch/riscv/instmap.h`
+
+#### Add new opcode in `instmap.h`'s enum
+
+To add a new opcode, create a new entry in `instmap.h`:
+
+```
+enum {
+ OPC_RISC_VADD_IVV = OPC_RISC_V_ARITH_IVV | (0x0 << 26),
+ OPC_RISC_VSUB_IVV = OPC_RISC_V_ARITH_IVV | (0x2 << 26),
+ OPC_RISC_VMINU_IVV = OPC_RISC_V_ARITH_IVV | (0x4 << 26),
+ YOUR_OPC_HERE = OPC_RISC_V_ARITH_IVV | (0x8 << 26),
+```
+
+#### Add `switch...case` entry and definition into `translate.c`
+
+Open `translate.c` and look for the following function (which will be around line 1450):
+
+```
+static void gen_v_arith_ivv(DisasContext *dc, uint32_t opc, int vd, int vs1, int vs2) {
+ tlib_printf(LOG_LEVEL_ERROR, "V_ARITH_IVV");
+
+```
+In this function there will be a `switch case`.
+Add an entry here for your new opcode, and fill out the behavior with tcg-lang.
+
+```
+switch (opc) {
+ case YOUR_OPC_HERE:
+ tlib_printf(LOG_LEVEL_ERROR, "OpCode Not Yet Defined");
+ break;
+```
+
+[Link to TCG Documentation for Reference](https://wiki.qemu.org/Documentation/TCG)
+
+#### Rebuild Renode
+
+```
+m renode_clean
+m renode
+```
+
+#### Add OpCode Test into `hello_vector.c`
+
+Wrap the assembly within an `__asm__` block and add to `hello_vector.c`:
+
+```
+$ROOTDIR/hw/opentitan/sw_shodan/device/examples/hello_vector/hello_vector.c
+```
+
+#### Rebuild `shodan_test_sw_hellovector` target
+
+If `hello_vector.c` was modified, run the following to rebuild the `shodan_test_sw_hellovector` target:
+
+```
+m shodan_test_sw_hellovector
+```
+
+#### Run Renode Script:
+
+```
+renode -e "i @sim/config/shodan_hellovector.resc; start"
+```
+
+#### Quicklinks to Relevant Files for OpCode Modification/Testing:
+
+- `$ROOTDIR/build/shodan_test_sw.mk` -- build file for `hellovector` example
+- `$ROOTDIR/sim/config/shodan_hellovector.resc` -- renode script which loads ELFs into memory
+- `$ROOTDIR/hw/opentitan/sw_shodan/device/examples/hello_vector/hello_vector.c` -- add assembly here (in `__asm__` blocks) for simulation
+- `$ROOTDIR/sim/renode/src/Infrastructure/src/Emulator/Cores/tlib/arch/riscv/translate.c` -- where to add or modify opcode behavior
+- `$ROOTDIR/sim/renode/src/Infrastructure/src/Emulator/Cores/tlib/arch/riscv/instmap.h` -- where to add numerical opcode definitions
+
