Getting Started

This page contains information for sourcing dependencies and getting started with Riescue.

Installing Dependencies

Dependencies

This repo currently uses a singularity container flow to manage the environment. See the Apptainer docs for information on installing Apptainer.

All dependencies can be found listed in the infra/Container.def file. Users looking to add to their own container or manage dependencies should refer to this file for all dependencies used.

Installing Riescue as a package after cloning the repo

Users can install the package

git clone https://github.com/tenstorrent/riescue.git
cd riescue
pip install .

Installing Riescue as a package without cloning.

pip install git+https://github.com/tenstorrent/riescue.git

Sourcing dependencies with singularity:

To source dependencies with singularity, users need to build the container. The container-build script will build the container and install all required dependencies.

./infra/container-build

Users can enter the container by running:

./infra/container-run

The container installs python3.9, default python dependencies, and the default simulators (whisper and spike). It doesn’t currently include riscv-gnu-toolchain.

Simulators and Toolchains

Installing and Configuring Simulators

Riescue invokes the following Instruction Set Simulators. Like simulators can be set with a command line switch, environment variable, or added to the PATH.

  • whisper - whisper GitHub

    • whisper is a git submodule and can be built in the container using ./infra/build_whisper.sh

    • External whisper binaries can be passed in using the environment variable WHISPER_PATH or the command line switch --whisper_path

  • spike - spike GitHub, TT-Spike Fork GitHub

    • spike is installed normally in the container flow.

    • External spike binaries can be passed in using the environment variable SPIKE_PATH or the command line switch --spike_path

    • Please see the infra/Container.def container definition file for more info on building Spike from the TT-source

After installing the dependencies, users can configure riescue to point to the correct toolchains and simulators.

Installing and Configuring Toolchains

RiescueD uses the riscv-gnu-toolchain to assemble, compile, and disassemble ELF tests. Like simulators, toolchains can be set with a command line switch, environment variable, or added to the PATH.

  • riscv64-unknown-elf-gcc is the default executable used for assembling and compiling

    • Tools will use the --compiler_path switch, followed by the environment variable RV_GCC, then riscv64-unknown-elf-gcc in the PATH

  • riscv64-unknown-elf-objdump is the default executable used for disassembling

    • Tools will use the --disassembler_path switch, followed by the environment variable RV_OBJDUMP, then riscv64-unknown-elf-objdump in the PATH

With all dependencies sourced, users should be able to run the ./riescued.py script to run the RiescueD tests.

What next? See the RiescueD User Guide page for information on getting started with RiESCUE.

Developing

Interested in making changes or contributing?

The main dependency needed for developing is a copy of the repo, singularity, and a basic python version installed.

Users can install the package in editable mode to make changes to the codebase while still in the package:

git clone https://github.com/tenstorrent/riescue.git
cd riescue
pip install -e .

Note that python dependencies are found in the pyproject.toml file. The container manually installs python dependencies when running ./infra/container-build.

Users can add dependencies to pyproject.toml and test locally with pip install -e .. Rebuild the container to include new dependencies in the container image.

See the Contributing page for additional information.