Skip to content

rescind spike_stf support #261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+6 −309
Open

rescind spike_stf support #261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
315 changes: 6 additions & 309 deletions traces/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,5 @@
# 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).

Expand All @@ -33,16 +11,6 @@ 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
Expand Down Expand Up @@ -125,290 +93,18 @@ 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) 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
```
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.

To run an STF file, provide the path to olympia:
To run the STF file, just provide it 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
Expand Down Expand Up @@ -555,5 +251,6 @@ Now, run that trace on olympia:
% ./olympia ../traces/stf_trace_gen/dromajo/run/dhry_riscv.zstf
Running...
olympia: STF file input detected

...
```
Binary file removed traces/dhrystone_opt1.zstf
View file
Open in desktop
Binary file not shown.
Binary file removed traces/dhrystone_opt2.zstf
View file
Open in desktop
Binary file not shown.
Binary file removed traces/dhrystone_opt3.zstf
View file
Open in desktop
Binary file not shown.