Add documentation for trace generation
Adding instructions for direct trace generation:
- Spike
And those with the `test_runner.py` wrapper script for:
- Spike
- Renode
Change-Id: I5eaf587953f0384deea98d8a0e01c2e8f4671d6d
diff --git a/TraceGeneration.md b/TraceGeneration.md
new file mode 100644
index 0000000..7ec5c64
--- /dev/null
+++ b/TraceGeneration.md
@@ -0,0 +1,130 @@
+# Trace Generation
+
+Methods available in the Shodan repo for generating traces from Qemu, 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)
+```
+
+
