[rte] cleanups and optimizations (#1299)

stnolting · web-flow · commit 90537fa2a1bb · 2025-06-27T20:48:02.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -29,6 +29,7 @@ mimpid = 0x01040312 -> Version 01.04.03.12 -> v1.4.3.12
 
 | Date | Version | Comment | Ticket |
 |:----:|:-------:|:--------|:------:|
+| 27.06.2025 | 1.11.7.3 | RTE cleanups; double-trap exception now has highest priority | [#1299](https://github.com/stnolting/neorv32/pull/1299) |
 | 21.06.2025 | 1.11.7.2 | :test_tube: add double-trap exception (loosely based on the RISC-V `Smdbltrp` ISA extension) | [#1294](https://github.com/stnolting/neorv32/pull/1294) |
 | 20.06.2025 | 1.11.7.1 | remove WDT's "strict" configuration bit; minor rtl cleanups | [#1293](https://github.com/stnolting/neorv32/pull/1293) |
 | 20.06.2025 | [**:rocket:1.11.7**](https://github.com/stnolting/neorv32/releases/tag/v1.11.7) | **New release** | |
diff --git a/docs/datasheet/cpu.adoc b/docs/datasheet/cpu.adoc
@@ -1298,17 +1298,17 @@ Whenever any trap (synchronous or asynchronous) is taken into M-mode an internal
 only if the triggering trap does not cause a debug-mode entry. It is cleared again when executing an `mret` instruction.
 Hence, this flag indicates "_inside trap_" status when set. If a second _synchronous_ trap occurs while this flag is set,
 a double-trap exception is raised. The RISC-V-compliant "double-trap" exception code 16 (see <<_neorv32_trap_listing>>)
-is used to identify this event. In summary, an trap that is followed by a synchronous trap (without an `mret` in between)
+is used to identify this event. In summary, a trap that is followed by a synchronous trap (without an `mret` in between)
 causes a double-trap exception:
 
 .Double-Trap Scenarios
 [cols="<3,<3,<4"]
 [options="header", grid="rows"]
 |=======================
 | First Trap | Second Trap | Resulting State
-| Synchronous (e.g. `ecall`) | Synchronous (e.g. `ecall`) | **Double-trap**
+| Synchronous (e.g. `ecall`) | Synchronous (e.g. `ecall`) | **Double-trap exception**
 | Synchronous (e.g. `ecall`) | Asynchronous (interrupt)   | Second trap is not triggered; IRQs are automatically disabled upon trap entry (<<_mstatus>>.`MIE` automatically clears)
-| Asynchronous (interrupt)   | Synchronous (e.g. `ecall`) | **Double-trap**
+| Asynchronous (interrupt)   | Synchronous (e.g. `ecall`) | **Double-trap exception**
 | Asynchronous (interrupt)   | Asynchronous (interrupt)   | Second trap is not triggered; IRQs are automatically disabled upon trap entry (<<_mstatus>>.`MIE` automatically clears); see <<_nested_interrupts>>
 |=======================
 
@@ -1363,8 +1363,8 @@ can be used to output debug information, to bring the system into a safe state o
 |=======================
 | Prio. | `mcause`     | RTE Trap ID              | Cause                                | `mepc` | `mtval` | `mtinst` | Note
 8+^| **Exceptions** (_synchronous_ to instruction execution)
-| 1     | `0x00000001` | `TRAP_CODE_I_ACCESS`     | instruction access fault             | I-PC   | 0       | INS      | **fatal**
-| 2     | `0x00000010` | `TRAP_CODE_DOUBLE_TRAP`  | <<_double_trap_exception>>           | I-PC   | 0       | INS      | **fatal**
+| 1     | `0x00000010` | `TRAP_CODE_DOUBLE_TRAP`  | <<_double_trap_exception>>           | I-PC   | 0       | INS      | **fatal**
+| 2     | `0x00000001` | `TRAP_CODE_I_ACCESS`     | instruction access fault             | I-PC   | 0       | INS      | **fatal**
 | 3     | `0x00000002` | `TRAP_CODE_I_ILLEGAL`    | illegal instruction                  | PC     | 0       | INS      |
 | 4     | `0x00000000` | `TRAP_CODE_I_MISALIGNED` | instruction address misaligned       | PC     | 0       | INS      | **fatal**
 | 5     | `0x0000000b` | `TRAP_CODE_MENV_CALL`    | environment call from M-mode         | PC     | 0       | INS      |
diff --git a/docs/datasheet/software.adoc b/docs/datasheet/software.adoc
@@ -74,6 +74,7 @@ The NEORV32 HAL consists of the following files.
 | `neorv32_gpio.c`    | `neorv32_gpio.h`       | <<_general_purpose_input_and_output_port_gpio>> HAL
 | `neorv32_gptmr.c`   | `neorv32_gptmr.h`      | <<_general_purpose_timer_gptmr>> HAL
 | -                   | `neorv32_intrinsics.h` | Macros for intrinsics and custom instructions
+| -                   | `neorv32_legacy.h`     | Legacy / backwards-compatibility wrappers (**do not use for new designs**)
 | `neorv32_neoled.c`  | `neorv32_neoled.h`     | <<_smart_led_interface_neoled>> HAL
 | `neorv32_onewire.c` | `neorv32_onewire.h`    | <<_one_wire_serial_interface_controller_onewire>> HAL
 | `neorv32_pwm.c`     | `neorv32_pwm.h`        | <<_pulse_width_modulation_controller_pwm>> HAL
diff --git a/rtl/core/neorv32_cpu_control.vhd b/rtl/core/neorv32_cpu_control.vhd
@@ -907,8 +907,8 @@ begin
     elsif rising_edge(clk_i) then
       trap_ctrl.cause <= (others => '0'); -- default
       -- standard RISC-V exceptions --
-      if    (trap_ctrl.exc_buf(exc_iaccess_c)  = '1') then trap_ctrl.cause <= trap_iaf_c; -- instruction access fault
-      elsif (trap_ctrl.exc_buf(exc_doublet_c)  = '1') then trap_ctrl.cause <= trap_dbt_c; -- double-trap
+      if    (trap_ctrl.exc_buf(exc_doublet_c)  = '1') then trap_ctrl.cause <= trap_dbt_c; -- double-trap
+      elsif (trap_ctrl.exc_buf(exc_iaccess_c)  = '1') then trap_ctrl.cause <= trap_iaf_c; -- instruction access fault
       elsif (trap_ctrl.exc_buf(exc_illegal_c)  = '1') then trap_ctrl.cause <= trap_iil_c; -- illegal instruction
       elsif (trap_ctrl.exc_buf(exc_ialign_c)   = '1') then trap_ctrl.cause <= trap_ima_c; -- instruction address misaligned
       elsif (trap_ctrl.exc_buf(exc_ecall_c)    = '1') then trap_ctrl.cause <= trap_env_c(6 downto 2) & replicate_f(csr.prv_level, 2); -- environment call (U/M)
diff --git a/rtl/core/neorv32_package.vhd b/rtl/core/neorv32_package.vhd
@@ -29,7 +29,7 @@ package neorv32_package is
 
   -- Architecture Constants -----------------------------------------------------------------
   -- -------------------------------------------------------------------------------------------
-  constant hw_version_c : std_ulogic_vector(31 downto 0) := x"01110702"; -- hardware version
+  constant hw_version_c : std_ulogic_vector(31 downto 0) := x"01110703"; -- hardware version
   constant archid_c     : natural := 19; -- official RISC-V architecture ID
   constant XLEN         : natural := 32; -- native data path width
 
diff --git a/sim/neorv32_tb.vhd b/sim/neorv32_tb.vhd
@@ -346,7 +346,8 @@ begin
     FIFO_WIDTH => 32+4+1,
     FIFO_RSYNC => false,
     FIFO_SAFE  => true,
-    FULL_RESET => true
+    FULL_RESET => true,
+    OUT_GATE   => false
   )
   port map (
     -- control --
diff --git a/sw/example/bus_explorer/main.c b/sw/example/bus_explorer/main.c
@@ -62,10 +62,10 @@ int main() {
 
   // capture all exceptions and give debug info via UART
   neorv32_rte_setup();
-  neorv32_rte_handler_install(RTE_TRAP_L_MISALIGNED, memory_trap_handler);
-  neorv32_rte_handler_install(RTE_TRAP_L_ACCESS, memory_trap_handler);
-  neorv32_rte_handler_install(RTE_TRAP_S_MISALIGNED, memory_trap_handler);
-  neorv32_rte_handler_install(RTE_TRAP_S_ACCESS, memory_trap_handler);
+  neorv32_rte_handler_install(TRAP_CODE_L_MISALIGNED, memory_trap_handler);
+  neorv32_rte_handler_install(TRAP_CODE_L_ACCESS, memory_trap_handler);
+  neorv32_rte_handler_install(TRAP_CODE_S_MISALIGNED, memory_trap_handler);
+  neorv32_rte_handler_install(TRAP_CODE_S_ACCESS, memory_trap_handler);
 
   // disable all interrupt sources
   neorv32_cpu_csr_write(CSR_MIE, 0);
diff --git a/sw/example/demo_clint/main.c b/sw/example/demo_clint/main.c
@@ -77,8 +77,8 @@ int main() {
   neorv32_clint_mtimecmp_set(-1);
 
   // install CLINT handlers to RTE
-  neorv32_rte_handler_install(RTE_TRAP_MTI, mti_irq_handler);
-  neorv32_rte_handler_install(RTE_TRAP_MSI, msi_irq_handler);
+  neorv32_rte_handler_install(TRAP_CODE_MTI, mti_irq_handler);
+  neorv32_rte_handler_install(TRAP_CODE_MSI, msi_irq_handler);
 
   // start real time clock
   neorv32_uart0_printf("\nStarting real-time clock demo...\n");
diff --git a/sw/example/demo_dma/main.c b/sw/example/demo_dma/main.c
@@ -63,7 +63,7 @@ int main() {
   neorv32_uart0_printf("Descriptor FIFO depth: %u\n", neorv32_dma_get_descriptor_fifo_depth());
 
   // install DMA interrupt handler
-  neorv32_rte_handler_install(DMA_RTE_ID, dma_firq_handler);
+  neorv32_rte_handler_install(DMA_TRAP_CODE, dma_firq_handler);
 
   // enable DMA
   neorv32_dma_enable();
diff --git a/sw/example/demo_dual_core_rte/main.c b/sw/example/demo_dual_core_rte/main.c
@@ -115,15 +115,15 @@ int app_main(void) {
 
   // setup machine timer interrupt for ALL cores
   neorv32_clint_mtimecmp_set(0); // initialize core-specific MTIMECMP
-  neorv32_rte_handler_install(RTE_TRAP_MTI, trap_handler_mtmi); // install trap handler
+  neorv32_rte_handler_install(TRAP_CODE_MTI, trap_handler_mtmi); // install trap handler
   neorv32_cpu_csr_set(CSR_MIE, 1 << CSR_MIE_MTIE); // enable interrupt source
 
   // setup machine software interrupt for ALL cores
-  neorv32_rte_handler_install(RTE_TRAP_MSI, trap_handler_mswi); // install trap handler
+  neorv32_rte_handler_install(TRAP_CODE_MSI, trap_handler_mswi); // install trap handler
   neorv32_cpu_csr_set(CSR_MIE, 1 << CSR_MIE_MSIE); // enable interrupt source
 
   // setup machine environment call trap for ALL cores
-  neorv32_rte_handler_install(RTE_TRAP_MENV_CALL, trap_handler_ecall); // install trap handler
+  neorv32_rte_handler_install(TRAP_CODE_MENV_CALL, trap_handler_ecall); // install trap handler
 
 
   // trigger environment call exception (just to test the according handler)
diff --git a/sw/example/demo_emulate_unaligned/main.c b/sw/example/demo_emulate_unaligned/main.c
@@ -1,7 +1,7 @@
 // ================================================================================ //
 // The NEORV32 RISC-V Processor - https://github.com/stnolting/neorv32              //
 // Copyright (c) NEORV32 contributors.                                              //
-// Copyright (c) 2020 - 2024 Stephan Nolting. All rights reserved.                  //
+// Copyright (c) 2020 - 2025 Stephan Nolting. All rights reserved.                  //
 // Licensed under the BSD-3-Clause license, see LICENSE for details.                //
 // SPDX-License-Identifier: BSD-3-Clause                                            //
 // ================================================================================ //
@@ -135,7 +135,7 @@ int main() {
   neorv32_uart0_printf("\nUnaligned load with emulation:\n");
 
   // install trap handler for "unaligned load address" exception
-  neorv32_rte_handler_install(RTE_TRAP_L_MISALIGNED, trap_handler_emulate_unaligned_lw);
+  neorv32_rte_handler_install(TRAP_CODE_L_MISALIGNED, trap_handler_emulate_unaligned_lw);
 
   addr = ((uint32_t)&data_block[0]) + 1; // = unaligned address
   neorv32_uart0_printf("MEM[0x%x] = ", addr);
diff --git a/sw/example/demo_gpio/main.c b/sw/example/demo_gpio/main.c
@@ -15,29 +15,34 @@
 /** User configuration */
 #define BAUD_RATE 19200
 
+volatile uint32_t timestamp = 0;
+
+
+
+static void puth(uint32_t num) {
+
+  int i = 0;
+  const char hex_symbols[] = "0123456789ABCDEF";
+  for (i=0; i<8; i++) {
+    uint32_t index = (num >> (28 - 4*i)) & 0xF;
+    neorv32_uart_tx_put(NEORV32_UART0, hex_symbols[index]);
+  }
+  neorv32_uart_tx_put(NEORV32_UART0, '\n');
+}
+
+
 
 /**********************************************************************//**
  * GPIO input pin(s) interrupt handler.
  **************************************************************************/
 void gpio_interrupt_handler(void) {
 
-  // get bit mask of all those input pin that caused this interrupt
-  uint32_t active = neorv32_gpio_irq_get();
-
-  // clear the active pins that we are "handling" here
-  neorv32_gpio_irq_clr(active);
-
-  // "handle" the individual pin interrupts:
-  // we just print the pin number of the triggering inputs
-  int i;
-  neorv32_uart0_printf("\nGPIO interrupt from pin(s): ");
-  for (i=0; i<32; i++) {
-    if (active & 1) {
-      neorv32_uart0_printf("%u ", i);
-    }
-    active = active >> 1;
-  }
-  neorv32_uart0_printf("\n");
+  neorv32_gpio_irq_clr(-1);
+  uint32_t current = (uint32_t)neorv32_clint_time_get();
+  uint32_t delta = current - timestamp;
+  //neorv32_uart0_printf("0x%x 0x%x 0x%x\n", current, timestamp, delta);
+  puth(delta);
+  timestamp = current;
 }
 
 
@@ -68,17 +73,17 @@ int main(void) {
   }
 
   // configure CPU's GPIO controller interrupt
-  neorv32_rte_handler_install(GPIO_RTE_ID, gpio_interrupt_handler); // install GPIO trap handler
+  neorv32_rte_handler_install(GPIO_TRAP_CODE, gpio_interrupt_handler); // install GPIO trap handler
   neorv32_cpu_csr_set(CSR_MIE, 1 << GPIO_FIRQ_ENABLE); // enable GPIO FIRQ channel
   neorv32_cpu_csr_set(CSR_MSTATUS, 1 << CSR_MSTATUS_MIE); // enable machine-mode interrupts
 
   // configure GPIO input's IRQ trigger
   int i;
   for (i=0; i<32; i+=4) {
-    neorv32_gpio_irq_setup(i+0, GPIO_TRIG_LEVEL_LOW);    // this pin's interrupt fires on low-level
-    neorv32_gpio_irq_setup(i+1, GPIO_TRIG_LEVEL_HIGH);   // this pin's interrupt fires on high-level
-    neorv32_gpio_irq_setup(i+2, GPIO_TRIG_EDGE_FALLING); // this pin's interrupt fires on a falling edge
-    neorv32_gpio_irq_setup(i+3, GPIO_TRIG_EDGE_RISING);  // this pin's interrupt fires on a rising edge
+    neorv32_gpio_irq_setup(i+0, GPIO_TRIG_LEVEL_HIGH);    // this pin's interrupt fires on low-level
+    //neorv32_gpio_irq_setup(i+1, GPIO_TRIG_LEVEL_HIGH);   // this pin's interrupt fires on high-level
+    //neorv32_gpio_irq_setup(i+2, GPIO_TRIG_EDGE_FALLING); // this pin's interrupt fires on a falling edge
+    //neorv32_gpio_irq_setup(i+3, GPIO_TRIG_EDGE_RISING);  // this pin's interrupt fires on a rising edge
   }
 
   // enable all GPIO input pin interrupts
diff --git a/sw/example/demo_gptmr/main.c b/sw/example/demo_gptmr/main.c
@@ -60,7 +60,7 @@ int main() {
 
 
   // install GPTMR interrupt handler
-  neorv32_rte_handler_install(GPTMR_RTE_ID, gptmr_firq_handler);
+  neorv32_rte_handler_install(GPTMR_TRAP_CODE, gptmr_firq_handler);
 
   // configure timer for 0.5Hz ticks with clock divisor = 8
   neorv32_gptmr_setup(CLK_PRSC_8, neorv32_sysinfo_get_clk() / (8 * 2));
diff --git a/sw/example/demo_semihosting/main.c b/sw/example/demo_semihosting/main.c
@@ -45,7 +45,7 @@ int main() {
 
   // hardware setup
   neorv32_rte_setup();
-  neorv32_rte_handler_install(RTE_TRAP_BREAKPOINT, ebreak_trap_handler);
+  neorv32_rte_handler_install(TRAP_CODE_BREAKPOINT, ebreak_trap_handler);
   neorv32_uart0_setup(BAUD_RATE, 0);
 
   // say hello via UART0
diff --git a/sw/example/demo_slink/main.c b/sw/example/demo_slink/main.c
@@ -118,7 +118,7 @@ int main() {
   neorv32_slink_tx_clear();
 
   // NEORV32 runtime environment: install SLINK FIRQ handler
-  neorv32_rte_handler_install(SLINK_RTE_ID, slink_firq_handler);
+  neorv32_rte_handler_install(SLINK_TRAP_CODE, slink_firq_handler);
   neorv32_cpu_csr_set(CSR_MIE, 1 << SLINK_FIRQ_ENABLE); // enable SLINK FIRQ
   neorv32_cpu_csr_set(CSR_MSTATUS, 1 << CSR_MSTATUS_MIE); // enable machine-mode interrupts
 
diff --git a/sw/example/demo_spi_irq/main.c b/sw/example/demo_spi_irq/main.c
@@ -1,7 +1,7 @@
 // ================================================================================ //
 // The NEORV32 RISC-V Processor - https://github.com/stnolting/neorv32              //
 // Copyright (c) NEORV32 contributors.                                              //
-// Copyright (c) 2020 - 2024 Stephan Nolting. All rights reserved.                  //
+// Copyright (c) 2020 - 2025 Stephan Nolting. All rights reserved.                  //
 // Licensed under the BSD-3-Clause license, see LICENSE for details.                //
 // SPDX-License-Identifier: BSD-3-Clause                                            //
 // ================================================================================ //
@@ -78,7 +78,7 @@ int main()
   }
 
   // enable IRQ system
-  neorv32_rte_handler_install(SPI_RTE_ID, spi_irq_handler); // SPI to RTE
+  neorv32_rte_handler_install(SPI_TRAP_CODE, spi_irq_handler); // SPI to RTE
   neorv32_cpu_csr_set(CSR_MIE, 1 << SPI_FIRQ_ENABLE); // enable SPI FIRQ
   neorv32_cpu_csr_set(CSR_MSTATUS, 1 << CSR_MSTATUS_MIE); // enable machine-mode interrupts
 
diff --git a/sw/example/demo_trng/main.c b/sw/example/demo_trng/main.c
@@ -66,7 +66,7 @@ int main(void) {
 
   // setup NEORV32 runtime environment
   neorv32_rte_setup();
-  neorv32_rte_handler_install(TRNG_RTE_ID, trng_firq_handler);
+  neorv32_rte_handler_install(TRNG_TRAP_CODE, trng_firq_handler);
   neorv32_cpu_csr_set(CSR_MSTATUS, 1 << CSR_MSTATUS_MIE);
 
   // setup UART at default baud rate, no interrupts
diff --git a/sw/example/demo_twd/main.c b/sw/example/demo_twd/main.c
@@ -65,13 +65,13 @@ int main() {
     neorv32_uart0_printf("TWD available with rx fifo depth of %i and tx fifo depth of %i\n",
                          neorv32_twd_get_rx_fifo_depth(), neorv32_twd_get_tx_fifo_depth());
   }
-  
+
   // setup TWD
-  neorv32_rte_handler_install(TWD_RTE_ID, isr_twd);
+  neorv32_rte_handler_install(TWD_TRAP_CODE, isr_twd);
   neorv32_twd_set_tx_dummy(status);
   neorv32_twd_setup(TWD_DEVICE_ID, 0, 1, 0, 0, 1, 0);
   neorv32_cpu_csr_set(CSR_MIE,
-                      1 << TWD_FIRQ_ENABLE); 
+                      1 << TWD_FIRQ_ENABLE);
   neorv32_cpu_csr_set(CSR_MSTATUS,
                       1 << CSR_MSTATUS_MIE);
 
diff --git a/sw/example/processor_check/main.c b/sw/example/processor_check/main.c
diff --git a/sw/lib/include/neorv32.h b/sw/lib/include/neorv32.h
diff --git a/sw/lib/include/neorv32_legacy.h b/sw/lib/include/neorv32_legacy.h
diff --git a/sw/lib/include/neorv32_rte.h b/sw/lib/include/neorv32_rte.h
diff --git a/sw/lib/source/neorv32_rte.c b/sw/lib/source/neorv32_rte.c
