trace gen doc update and announce Spike-STF (#258)

For olympia this is a documentation update for trace generation.

Also this PR announces public release of a Spike fork that supports STF
and BBV generation (called Spike-STF). Spike-STF was forked from the
main Spike and the STV/BBV/regression support was developed by me and
others at Condor. There are a number of other features included. BTW:
this version of spike supports the RVA23 profile, which includes vector.

The public repo is here
https://github.com/jeffnye-gh/cpm.riscv-isa-sim.git.

In the PR I have updated the trace/README.md with details on how to
generate traces under linux and baremetal and use them with olympia.

The trace README.md documents how to use the Spike-STF repo, cloning it
within the olympia tree, d/loading a baremetal and linux cross-compiler,
d/loading the kernel, buildroot and opensbi. There is a fair bit of
automation to support linux and build these packages. There are bash
scripts that illustrate how to use the constructed collateral to create
traces for olympia.

I have kept the Dromajo instructions, but I think long term this will
replace Dromajo because Spike's ISA support is current.

I have also added three dhrystone traces generated with Spike-STF. These
three dhrystone align with the accepted practice of 3 levels of
optimization, ground rules, in-lining, and LTO.

---------

Co-authored-by: jeffnye-gh <habanaro@gmail.com>

Author: jeffnye-gh

traces/README.md

@@ -1,5 +1,27 @@
 # Generating Input for Olympia
 
+## Table of Contents
+
+1. [Introduction](#introduction)
+1. [JSON Inputs](#json-inputs)
+1. [STF Inputs](#stf-inputs)
+1. [Instrumenting Source for Tracing](#instrumenting-source-for-tracing)
+1. [Generating Baremetal Traces](#generating-baremetal-traces)
+    1. [Build Spike-STF](#build-spike-stf)
+    1. [Generating the Baremetal Dhrystone Traces](#generating-the-baremetal-dhrystone-traces)
+1. [Generating Linux Traces](#generating-linux-traces)
+    1. [Building the Linux Dhrystone Elfs](#building-the-linux-dhrystone-elfs)
+    1. [Building the Linux Collateral](#building-the-linux-collateral)
+    1. [Booting Linux on Spike-STF](#booting-linux-on-spike-stf)
+    1. [Updating the Root File System](#updating-the-root-file-system)
+    1. [Invoke Linux and Generate the Traces](#invoke-linux-and-generate-the-traces)
+    1. [Sample Session](#sample-session)
+1. [Generating an STF Trace with Dromajo](#generating-an-stf-trace-with-dromajo)
+    1. [Build an STF Capable Dromajo](#build-an-stf-capable-dromajo)
+    1. [Instrument a Workload for Tracing](#instrument-a-workload-for-tracing)
+
+## Introduction
+
 Olympia can take input in two formats: JSON and
 [STF](https://github.com/sparcians/stf_spec).
 
@@ -11,6 +33,16 @@ STF format is the preferred format to represent a workload to run on
 Olympia.  STFs are typically created by a RISC-V functional model that
 has been instrumented to generate one.
 
+Two functional models which generate STFs are documented.
+[Spike-STF](https://github.com/jeffnye-gh/cpm.riscv-isa-sim)
+ is the latest model, 
+[Dromajo](https://github.com/chipsalliance/dromajo) also generates
+STFs. 
+
+Spike-STF ISA suport is more recent. Spike-STF adds other features such as BBV generation. 
+
+Documentation for trace generation is provided for both functional models.
+
 ## JSON Inputs
 
 JSON inputs are typically generated by hand.  There are no automated
@@ -93,18 +125,290 @@ cd build
 
 Using the [stf_lib]() in the [Sparcians](https://github.com/sparcians)
 repo, Olympia is capable of reading a RISC-V STF trace generated from
-a functional simulator.  Included in Olympia (in this directory) is a
-trace of the "hot spot" of Dhrystone generated from the Dromajo
-simulator. This directory also contains a trace of Coremark generated
-similarly.
+a functional simulator.  Included in Olympia (in this directory) are several trace files
+
+```
+  - traces/dhrystone_opt1.zstf  1000 iterations of a baremetal Dhrystone 
+                                run with optimization set for 'Ground Rules'.
+  - traces/dhrystone_opt2.zstf  1000 iterations of a baremetal Dhrystone 
+                                run with optimization allowing in-lining.
+  - traces/dhrystone_opt3.zstf  1000 iterations of baremetal Dhrystone 
+                                run with optimization allowing in-lining
+                                and LT. Baremetal
+
+  - traces/core_riscv.zstf      Hot spot of Coremark generated by Dromajo
+  - traces/dhrystone.zstf       Hot spot of Dhrystone generated by Dromajo
+  - traces/core_riscv.zstf      Hot spot of Coremark generated by Dromajo
+```
 
-To run the STF file, just provide it to olympia:
+To run an STF file, provide the path to olympia:
 ```
 cd build
+./olympia ../traces/dhrystone_opt1.zstf
+./olympia ../traces/dhrystone_opt2.zstf
+./olympia ../traces/dhrystone_opt3.zstf
 ./olympia ../traces/dhrystone.zstf
 ./olympia ../traces/core_riscv.zstf
 ```
 
+## Instrumenting Source for Tracing
+
+There are multiple ways to trigger tracing. The macro tracing scheme
+instruments source code with trace boundary macros. These
+macros are nops with known operand encodings comprehended by
+the functional models. The macro tracing scheme supports baremetal and 
+linux application tracing.
+
+The source code is instrumented by insertion of `START_TRACE` and `STOP_TRACE`.
+
+For example:
+``` main() {
+    // ... init code
+
+    START_TRACE;
+    // Dhrystone benchmark code
+    STOP_TRACE;
+
+    // ... teardown
+   }
+
+```
+The `START_TRACE` and `STOP_TRACE` macros are defined in `traces/stf_trace_gen/trace_macros.h`.
+
+Instructions between the macros will be recorded in the trace output.
+
+Spike-STF supports other tracing modes. Both Dromajo and Spike-STF support 
+the macro tracing mode.
+
+---------------------------------------------------------
+## Generating Baremetal Traces
+
+### Build Spike-STF
+The first step to generating an STF with Spike-STF is to clone and build
+the Spike-STF [repo](https://github.com/jeffnye-gh/cpm.riscv-isa-sim.git).
+
+This example uses the `riscv-perf-model/traces` directory as a working
+directory.
+
+The steps are: clone the repo, download and add the baremetal compiler to your
+path, and build/regress/install Spike-STF.
+
+The compiler steps are optional if you have `riscv64-unknown-elf-gcc` in 
+your path.
+
+```bash
+cd riscv-perf-model/traces
+git clone https://github.com/jeffnye-gh/cpm.riscv-isa-sim.git --recursive
+
+cd cpm.riscv-isa-sim
+bash scripts/download-bm-compiler.sh
+export PATH=`pwd`/riscv-embecosm-embedded-ubuntu2204-20250309/bin:$PATH
+```
+Exit the conda environment, if enabled, before compiling Spike-STF.
+```
+conda deactivate
+conda deactivate
+
+mkdir -p build install && cd build
+../configure --prefix=`pwd`/../install
+make -j$(nproc)
+make regress
+make install
+```
+
+The regress target executes the [riscv-tests](https://github.com/riscv-software-src/riscv-tests) test suite. Pass/fail is reported.
+
+The compiler is a prebuilt RISC-V cross compiler from [Embecosm](https://embecosm.com/).
+
+There is detailed information in the Spike-STF repo, 
+[README_FORK.mk](https://github.com/jeffnye-gh/cpm.riscv-isa-sim/blob/spike_stf/README_FORK.md)  and [USAGE.md](https://github.com/jeffnye-gh/cpm.riscv-isa-sim/blob/spike_stf/USAGE.md).
+
+### Generating the Baremetal Dhrystone Traces
+
+When Spike-STF is initially configured the dhrystone ELFs are created. If they need to be re-created:
+
+```bash
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+make -C dhrystone
+```
+
+This creates 3 versions of the dhrystone elf with 3 different levels of 
+optimization running 1000 iterations. The source code has been modified to
+add the trace macros and to allow simplified execution under baremetal with
+limited syscall support.
+
+A discussion of the 3 optimization levels is available in [USAGE.md](https://github.com/jeffnye-gh/cpm.riscv-isa-sim/blob/spike_stf/USAGE.md#dhrystone-optimization-discussion).
+
+Once the ELFs are built, traces are generated by:
+
+```
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+
+bash scripts/run-spike-stf.sh dhrystone/bin/dhrystone_opt1.1000.gcc.bare.riscv \
+                              dhrystone_opt1.zstf
+bash scripts/run-spike-stf.sh dhrystone/bin/dhrystone_opt2.1000.gcc.bare.riscv \
+                              dhrystone_opt2.zstf
+bash scripts/run-spike-stf.sh dhrystone/bin/dhrystone_opt3.1000.gcc.bare.riscv \
+                              dhrystone_opt3.zstf
+```
+
+The compressed trace outputs can then be run on olympia by
+
+```
+<cd to the directory containing olympia>
+
+./olympia ../traces/cpm.riscv-isa-sim/trace_out/dhrystone_opt1.zstf
+./olympia ../traces/cpm.riscv-isa-sim/trace_out/dhrystone_opt2.zstf
+./olympia ../traces/cpm.riscv-isa-sim/trace_out/dhrystone_opt3.zstf
+```
+## Generating Linux Traces
+
+### Building the Linux Dhrystone Elfs
+
+In order to compile applications for linux, you must have riscv64-unknown-linux-gnu-gcc in your path.
+
+```
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+bash scripts/download-lnx-compiler.sh
+export PATH=`pwd`/riscv64-embecosm-linux-gcc-ubuntu2204-20240407/bin:$PATH
+```
+
+To build the linux version of the Dhrystone benchmarks:
+```
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+make -C dhrystone bin-linux
+```
+
+Directory dhrystone/bin will contain:
+```
+dhrystone/bin/dhrystone_opt1.1000.gcc.linux.riscv
+dhrystone/bin/dhrystone_opt2.1000.gcc.linux.riscv
+dhrystone/bin/dhrystone_opt3.1000.gcc.linux.riscv
+```
+
+### Building the Linux Collateral
+
+In order to generate linux based traces a linux environment is required as well as a linux cross compiler in your path. See above for the compiler.
+
+A linux environment consists of a bootloader, the linux kernel and a 
+root file system.
+
+The process to clone and build these components is contained in a script.
+This is a lengthy process.
+
+```bash
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+bash scripts/build-linux-collateral.sh
+```
+
+Once complete, the directory `riscv-perf-model/traces/cpm.riscv-isa-sim/riscv-linux` will contain the files necessary to boot linux.
+```
+fw_jump.elf
+rootfs.cpio
+Image
+```
+
+### Booting Linux on Spike-STF
+With the linux components built, boot linux using the helper script:
+```
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+bash scripts/boot-linux.sh
+```
+The credentials are root/root.
+
+Hitting control-c a few times will exit the simulator. Depending on what is
+running under linux it is sometimes necessary to kill the spike PID.
+
+### Updating the Root File System
+To trace applications under linux it is necessary to add them to the root
+file system. This makes them available from the spike/linux console.
+
+In this example the 3 versions of dhrystone linux are built into the root
+file system.
+
+This script builds the `dhrystone_optN.1000.gcc.linux.riscv` elfs, adds them to
+the buildroot source tree, rebuilds rootfs, and copies the image to riscv-linux
+for use in the next section.
+
+```
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+bash scripts/build-trace-rootfs.sh
+```
+
+This script performs basic checking, and copies the dhrystone linux ELFS to 
+a location in the buildroot tree.
+
+```
+${BUILDROOT}/output/target/root/trace_elfs
+```
+
+This location ensures access to the elfs once the root file system has been recompiled and linux has been booted.
+
+### Invoke Linux and Generate the Traces
+
+
+Once the new rootfs is built we boot linux on spike with tracing enabled from the
+command line. We use the boot-linux.sh script with two additional
+arguments. The first specifes the new rootfs and the second specifies the path
+for the STF trace output.
+
+```
+cd riscv-perf-model/traces/cpm.riscv-isa-sim
+bash scripts/boot-linux.sh --rootfs ./riscv-linux/trace_rootfs.cpio \
+                           --trace ./trace_out/linux_trace.zstf
+```
+Once linux boots, enter the root/root credentials, then from the ash shell
+cd to `trace_elfs and run the dhrystone_opt3.1000.gcc.bare.riscv.zstf
+
+### Sample Session
+
+A sample session: 
+
+```
+Welcome to Buildroot
+buildroot login: root
+root
+Password: root
+
+# cd trace_elfs
+cd trace_elfs
+# ls
+ls
+dhrystone_opt1.1000.gcc.linux.riscv  dhrystone_opt3.1000.gcc.linux.riscv
+dhrystone_opt2.1000.gcc.linux.riscv
+# ./dhrystone_opt3.1000.gcc.linux.riscv
+
+...snip...
+-I: traced 241546 instructions
+...snip...
+Str_2_Loc:           DHRYSTONE PROGRAM, 2'ND STRING
+        should be:   DHRYSTONE PROGRAM, 2'ND STRING
+
+Measured time too small to obtain meaningful results
+Please increase number of runs
+
+# <control-c>
+# ^C(spike) quit
+```
+
+Once you have exited spike and are returned to the main o/s, the trace_out
+directory will hold the trace file.
+```
+-rw-r--r-- 1 random agroup 12097 Jan 1 00:00 linux_trace.zstf
+```
+
+Note _any_ trace-enabled ELF you run while in spike linux will be added to the
+same trace file.
+
+This is useful in cases.
+
+For other use cases, check the USAGE.md file in the Spike-STF repo for
+instructions on how to use initd to automate linux based trace generation.
+
+See [Automating Linux Tracing with INIT.d](https://github.com/jeffnye-gh/cpm.riscv-isa-sim/blob/spike_stf/USAGE.md#Automating-linux-tracing-with-initd)
+
+
+-----------------------------------------------------
 ### Generating an STF Trace with Dromajo
 
 #### Build an STF-Capable Dromajo
@@ -251,6 +555,5 @@ Now, run that trace on olympia:
 % ./olympia ../traces/stf_trace_gen/dromajo/run/dhry_riscv.zstf
 Running...
 olympia: STF file input detected
-
 ...
 ```