Merge pull request #324 from rust-embedded/rvrt-asm

`riscv-rt`: Use `_start_rust` and `hal_main`

Author: romancardenas

riscv-rt/CHANGELOG.md

@@ -25,11 +25,18 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   4. `_start_DefaultHandler_trap` and `_continue_trap` (if `v-trap` is enabled).
   5. `_start_trap_rust`.
   6. Other code in `.trap` section (usually, none)
+- Now, `riscv-rt` jumps to `_start_rust` instead of `main` directly. This allows us
+  to leave input parameters preservation to the Rust compiler.
+- `_default_setup_interrupts` is now written in Rust and called from `_start_rust`.
+- Now, `_start_rust` jumps to `hal_main` instead of `main` directly. At linker level,
+  `hal_main` maps to `main` if not defined. However, we now allow HALs to inject
+  additional configuration code before jumping to the final user's `main` function.
 
 ### Fixed
 
 - `clippy` fixes
 - Merged `cfg_global_asm!` macro invocations to guarantee contiguous code generation.
+- Use `.balign` instead of `.align` in `_default_abort`
 
 ## [v0.15.0] - 2025-06-10
 

riscv-rt/link.x.in

@@ -52,6 +52,11 @@ PROVIDE(_start_trap = _default_start_trap);
 EXTERN(_default_setup_interrupts);
 PROVIDE(_setup_interrupts = _default_setup_interrupts);
 
+/* Default main routine. If no hal_main symbol is provided, then hal_main maps to main, which
+   is usually defined by final users via the #[riscv_rt::entry] attribute. Using hal_main
+   instead of main directly allow HALs to inject code before jumping to user main. */
+PROVIDE(hal_main = main);
+
 /* Default exception handler. By default, the exception handler is abort.
    Users can override this alias by defining the symbol themselves */
 PROVIDE(ExceptionHandler = abort);

riscv-rt/src/asm.rs

@@ -113,7 +113,7 @@ _abs_start:
     "sub t1, t1, t0",
     "andi sp, t1, -16 // align stack to 16-bytes
     add s0, sp, zero",
-// STORE A0..A2 IN THE STACK, AS THEY WILL BE NEEDED LATER BY main
+// STORE A0..A2 IN THE STACK, AS THEY WILL BE NEEDED LATER BY _start_rust
     #[cfg(target_arch = "riscv32")]
     "addi sp, sp, -4 * 4 // we must keep stack aligned to 16-bytes
     sw a0, 4 * 0(sp)
@@ -183,8 +183,7 @@ _abs_start:
     "fscsr x0",
 }
 
-// SET UP INTERRUPTS, RESTORE a0..a2, AND JUMP TO MAIN RUST FUNCTION
-    "call _setup_interrupts",
+// RESTORE a0..a2, AND JUMP TO _start_rust FUNCTION
     #[cfg(target_arch = "riscv32")]
     "lw a0, 4 * 0(sp)
     lw a1, 4 * 1(sp)
@@ -195,7 +194,7 @@ _abs_start:
     ld a1, 8 * 1(sp)
     ld a2, 8 * 2(sp)
     addi sp, sp, 8 * 4",
-    "la t0, main
+    "la t0, _start_rust
     jr t0
     .cfi_endproc",
 
@@ -210,21 +209,6 @@ _default_mp_hook:
     j 1b
 2:  li a0, 1
     ret",
-    // Default implementation of `_setup_interrupts` sets the trap vector to `_start_trap` in direct mode.
-    // In vectored mode, it sets the trap vector to `_vector_table`.
-    // Users can override this function by defining their own `_setup_interrupts`
-    ".global _default_setup_interrupts
-_default_setup_interrupts:",
-    #[cfg(not(feature = "v-trap"))]
-    "la t0, _start_trap", // _start_trap is 4-byte aligned, so it corresponds to the Direct trap mode
-    #[cfg(feature = "v-trap")]
-    "la t0, _vector_table
-    ori t0, t0, 0x1", // _vector_table is at least 4-byte aligned, so we must set the bit 0 to activate the Vectored trap mode
-    #[cfg(feature = "s-mode")]
-    "csrw stvec, t0",
-    #[cfg(not(feature = "s-mode"))]
-    "csrw mtvec, t0",
-    "ret",
 );
 
 riscv_rt_macros::default_start_trap!();
