Runtime Environment

Riescue’s Runtime Environment (referred to as the “Runtime”) is code included in the final test ELF binary. It initializes the execution environment, schedules tests, handles traps, and manages the End of Test (EOT).

Test vs Runtime

A test ELF can be divided into two parts: the Test and the Runtime. Test Code consists of discrete test cases to be ran in the Test Environment. After Test code is finished, it returns control back to the Runtime environment. It runs in the Test privilege mode.

The Runtime Environment or Runtime is generated by RiescueD and manages startup, scheduling, traps, and the end of test. It runs in Machine mode (M-mode).

        %%{init: {'themeVariables': {'fontFamily': 'Fira Code', monospace;}}}%%
flowchart LR

Handler["Runtime<br/>(Machine Mode)"]
Test["Test<br/>(Test Privilege)"]

Handler --> Test
Test   --> Handler

classDef mMode fill:#5164e0,stroke:#fa512e,stroke-width:3px,color:#fff
classDef handlerMode fill:#fa512e,stroke:#fa512e,stroke-width:3px,color:#000
classDef handlerBlock fill:#FEC3A4,stroke:#FEC3A4,stroke-width:3px,color:#0
classDef testMode fill:#7584e6,stroke:#7584e6,stroke-width:3px,color:#0
classDef testBlock fill:#C0C0E0,stroke:#C0C0E0,stroke-width:3px,color:#0

class Loader,EOT_Final mMode
class Handler handlerMode
class Test testMode

Test Code and Environment

Test Code is the code that is being tested. It can consist of hand written test cases in a directed test or generated by a test generator like RiescueC.

The environment used to run Test Code is the Test Environment. It consists of the paging mode, privilege mode, and virtualization support that a test should be ran with. The Test’s privilege mode or priv_mode is used to run all discrete tests. It can be of any privilege mode except VS , i.e. M, HS, U, or VU.

Hart Context

While in the Runtime Environment, the hart has access to a thread-local storage or Hart Context. This is used to store the test’s context during a trap, to ensure that asynchronou or unexpected traps don’t corrupt the test’s state.

The Hart Context is maintained until the Runtime returns control back to the Test

See the Variables for info on using the Hart Context.

Test API

Test code runs in the Test privilege mode. It runs until the test ends with a pass or a failure. This can be done by calling the ;#test_passed() or ;#test_failed() directives.

Additionally, tests can request some functionality from the Runtime using the Test API. This includes:

Riescue Directives - used to control test execution
Test Macros - used to assert traps and access Runtime variables

Note

This also inlcudes the syscall API, but in the future this will be moved to macros to simplify the API.

Runtime Code and Environment

Runtime Code is the code that’s used to intialize the Test Environment and run Test Code. It always runs in Machine mode (M-mode).

Runtime API

Runtime is generated by RiescueD based on the Test’s configuration and consists of a few different components. Each component has an API that is called by other Runtime components. Test code shouldn’t be accessing these APIs directly.

It’s used to intialize the Test’s environment by setting up paging, virtualization, privilege mode, and trap handling.

Configuration

Each test’s runtime is generated with a single configuration in mind. CLI shows the configuration options available on the command line. This configuration is contained in the FeatMgr class and is used to generate the correct Runtime code.

The input configuration includes:

priv_mode: The Test’s privilege mode
deleg_excp_to: Sets medeleg/mideleg for exception delegation (does not change runtime privilege)
paging_mode: The Test’s paging mode
env: If the test is virtualized (using Hypervisor) or bare metal
mp: The Test’s multi-processing mode

The FeatMgr class contains all configuration needed to generate the correct Runtime code.

Runtime Privilege Model

The Runtime always executes in Machine mode (M-mode). This ensures:

Consistent syscall handling regardless of test privilege
Ability to manage traps from any test privilege mode (M, S, U, VU)

Exception delegation registers (medeleg/mideleg/hedeleg/hideleg) control how non-ecall traps get delegated. By default, these are set randomly.

Test Modes

There are a few modes that can be used to generate the test ELF. Some modes cede more control than the default Runtime Environment

The different modes include: - default mode: Test Code + Runtime Code - wysiwyg mode: What You See Is What You Get - Test Code Only - linux mode: Test Code + Runtime’s Scheduler (no trap handling)

wysiwyg mode is useful for early bringup, minimal testbench support, and testing without privileged code.: linux mode is useful for testing with Linux support.

Runtime Components: