Subversion Repositories neorv32

:sectnums:

=== NEORV32 Runtime Environment

The NEORV32 software framework provides a minimal runtime environment (**RTE**) that takes care of a stable

and _safe_ execution environment by handling _all_ traps (= exceptions & interrupts). The RTE simplifies trap handling

by wrapping the CPU's _privileged architecture_ (i.e. trap-related CSRs) into a unified software API.

The NEORV32 RTE is a software library (`sw/lib/source/neorv32_rte.c`) that is part of the default processor library set.

It provides public functions via `sw/lib/include/neorv32_rte.h` for application interaction.

Once initialized, the RTE provides <<_default_rte_trap_handlers>> that catch all possible exceptions. These

default handlers just output a message via UART to inform the user when a certain trap has been triggered. The

default handlers can be overridden by the application code to install application-specific handler functions for each trap.

[IMPORTANT]

Using the RTE is **optional but highly recommended**. The RTE provides a simple and comfortable way of delegating

traps to application-specific handlers while making sure that all traps (even though they are not explicitly used

by the application) are handled correctly. Performance-optimized applications or embedded operating systems should

not use the RTE for delegating traps.

[NOTE]

For the **C standard runtime library** see section <>.

==== RTE Operation

The RTE handles the trap-related CSRs of the CPU's privileged architecture (<<_machine_trap_handling_csrs>>).

It initializes the <<_mtvec>> CSR, which provides the base entry point for all trap

handlers. The address stored to this register reflects the **first-level exception handler**, which is provided by the

NEORV32 RTE. Whenever an exception or interrupt is triggered this first-level handler is executed.

The first-level handler performs a complete context save, analyzes the source of the exception/interrupt and

calls the according **second-level exception handler**, which takes care of the actual exception/interrupt

handling. For this, the RTE manages a private look-up table to store the addresses of the according trap

handlers.

After the initial RTE setup, each entry in the RTE's trap handler's look-up table is initialized with a

<<_default_rte_trap_handlers>>. These default handler do not execute any trap-related operations - they

just output a message via the *primary UART (UART0)* to inform the user that a trap has occurred, that is not

handled by the actual application. After sending this message, the RTE tries to continue executing the user program.

==== Using the RTE

The NEORV32 is enabled by calling the RTE's setup function:

.Function Prototype: RTE Setup

[source,c]

----

void neorv32_rte_setup(void);

----

[NOTE]

The RTE should be enabled right at the beginning of the application's `main` function.

As mentioned above, _all_ traps will only trigger execution of the RTE's <<_default_rte_trap_handlers>>.

To use application-specific handlers, which actually _handle_ a trap, the default handlers can be overridden

by installing user-defined ones:

.Function Prototype: Installing an Application-Specific Trap Handler

[source,c]

----

int neorv32_rte_exception_install(uint8_t id, void (*handler)(void));

----

The first argument `id` defines the "trap ID" (for example a certain interrupt request) that shall be handled

by the user-defined handler. The second argument `*handler` is the actual function that implements the trap

handler. The function return zero on success and a non-zero value if an error occurred (invalid `id`). In this

case no modifications to the RTE's trap look-up-table will be made.

The custom handler functions need to have a specific format without any arguments an with no return value:

.Function Prototype: Custom Trap Handler

[source,c]

----

void custom_trap_handler_xyz(void) {

  // handle exception/interrupt...

}

----

.Custom Trap Handler Attributes

[WARNING]

Do NOT use the `((interrupt))` attribute for the application exception handler functions! This

will place a `mret` instruction to the end of it making it impossible to return to the first-level

exception handler of the RTE core, which will cause stack corruption.

The trap identifier `id` specifies the according trap cause. These can be an _asynchronous trap_ like

an interrupt from one of the processor modules or a _synchronous trap_ triggered by software-caused events

like an illegal instruction or an environment call instruction. The `sw/lib/include/neorv32_rte.h` library files

