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 Environment
-----------------------------

A test ELF can be divided into two parts: the `Test Environment` and the `Runtime Environment`

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.

Runtime Code and Environment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`Runtime Code` is the code that's used to intialize the `Test Environment` and run `Test Code`.
Runtime is generated by RiescueD based on the Test's configuration and consists of a few different parts:

- :doc:`Loader <loader>`
- :doc:`Scheduler <scheduler>`
- :doc:`Trap Handler <trap_handler>`
- :doc:`OS <os>`
- :doc:`Macros <macros>`

It's used to intialize the Test's environment by setting up paging, virtualization, privilege mode, and trap handling.
It has it's own privilege mode it's ran with, depending on the Test's configuration. This Runtime privilege mode or ``runtime_priv_mode`` can be of a greater than or equal privilege as the Test's ``priv_mode``.


Configuration
-------------
Each test's runtime is generated with a single configuration in mind. :doc:`CLI <../config/cli>` shows the configuration options available on the command line.
This configuration is contained in the  :doc:`FeatMgr <../python_api/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``: The Runtime's privilege mode and privilege mode for trap handling. All trap handling and OS code uses this privilege mode.
- ``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  :doc:`FeatMgr <../python_api/FeatMgr>` class contains all configuration needed to generate the correct Runtime code.



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.




.. toctree::
   :maxdepth: 1
   :caption: Runtime Sections:

   loader
   scheduler
   trap_handler
   os
   macros