TraceGeneration.md

# 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" \
    -m0x34000000:0x1000000 \
    --pc=0x34000000 \
    --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<TCM>:<TCM 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 TCM starts at 0x34000000, may need to s/0x34/0x80/ for 0x8000000 TCM Starting address.

#### Spike

```sh
cat spike_trace_output.txt | awk '/_start/,/_finish/' | grep "0: 0x34" | 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 "^34" > spike_trace_pc.txt
```

#### Renode


```sh
cat renode_trace.txt | awk -F":" '{print $1}' | tr "[:upper:]" "[:lower:]" > renode_trace_pc.txt
```