RiescueD

RiescueD is the Riescue Directed Test Framework used to generate directed tests. It consists of a Python library and a command-line interface. The main workflow for writing directed tests is:

  1. Write .s file using assembly with RiescueD Directives (see RiescueD Directives)

  2. Provide system memory map and configuration in cpuconfig .json file (see Configuration Schema Reference)

  3. Run RiescueD to produce:

    • ELF binary

    • .S assembly file

    • .ld Linker Script

Command-line Interface

The main entry point for the framework is the riescued.py wraper script. To see available run options, run:

riescued  -h

To run a directed test, use

riescued  --testname <path/to/test.s> --cpuconfig <path/to/cpuconfig.json>

You can also run a wrapper script, e.g.

from riescue import RiescueD

RiescueD.run_cli("-t test.s".split())
RiescueD.run_cli(["--t", "test.s"])

API

The RiescueD python library can also be used to generate directed tests.

class riescue.RiescueD(testfile: Path, cpuconfig: Path = PosixPath('dtest_framework/lib/config.json'), run_dir: Path = PosixPath('.'), seed: int | None = None, toolchain: Toolchain | None = None)

Bases: CliBase

RiescueD is the main class for the RiescueD framework. Used to generate and compile tests.

Constructor makes run_dir if it doesn’t exist and picks a random seed if unset.

Parameters:

  • testfile – RiescueD Assembly File (.rasm) ; to be suffixed with .rasm in the future.

  • cpuconfig – CPU Config file with memory map and features

  • run_dir – The directory to run the test in. Defaults to current directory

  • seed – The seed to use for the random number generator. Defaults to a random number in range 0 to 2^32

  • toolchain – The Toolchain to use for the test. Defaults to a default Toolchain object if not provided

run(cl_args: Namespace, elaborate_only: bool = False, run_iss: bool = False) → GeneratedFiles

Run RiescueD configuration, generation, and compilation. Simulate if requested.

Returns:

Generated files; structure containing all generated files

configure(args: Namespace | None = None) → FeatMgr

Configure FeatMgr object for generation. FeatMgr can be modified before generation.

Parameters:

args – optional argparse.Namespace object used to build FeatMgr. If not provided, FeatMgr is built with test header and cpu config.

Returns:

Constructed FeatMgr object

generate(featmgr: FeatMgr) → GeneratedFiles

Generate the test code into an assembly file, linker script, and any additional files.

Uses FeatMgr object to generate the test code. Modifies :returns: The internal generated_files instance, a GeneratedFiles object containing paths to generated files.

build(featmgr: FeatMgr, generator: Generator | None = None) → GeneratedFiles

Compile and disassemble the test code.

Parameters:

  • featmgr – FeatMgr object

  • generator – [Deprecated] Generator object, currently ignored

Returns:

The internal generated_files instance, a GeneratedFiles object containing paths to generated files.

simulate(featmgr: FeatMgr, iss: Spike | Whisper, whisper_config_json_override: Path | None = None) → Path

Run test code through ISS

Parameters:

  • featmgr – FeatMgr object

  • iss – Spike or Whisper object

  • whisper_config_json_override – Optional path to whisper config json file to override default

Returns:

Path to ISS log file