@@ -235,7 +219,7 @@ riscv_rt_macros::vectored_interrupt_trap!();
 #[rustfmt::skip]
 global_asm!(
     ".section .text.abort
-.align 4
+.balign 4
 .global _default_abort
 _default_abort:  // make sure there is an abort symbol when linking
     j _default_abort"

riscv-rt/src/lib.rs

@@ -359,6 +359,24 @@
 //! If the `v-trap` feature is enabled, the trap vector is set to `_vector_table`
 //! in vectored mode. Users can override this function by defining their own `_setup_interrupts`.
 //!
+//! This function can be redefined in the following way:
+//!
+//! ``` no_run
+//! #[export_name = "_setup_interrupts"]
+//! pub fn setup_interrupts() {
+//!    // ...
+//! }
+//! ```
+//!
+//! ## `hal_main`
+//!
+//! Internally, `riscv-rt` does not jump to the `main` function created by the user using the
+//! [`#[entry]`][attr-entry] attribute. Instead, it jumps to the `hal_main` function.
+//! The linker will map `hal_main` to `main` if the prior is not defined, which is the typical case.
+//! However, the `hal_main` function allows HALs to inject additional code before jumping to the
+//! user's `main` function. This might be useful for certain HALs that need to perform additional
+//! configuration before the main function is executed.
+//!
 //! # Attributes
 //!
 //! ## Core exception handlers
@@ -552,10 +570,16 @@ pub mod exceptions;
 pub mod interrupts;
 
 #[cfg(feature = "s-mode")]
-use riscv::register::scause as xcause;
+use riscv::register::{
+    scause as xcause,
+    stvec::{self as xtvec, Stvec as Xtvec, TrapMode},
+};
 
 #[cfg(not(feature = "s-mode"))]
-use riscv::register::mcause as xcause;
+use riscv::register::{
+    mcause as xcause,
+    mtvec::{self as xtvec, Mtvec as Xtvec, TrapMode},
+};
 
 pub use riscv_pac::*;
 pub use riscv_rt_macros::{core_interrupt, entry, exception, external_interrupt};
@@ -571,6 +595,60 @@ pub use riscv_rt_macros::pre_init;
 #[doc(hidden)]
 pub static __ONCE__: () = ();
 
+/// Rust entry point (_start_rust)
+///
+/// Configures interrupts and calls main. This function never returns.
+///
+/// # Safety
+///
+/// This function should not be called directly by the user, and should instead
+/// be invoked by the runtime implicitly.
+#[cfg_attr(
+    any(target_arch = "riscv32", target_arch = "riscv64"),
+    link_section = ".init.rust"
+)]
+#[export_name = "_start_rust"]
+pub unsafe extern "C" fn start_rust(a0: usize, a1: usize, a2: usize) -> ! {
+    extern "Rust" {
+        fn _setup_interrupts();
+        fn hal_main(a0: usize, a1: usize, a2: usize) -> !;
+    }
+
+    _setup_interrupts();
+    hal_main(a0, a1, a2);
+}
+
+/// Default implementation of `_setup_interrupts`.
+///
+/// In direct mode (i.e., `v-trap` feature disabled), it sets the trap vector to `_start_trap`.
+/// In vectored mode (i.e., `v-trap` feature enabled), it sets the trap vector to `_vector_table`.
+///
+/// # Note
+///
+/// Users can override this function by defining their own `_setup_interrupts` function.
+///
+/// # Safety
+///
+/// This function should not be called directly by the user, and should instead
+/// be invoked by the runtime implicitly. It is expected to be called before the main function.
+#[export_name = "_default_setup_interrupts"]
+pub unsafe extern "Rust" fn setup_interrupts() {
+    extern "C" {
+        #[cfg(not(feature = "v-trap"))]
+        fn _start_trap();
+        #[cfg(feature = "v-trap")]
+        fn _vector_table();
+    }
+
+    let xtvec_val = match () {
+        #[cfg(not(feature = "v-trap"))]
+        _ => Xtvec::new(_start_trap as usize, TrapMode::Direct),
+        #[cfg(feature = "v-trap")]
+        _ => Xtvec::new(_vector_table as usize, TrapMode::Vectored),
+    };
+    xtvec::write(xtvec_val);
+}
+
 /// Registers saved in trap handler
 #[repr(C)]
 #[derive(Debug)]