Merge #104

104: SBI mode r=almindor a=pgraubner

Introducing Supervisor Binary Interface (SBI) compatibility as a build-time feature. Main goal is to allow riscv-rt based implementations to be bootstrapped by a SBI-firmware (like in `qemu-system-riscv64`).

* Introduce compiler switches for assembly in order to switch between machine mode / supervisor mode
* Introduce cargo feature for conditional compilation
* Patch lib.rs for supervisor-mode compatibility

The only interface this PR is braking is `mp_hook`, which needs a mhartid replacement for smode. The hart id is passed by the caller.
Tested with `qemu-system-riscv64`.

See also documentation/features/sbi for further implementation details.

Co-authored-by: Pablo Graubner <2234137+pgraubner@users.noreply.github.com>

riscv-rt/CHANGELOG.md

@@ -7,9 +7,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- Optional cargo feature `s-mode` for supervisor mode, including conditional compilation for supervisor/machine mode instructions.
+
 ### Changed
 
 - Remove superfluous parentheses from link.x, which caused linker errors with nightly.
+- Changed `mp_hook` signature, hartid as passed as usize parameter by the caller (required for `s-mode` feature).
 
 ## [v0.9.0] - 2022-07-01
 

riscv-rt/Cargo.toml

@@ -10,6 +10,9 @@ keywords = ["riscv", "runtime", "startup"]
 license = "ISC"
 edition = "2018"
 
+[features]
+s-mode = []
+
 [dependencies]
 r0 = "1.0.0"
 riscv = "0.8"

riscv-rt/asm.S

@@ -46,8 +46,14 @@ _abs_start:
     .cfi_startproc
     .cfi_undefined ra
 
+    #ifdef SMODE
+    csrw sie, 0     // interrupt disable 
+    csrw sip, 0     // no pending interrupts
+    #else
     csrw mie, 0
     csrw mip, 0
+    #endif
+    
 
     li  x1, 0
     li  x2, 0
@@ -84,8 +90,13 @@ _abs_start:
     la gp, __global_pointer$
     .option pop
 
-    // Check hart id
+    #ifdef SMODE
+    // there is no equivalent of mhartid in supervisor mode.
+    // instead, the hartid is passed as paramter by SMODE
+    mv t2, a0   
+    #else 
     csrr t2, mhartid
+    #endif
     lui t0, %hi(_max_hart_id)
     add t0, t0, %lo(_max_hart_id)
     bgtu t2, t0, abort
@@ -165,7 +176,11 @@ default_start_trap:
     LOAD a7, 15*REGBYTES(sp)
 
     addi sp, sp, 16*REGBYTES
+    #ifdef SMODE
+    sret
+    #else
     mret
+    #endif
 
 /* Make sure there is an abort when linking */
 .section .text.abort

riscv-rt/assemble.sh

@@ -31,6 +31,14 @@ do
 
     riscv64-unknown-elf-gcc -ggdb3 -fdebug-prefix-map=$(pwd)=/riscv-rt -c -mabi=lp64${abi} -march=rv64${ext} asm.S -o bin/$crate.o
     riscv64-unknown-elf-ar crs bin/riscv64${ext}-unknown-none-elf.a bin/$crate.o
+
+    #s-mode
+    riscv64-unknown-elf-gcc -DSMODE -ggdb3 -fdebug-prefix-map=$(pwd)=/riscv-rt -c -mabi=ilp32${abi} -march=rv32${ext} asm.S -o bin/$crate.o
+    riscv64-unknown-elf-ar crs bin/riscv32${ext}-unknown-none-elf-smode.a bin/$crate.o
+
+    riscv64-unknown-elf-gcc -DSMODE -ggdb3 -fdebug-prefix-map=$(pwd)=/riscv-rt -c -mabi=lp64${abi} -march=rv64${ext} asm.S -o bin/$crate.o
+    riscv64-unknown-elf-ar crs bin/riscv64${ext}-unknown-none-elf-smode.a bin/$crate.o
+
 done
 
 rm bin/$crate.o

riscv-rt/build.rs