provides aliases for trap events supported by the CPU (see <<_neorv32_trap_listing>>) that can be used when

installing custom trap handler functions:

.RTE Trap ID List

[cols="<5,<12"]

[options="header",grid="rows"]

|=======================

| ID alias [C] | Description / trap causing event

| `RTE_TRAP_I_MISALIGNED` | instruction address misaligned

| `RTE_TRAP_I_ACCESS`     | instruction (bus) access fault

| `RTE_TRAP_I_ILLEGAL`    | illegal instruction

| `RTE_TRAP_BREAKPOINT`   | breakpoint (`ebreak` instruction)

| `RTE_TRAP_L_MISALIGNED` | load address misaligned

| `RTE_TRAP_L_ACCESS`     | load (bus) access fault

| `RTE_TRAP_S_MISALIGNED` | store address misaligned

| `RTE_TRAP_S_ACCESS`     | store (bus) access fault

| `RTE_TRAP_MENV_CALL`    | environment call from machine mode (`ecall` instruction)

| `RTE_TRAP_UENV_CALL`    | environment call from user mode (`ecall` instruction)

| `RTE_TRAP_MTI`          | machine timer interrupt

| `RTE_TRAP_MEI`          | machine external interrupt

| `RTE_TRAP_MSI`          | machine software interrupt

| `RTE_TRAP_FIRQ_0`       | fast interrupt channel 0

| `RTE_TRAP_FIRQ_1`       | fast interrupt channel 1

| `RTE_TRAP_FIRQ_2`       | fast interrupt channel 2

| `RTE_TRAP_FIRQ_3`       | fast interrupt channel 3

| `RTE_TRAP_FIRQ_4`       | fast interrupt channel 4

| `RTE_TRAP_FIRQ_5`       | fast interrupt channel 5

| `RTE_TRAP_FIRQ_6`       | fast interrupt channel 6

| `RTE_TRAP_FIRQ_7`       | fast interrupt channel 7

| `RTE_TRAP_FIRQ_8`       | fast interrupt channel 8

| `RTE_TRAP_FIRQ_9`       | fast interrupt channel 9

| `RTE_TRAP_FIRQ_10`      | fast interrupt channel 10

| `RTE_TRAP_FIRQ_11`      | fast interrupt channel 11

| `RTE_TRAP_FIRQ_12`      | fast interrupt channel 12

| `RTE_TRAP_FIRQ_13`      | fast interrupt channel 13

| `RTE_TRAP_FIRQ_14`      | fast interrupt channel 14

| `RTE_TRAP_FIRQ_15`      | fast interrupt channel 15

|=======================

The following example shows how to install a custom handler (`custom_mtime_irq_handler`) for handling

the RISC-V machine timer (MTIME) interrupt:

.Example: Installing the MTIME IRQ Handler

[source,c]

----

neorv32_rte_exception_install(RTE_TRAP_MTI, custom_mtime_irq_handler);

----

User-defined trap handlers can also be un-installed. This will remove the users trap handler from the RTE core

and will re-install the <<_default_rte_trap_handlers>> for the specific trap.

.Function Prototype: Installing an Application-Specific Trap Handler

[source,c]

----

int neorv32_rte_exception_uninstall(uint8_t id);

----

The argument `id` defines the identifier of the according trap that shall be un-installed. The function return zero

on success and a non-zero value if an error occurred (invalid `id`). In this case no modifications to the RTE's trap

look-up-table will be made.

The following example shows how to un-install the custom handler `custom_mtime_irq_handler` from the

RISC-V machine timer (MTIME) interrupt:

.Example: Removing the Custom MTIME IRQ Handler

[source,c]

----

neorv32_rte_exception_uninstall(RTE_TRAP_MTI);

----

==== Default RTE Trap Handlers

The default RTE trap handlers are executed when a certain trap is triggered that is not handled by a user-defined

