Merge "docs: Update code review policy"
diff --git a/TraceGeneration.md b/TraceGeneration.md
new file mode 100644
index 0000000..ebc745b
--- /dev/null
+++ b/TraceGeneration.md
@@ -0,0 +1,172 @@
+# Trace Generation
+
+Methods available in the Shodan repo for generating traces from Spike,
+and Renode.
+
+[TOC]
+
+## Trace Generation with Wrapper Script
+
+The `test_runner.py` script currently supports both trace generation in both **Spike** and **Renode**.
+
+### Spike trace generation with `test_runner.py`
+
+1. cd to the root shodan directory and run:
+
+```sh
+source build/setup.sh
+```
+
+2. (optionally) run `m springbok` to create potential elf targets
+
+3. Run trace with the `test_runner.py` script and save trace to file:
+
+```sh
+TEST_RUNNER="${ROOTDIR}/sw/vec/scripts/test_runner.py"
+ELF_FILE="${ROOTDIR}/out/springbok/rvv/softrvv/tests/softrvv_vxor_test.elf"
+SPIKE_PATH="${ROOTDIR}/out/host/spike/bin/spike"
+OUTPUT_FILE="spike_trace_output.txt"
+
+"${TEST_RUNNER}" "spike" \
+ "${ELF_FILE}" \
+ "--spike-path" "${SPIKE_PATH}" \
+ "--timeout=30" \
+ "--trace-output" "${OUTPUT_FILE}"
+```
+
+### Renode trace generation with `test_runner.py`
+
+```sh
+TEST_RUNNER="${ROOTDIR}/sw/vec/scripts/test_runner.py"
+ELF_FILE="${ROOTDIR}/out/springbok/rvv/softrvv/tests/softrvv_vxor_test.elf"
+RENODE_PATH="${ROOTDIR}/out/host/renode/renode"
+OUTPUT_FILE="renode_trace_output.txt"
+
+"${TEST_RUNNER}" "renode" \
+ "${ELF_FILE}" \
+ "--renode-path" "${RENODE_PATH}" \
+ "--quick_test" \
+ "--timeout=30" \
+ "--trace-output" "${OUTPUT_FILE}"
+```
+
+
+## Direct Trace Generation
+
+This section provides examples for setting up trace generation, and
+command line options for **Spike** and **Renode**.
+
+### Direct Spike Trace Generation
+
+#### Quickly Get Spike Trace With Springbok Defaults
+
+To run a direct spike trace with the defaults for springbok, run:
+
+```sh
+ELF_FILE="${ROOTDIR}/out/springbok/rvv/softrvv/tests/softrvv_vxor_test.elf"
+
+spike_sim_springbok "${ELF_FILE}"
+```
+
+Trace file will be saved to /tmp/spike_trace.txt
+
+#### Granular Direct Spike Trace Generation
+
+This section describes flags in depth for more granular trace generation.
+
+The following example shows trace generation for a softrvv vxor test script,
+and how to adjust each of the flag values:
+
+```sh
+ELF_FILE="${ROOTDIR}/out/springbok/rvv/softrvv/tests/softrvv_vxor_test.elf"
+LOG_FILE="spike_trace_output.txt"
+
+"${OUT}/host/spike/bin/spike" \
+ -m0x32000000:0x100000,0x34000000:0x1000000 \
+ --pc=0x32000000 \
+ --log="${LOG_FILE}" \
+ -l \
+ "${ELF_FILE}"
+```
+
+Sample output:
+
+```sh
+core 0: 0x00001000 (0x00000297) auipc t0, 0x0
+core 0: 0x00001004 (0x02028593) addi a1, t0, 32
+core 0: 0x00001008 (0xf1402573) csrr a0, mhartid
+core 0: 0x0000100c (0x0182a283) lw t0, 24(t0)
+core 0: 0x00001010 (0x00028067) jr t0
+core 0: >>>> _boot_address
+core 0: 0x32000000 (0x0080006f) j pc + 0x8
+core 0: >>>> _start
+core 0: 0x32000008 (0x02400117) auipc sp, 0x2400
+core 0: 0x3200000c (0xfb810113) addi sp, sp, -72
+```
+
+*Notes on Spike Flags:*
+
+- The elf-file __must__ be the last argument
+- Omitting the `--log` flag but keeping the `-l` flag sends trace to console's stderr instead of to a file.
+- add `-d` to to interactively run the trace
+- add `--log-commits` to add register value changes woven between the trace:
+
+Sample output (recall that `t0` is register `x5`, and `a1` is `x11`):
+
+```sh
+core 0: 0x00001000 (0x00000297) auipc t0, 0x0
+core 0: 3 0x00001000 (0x00000297) x 5 0x00001000
+core 0: 0x00001004 (0x02028593) addi a1, t0, 32
+core 0: 3 0x00001004 (0x02028593) x11 0x00001020
+```
+
+- we use the `-m` flag as `-m<IMEM>:<IMEM LENGTH>,<DMEM>:<DMEM LENGTH>` or more generally from the spike documentation:
+
+```
+ -m<a:m,b:n,...> Provide memory regions of size m and n bytes
+ at base addresses a and b (with 4 KiB alignment)
+```
+
+## Trace Analysis
+
+### Number of Instructions
+
+These commands assume the IMEM starts at 0x32000000, may need to s/0x32/0x80/ for 0x8000000 IMEM Starting address.
+
+#### Spike
+
+```sh
+cat spike_trace_output.txt | awk '/_start/,/_finish/' | grep "0: 0x32" | wc -l
+```
+
+#### Renode
+
+```sh
+renode_trace_output.txt | wc -l
+```
+
+### PC for Trace Analysis
+
+SystemC trace output contains the 8 digit PC in hex (without the '0x' prefix).
+
+These commands reformat the raw output trace from Spike and Renode for
+comparison with the SystemC output trace, located at:
+
+```sh
+$ROOTDIR/out/springbok/systemc/sim/simulations/trace.dat
+```
+
+
+#### Spike
+
+```sh
+cat spike_trace.txt | awk '/_start/,/_finish/' | sed 's/.*: 0x\([0-9a-fA-F]\{8\}\).*/\1/g' | egrep "^32" > spike_trace_pc.txt
+```
+
+#### Renode
+
+
+```sh
+cat renode_trace.txt | awk -F":" '{print $1}' | tr "[:upper:]" "[:lower:]" > renode_trace_pc.txt
+```
+
