Intro to RiESCUE, RiescueD, and RiescueC

What’s RiESCUE?

RiESCUE is an open-source Python library for generating RISC-V assembly tests. It compiles assembly tests into ELF binaries and uses instruction set simulators during generation to validate test correctness.

RiESCUE provides two main tools: RiescueD for writing directed tests with special assembly directives, and RiescueC for generating self-checking compliance tests.

RiESCUE Directed Testing Framework - RiescueD

Writing directed RISC-V assembly tests by hand can be time consuming, hard to maintain, and leads to static tests. RiescueD speeds up the test development process by providing a framework for writing directed tests while controlling the environment, offering an extensible test runtime environment, and providing constrained randomization of memory addresses and data values.

Users provide a directed test case written in assembly with Riescue Directives and a CPU configuration file detailing the memory map and ISA of the target system. RiescueD uses this configuration to setup the environment and the test runtime environment. It compiles and runs the test on an Instruction Set Simulator to verify the test is valid. This enables quick development of directed tests without having to write the test runtime environment from scratch, manage the environment, generate the correct memory map, or randomize memory addresses and data values.

../_images/riescued_diagram.png

RiescueD provides a set of tools and directives to control the test scenario. This includes:

  • randomized memory address and data values

  • automatic page table generation

  • multiple privilege modes (machine, supervisor, user)

  • paging mode support (sv39, sv48, sv57)

  • OS simulation with exception handling and scheduling

  • multiple processor testing (MP)

RiescueD use cases:

RiescueD excels as a directed test framework when used to bringup and verify new RISC-V features. The utilities provided in RiescueD let test writers focus on writing test logic and not worry about the environment and test runtime environment. This allows for both quick bringup for new features and randomized test generation for regression testing.

RiescueD also excels as a framework to build complex test generators on top of. With RiescueD handling the environment and test runtime environment, test generators using the framework can focus on generating interesting stimulus instead of a complex environment and managing virtual memory. Combined with support for multiprocessor testing (MP), this creates an extensible framework for generating complex tests for a range of RISC-V platforms.

For examples on how to write directed tests, see the RiescueD Workflow Guide.

RiESCUE Compliance Testing - RiescueC

RiescueC is a specialized test generator that generates self-checking compliance tests for RISC-V extensions. It provides bringup, test plan, and compliance modes for generating tests.

  • bringup mode uses a CPU configuration file and a set of extensions and/or instructions to generate a self-checking test targeting instruction based compliance

  • test plan mode uses a CPU configuration file and a TestPlan object to generate architectural compliance tests for non-instruction based compliance

  • compliance mode uses a CPU configuration file and an ISA string to generate a suite of self-checking tests.

More information and user guides for RiescueC will be added with the release of RiescueC.

RiescueC Use Cases:

RiescueC excels for generating self-checking compliance tests targeting instruction and architectural compliance. bringup mode allows for bringing up new extensions, while test plan mode allows for generating architectural compliance tests for non-instruction based compliance. Both are useful for bringing up and verifying ISA compliance while developing RISC-V platforms. compliance mode generates suites of tests useful for regression testing for mature platforms.

Next Steps

See the First RiescueD Test tutorial to get started on a basic directed test.