application-specific trap handler. These default handler will just output a message giving additional debug information

via UART0 to inform the user and will try to resume normal execution of the application.

.Continuing Execution

[IMPORTAN]

In most cases the RTE can successfully continue operation when it catches an interrupt request, which is not handled

by the actual application program. However, if the RTE catches an un_handled exception like a bus access fault

continuing execution will most likely fail and the CPU will crash.

.RTE Default Trap Handler Output Example (Illegal Instruction)

[source]

----

 Illegal instruction @ PC=0x000002d6, MTVAL=0x00001537 

----

In this example the "Illegal instruction" _message_ describes the cause of the trap, which is an illegal instruction

exception here. `PC` shows the current program counter value when the trap occurred and `MTVAL` shows additional

debug information from the <<_mtval>> CSR. In this case it shows the encoding of the illegal instruction.

The specific _message_ corresponds to the trap code from the <<_mcause>> CSR (see <<_neorv32_trap_listing>>).

A full list of all messages and the according `mcause` trap codes are shown below.

.RTE Default Trap Handler Messages and According `mcause` Values

[cols="<5,^5"]

[options="header",grid="rows"]

|=======================

| Trap identifier | According `mcause` CSR value

| "Instruction address misaligned" | `0x00000000`

| "Instruction access fault"       | `0x00000001`

| "Illegal instruction"            | `0x00000002`

| "Breakpoint"                     | `0x00000003`

| "Load address misaligned"        | `0x00000004`

| "Load access fault"              | `0x00000005`

| "Store address misaligned"       | `0x00000006`

| "Store access fault"             | `0x00000007`

| "Environment call from U-mode"   | `0x00000008`

| "Environment call from M-mode"   | `0x0000000b`

| "Machine software interrupt"     | `0x80000003`

| "Machine timer interrupt"        | `0x80000007`

| "Machine external interrupt"     | `0x8000000b`

| "Fast interrupt 0"               | `0x80000010`

| "Fast interrupt 1"               | `0x80000011`

| "Fast interrupt 2"               | `0x80000012`

| "Fast interrupt 3"               | `0x80000013`

| "Fast interrupt 4"               | `0x80000014`

| "Fast interrupt 5"               | `0x80000015`

| "Fast interrupt 6"               | `0x80000016`

| "Fast interrupt 7"               | `0x80000017`

| "Fast interrupt 8"               | `0x80000018`

| "Fast interrupt 9"               | `0x80000019`

| "Fast interrupt a"               | `0x8000001a`

| "Fast interrupt b"               | `0x8000001b`

| "Fast interrupt c"               | `0x8000001c`

| "Fast interrupt d"               | `0x8000001d`

| "Fast interrupt e"               | `0x8000001e`

| "Fast interrupt f"               | `0x8000001f`

| "Unknown trap cause"             | _not defined_

|=======================

===== Bus Access Faults

For bus access faults the RTE default trap handlers also output the error code from the

<<_internal_bus_monitor_buskeeper>> to show the cause of the bus fault. One example is shown below.

.RTE Default Trap Handler Output Example (Load Access Bus Fault)

[source]

----

 Load access fault [TIMEOUT_ERR] @ PC=0x00000150, MTVAL=0xFFFFFF70 

----

The additional message encapsulated in `[ ]` shows the actual cause of the bus access fault.

Three different messages are possible here:

* `[TIMEOUT_ERR]`: The accessed memory-mapped module did not respond within the valid access time window.

In Most cases this is caused by accessing a module that has not been implemented or when accessing

"address space holes" (unused/unmapped addresses).

* `[DEVICE_ERR]`: The accesses memory-mapped module asserted it's error signal to indicate an invalid access.

For example this can be caused by trying to write to read-only registers or by writing data quantities (like a byte)

to devices that do not support sub-word write accesses.

* `[PMP_ERR]`: This indicates an access right violation caused by the <<_pmp_physical_memory_protection>>.