@@ -14,7 +14,13 @@ fn main() {
     if target.starts_with("riscv") {
         let mut target = Target::from_target_str(&target);
         target.retain_extensions("imfdc");
-        let archive = format!("bin/{}.a", target.to_string());
+        let archive: String;
+        if cfg!(feature = "s-mode") {
+            println!("======== compiling riscv-rt for s-mode");
+            archive = format!("bin/{}-smode.a", target.to_string());
+        } else {
+            archive = format!("bin/{}.a", target.to_string());
+        }
 
         fs::copy(&archive, out_dir.join(format!("lib{}.a", name))).unwrap();
         println!("cargo:rerun-if-changed={}", archive);

riscv-rt/examples/multi_core.rs

@@ -6,13 +6,12 @@ extern crate riscv;
 extern crate riscv_rt;
 
 use riscv::asm::wfi;
-use riscv::register::{mhartid, mie, mip};
+use riscv::register::{mie, mip};
 use riscv_rt::entry;
 
 #[export_name = "_mp_hook"]
 #[rustfmt::skip]
-pub extern "Rust" fn user_mp_hook() -> bool {
-    let hartid = mhartid::read();
+pub extern "Rust" fn user_mp_hook(hartid: usize) -> bool {
     if hartid == 0 {
         true
     } else {
@@ -42,9 +41,7 @@ pub extern "Rust" fn user_mp_hook() -> bool {
 }
 
 #[entry]
-fn main() -> ! {
-    let hartid = mhartid::read();
-
+fn main(hartid: usize) -> ! {
     if hartid == 0 {
         // Waking hart 1...
         let addr = 0x02000004;

riscv-rt/src/lib.rs

@@ -22,6 +22,8 @@
 //!
 //! - A `_sheap` symbol at whose address you can locate a heap.
 //!
+//! - Support for a runtime in supervisor mode, that can be bootstrapped via [Supervisor Binary Interface (SBI)](https://github.com/riscv-non-isa/riscv-sbi-doc)
+//!
 //! ``` text
 //! $ cargo new --bin app && cd $_
 //!
@@ -230,12 +232,13 @@
 //! This function is called from all the harts and must return true only for one hart,
 //! which will perform memory initialization. For other harts it must return false
 //! and implement wake-up in platform-dependent way (e.g. after waiting for a user interrupt).
+//! The parameter `hartid` specifies the hartid of the caller.
 //!
 //! This function can be redefined in the following way:
 //!
 //! ``` no_run
 //! #[export_name = "_mp_hook"]
-//! pub extern "Rust" fn mp_hook() -> bool {
+//! pub extern "Rust" fn mp_hook(hartid: usize) -> bool {
 //!    // ...
 //! }
 //! ```
@@ -245,7 +248,7 @@
 //! ### `ExceptionHandler`
 //!
 //! This function is called when exception is occured. The exception reason can be decoded from the
-//! `mcause` register.
+//! `mcause`/`scause` register.
 //!
 //! This function can be redefined in the following way:
 //!
@@ -300,7 +303,7 @@
 //! ### `DefaultHandler`
 //!
 //! This function is called when interrupt without defined interrupt handler is occured.
-//! The interrupt reason can be decoded from the `mcause` register.
+//! The interrupt reason can be decoded from the `mcause`/`scause` register.
 //!
 //! This function can be redefined in the following way:
 //!
@@ -319,12 +322,49 @@
 //! ```
 //!
 //! Default implementation of this function stucks in a busy-loop.
+//!
+//! # Features
+//!
+//! ## `s-mode`
+//!
+//! The supervisor mode feature (`s-mode`) can be activated via [Cargo features](https://doc.rust-lang.org/cargo/reference/features.html).
+//!
+//! For example:
+//! ``` text
+//! [dependencies]
+//! riscv-rt = {features=["s-mode"]}
+//! ```
+//! Internally, riscv-rt uses different versions of precompiled static libraries
+//! for (i) machine mode and (ii) supervisor mode. If the `s-mode` feature was activated,
+//! the build script selects the s-mode library. While most registers/instructions have variants for
+//! both `mcause` and `scause`, the `mhartid` hardware thread register is not available in supervisor
+//! mode. Instead, the hartid is passed as parameter by a bootstrapping firmware (i.e., SBI).
+//!
+//! Use case: QEMU supports [OpenSBI](https://github.com/riscv-software-src/opensbi) as default firmware.
+//! Using the SBI requires riscv-rt to be run in supervisor mode instead of machine mode.
+//! ``` text
+//! APP_BINARY=$(find target -name app)
+//! sudo qemu-system-riscv64 -m 2G -nographic -machine virt -kernel $APP_BINARY
+//! ```
+//! It requires the memory layout to be non-overlapping, like
+//! ``` text
+//! MEMORY
+//! {
+//!   RAM : ORIGIN = 0x80200000, LENGTH = 0x8000000
+//!   FLASH : ORIGIN = 0x20000000, LENGTH = 16M
+//! }
+//! ```
 
 // NOTE: Adapted from cortex-m/src/lib.rs
 #![no_std]
 #![deny(missing_docs)]
 
-use riscv::register::mcause;
+#[cfg(feature = "s-mode")]
+use riscv::register::{scause as xcause, stvec as xtvec, stvec::TrapMode as xTrapMode};
+
+#[cfg(not(feature = "s-mode"))]
+use riscv::register::{mcause as xcause, mhartid, mtvec as xtvec, mtvec::TrapMode as xTrapMode};
+
 pub use riscv_rt_macros::{entry, pre_init};
 
 #[export_name = "error: riscv-rt appears more than once in the dependency graph"]
@@ -361,10 +401,16 @@ pub unsafe extern "C" fn start_rust(a0: usize, a1: usize, a2: usize) -> ! {
 
         fn _setup_interrupts();
 
-        fn _mp_hook() -> bool;
+        fn _mp_hook(hartid: usize) -> bool;
     }
 
-    if _mp_hook() {
+    // sbi passes hartid as first parameter (a0)
+    #[cfg(feature = "s-mode")]
+    let hartid = a0;
+    #[cfg(not(feature = "s-mode"))]
+    let hartid = mhartid::read();
+
+    if _mp_hook(hartid) {
         __pre_init();
 
         r0::zero_bss(&mut _sbss, &mut _ebss);
@@ -403,7 +449,7 @@ pub struct TrapFrame {
 
 /// Trap entry point rust (_start_trap_rust)
 ///
-/// `mcause` is read to determine the cause of the trap. XLEN-1 bit indicates
+/// `scause`/`mcause` is read to determine the cause of the trap. XLEN-1 bit indicates
 /// if it's an interrupt or an exception. The result is examined and ExceptionHandler
 /// or one of the core interrupt handlers is called.
 #[link_section = ".trap.rust"]
@@ -415,13 +461,13 @@ pub extern "C" fn start_trap_rust(trap_frame: *const TrapFrame) {
     }
 
     unsafe {
-        let cause = mcause::read();
+        let cause = xcause::read();
+
         if cause.is_exception() {
             ExceptionHandler(&*trap_frame)
         } else {
-            let code = cause.code();
-            if code < __INTERRUPTS.len() {
-                let h = &__INTERRUPTS[code];
+            if cause.code() < __INTERRUPTS.len() {
+                let h = &__INTERRUPTS[cause.code()];
                 if h.reserved == 0 {
                     DefaultHandler();
                 } else {
@@ -529,9 +575,8 @@ pub unsafe extern "Rust" fn default_pre_init() {}
 #[doc(hidden)]
 #[no_mangle]
 #[rustfmt::skip]
-pub extern "Rust" fn default_mp_hook() -> bool {
-    use riscv::register::mhartid;
-    match mhartid::read() {
+pub extern "Rust" fn default_mp_hook(hartid: usize) -> bool {
+    match hartid {
         0 => true,
         _ => loop {
             unsafe { riscv::asm::wfi() }
@@ -539,14 +584,14 @@ pub extern "Rust" fn default_mp_hook() -> bool {
     }
 }
 
-/// Default implementation of `_setup_interrupts` that sets `mtvec` to a trap handler address.
+/// Default implementation of `_setup_interrupts` that sets `mtvec`/`stvec` to a trap handler address.
 #[doc(hidden)]
 #[no_mangle]
 #[rustfmt::skip]
 pub unsafe extern "Rust" fn default_setup_interrupts() {
-    use riscv::register::mtvec::{self, TrapMode};
     extern "C" {
         fn _start_trap();
     }
-    mtvec::write(_start_trap as usize, TrapMode::Direct);
+
+    xtvec::write(_start_trap as usize, xTrapMode::Direct);
 }