Added features to select privilege level (#5)

Currently, the library attempts to execute some semihosting operations
in a completely interrupt-free context. It does this by using
`riscv::interrupt::free`, which saves and restores the `mie` field of
`mstatus`. As a result, attempts to initiate semihosting calls outside
of M mode cause illegal instruction exceptions.

This commit provides a solution, by requiring users to choose one of two
features, "machine-mode" or "user-mode", which will compile different
versions of the functions in src/export.rs that do and do not suspend
interrupts, respectively. Failure to do so will throw a compiler error,
unless the "no-semihosting" feature was enabled.

A "supervisor-mode" feature was left out as the `riscv` crate does not
yet have an equivalent of `interrupt::free` for supervisor mode.

CI now also checks builds with both of these features.

Author: FawazTirmizi

.github/workflows/check.yml

@@ -9,6 +9,7 @@ jobs:
         # All generated code should be running on stable now, MRSV is 1.59.0
         toolchain: [nightly, stable, 1.59.0]
         target: [riscv32i-unknown-none-elf, riscv32imc-unknown-none-elf, riscv32imac-unknown-none-elf, riscv64imac-unknown-none-elf, riscv64gc-unknown-none-elf]
+        privilege: [machine, user]
 
         include:
           # Nightly is only for reference and allowed to fail
@@ -27,4 +28,4 @@ jobs:
         with:
           use-cross: true
           command: check
-          args: --verbose --target ${{ matrix.target }}
+          args: --verbose --target ${{ matrix.target }} --features=${{matrix.privilege}}-mode

.github/workflows/doc.yml

@@ -5,6 +5,9 @@ on: [push, pull_request]
 jobs:
   doc:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        privilege: [machine, user]
     steps:
       - uses: actions/checkout@v2
       - uses: actions-rs/toolchain@v1
@@ -15,3 +18,4 @@ jobs:
       - uses: actions-rs/cargo@v1
         with:
           command: doc
+          args: --features=${{matrix.privilege}}-mode

CHANGELOG.md

@@ -21,6 +21,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Clean up documentation, removing unnecessary references to
   cortex-m-semihosting and improving clarity.
 - Added GitHub Actions CI
+- Add features to select the privilege level the semihosting operations will be
+  started from
 
 ## [v0.0.1] - 2018-02-27
 

Cargo.toml

@@ -18,8 +18,11 @@ rust-version = "1.59.0"
 
 [features]
 default = ["jlink-quirks"]
+machine-mode = []
+user-mode = []
 jlink-quirks = []
 no-semihosting = []
 
 [dependencies]
 riscv = "0.8.0"
+cfg-if = "1.0.0"

README.md

@@ -7,12 +7,20 @@ This is a fork of the
 to support the RISC-V Semihosting Specification as documented
 [here](https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc)
 
-This crate can be used in exactly the same way as cortex-m-semihosting, simply
-by changing calls to `cortex_m_semihosting::*` to `riscv_semihosting::*`. Given
-this, the
+This crate can (almost) be used in exactly the same way as cortex-m-semihosting,
+simply by changing calls to `cortex_m_semihosting::*` to `riscv_semihosting::*`.
+Given this, the
 [cortex-m-semihosting documentation](https://docs.rs/cortex-m-semihosting) is
 generally sufficient for using this library.
 
+A major difference between this library and cortex-m-semihosting is that there
+are mandatory features to choose the privilege level at which the semihosting
+calls are executed. The "machine-mode" feature will cause the macros in `export`
+to execute the semihosting operation in an interrupt-free context, while
+"user-mode" causes them to just execute the operation. Failure to select one of
+these two features will cause a compiler error.
+
+
 # Minimum Supported Rust Version (MSRV)
 
 This crate is guaranteed to compile on stable Rust 1.59.0 and up. It **won't**

src/export.rs

@@ -2,50 +2,104 @@
 
 use core::fmt::{self, Write};
 
+#[cfg(feature = "machine-mode")]
 use riscv::interrupt;
 
 use crate::hio::{self, HostStream};
 
 static mut HSTDOUT: Option<HostStream> = None;
 
-pub fn hstdout_str(s: &str) {
-    let _result = interrupt::free(|_| unsafe {
-        if HSTDOUT.is_none() {
-            HSTDOUT = Some(hio::hstdout()?);
+#[cfg(not(feature = "no-semihosting"))]
+cfg_if::cfg_if! {
+    if #[cfg(feature="machine-mode")] {
+        pub fn hstdout_str(s: &str) {
+            let _result = interrupt::free(|_| unsafe {
+                if HSTDOUT.is_none() {
+                    HSTDOUT = Some(hio::hstdout()?);
+                }
+
+                HSTDOUT.as_mut().unwrap().write_str(s).map_err(drop)
+            });
         }
 
-        HSTDOUT.as_mut().unwrap().write_str(s).map_err(drop)
-    });
-}
+        pub fn hstdout_fmt(args: fmt::Arguments) {
+            let _result = interrupt::free(|_| unsafe {
+                if HSTDOUT.is_none() {
+                    HSTDOUT = Some(hio::hstdout()?);
+                }
 
-pub fn hstdout_fmt(args: fmt::Arguments) {
-    let _result = interrupt::free(|_| unsafe {
-        if HSTDOUT.is_none() {
-            HSTDOUT = Some(hio::hstdout()?);
+                HSTDOUT.as_mut().unwrap().write_fmt(args).map_err(drop)
+            });
         }
 
-        HSTDOUT.as_mut().unwrap().write_fmt(args).map_err(drop)
-    });
-}
+        static mut HSTDERR: Option<HostStream> = None;
 
-static mut HSTDERR: Option<HostStream> = None;
+        pub fn hstderr_str(s: &str) {
+            let _result = interrupt::free(|_| unsafe {
+                if HSTDERR.is_none() {
+                    HSTDERR = Some(hio::hstderr()?);
+                }
 
-pub fn hstderr_str(s: &str) {
-    let _result = interrupt::free(|_| unsafe {
-        if HSTDERR.is_none() {
-            HSTDERR = Some(hio::hstderr()?);
+                HSTDERR.as_mut().unwrap().write_str(s).map_err(drop)
+            });
         }
 
-        HSTDERR.as_mut().unwrap().write_str(s).map_err(drop)
-    });
-}
+        pub fn hstderr_fmt(args: fmt::Arguments) {
+            let _result = interrupt::free(|_| unsafe {
+                if HSTDERR.is_none() {
+                    HSTDERR = Some(hio::hstderr()?);
+                }
 
-pub fn hstderr_fmt(args: fmt::Arguments) {
-    let _result = interrupt::free(|_| unsafe {
-        if HSTDERR.is_none() {
-            HSTDERR = Some(hio::hstderr()?);
+                HSTDERR.as_mut().unwrap().write_fmt(args).map_err(drop)
+            });
         }
+    }
+    else if #[cfg(feature = "user-mode")] {
+        pub fn hstdout_str(s: &str) {
+            let _result = unsafe {
+                if HSTDOUT.is_none() {
+                    HSTDOUT = Some(hio::hstdout().unwrap());
+                }
 
-        HSTDERR.as_mut().unwrap().write_fmt(args).map_err(drop)
-    });
+                HSTDOUT.as_mut().unwrap().write_str(s).map_err(drop)
+            };
+        }
+
+        pub fn hstdout_fmt(args: fmt::Arguments) {
+            let _result = unsafe {
+                if HSTDOUT.is_none() {
+                    HSTDOUT = Some(hio::hstdout().unwrap());
+                }
+
+                HSTDOUT.as_mut().unwrap().write_fmt(args).map_err(drop)
+            };
+        }
+
+        static mut HSTDERR: Option<HostStream> = None;
+
+        pub fn hstderr_str(s: &str) {
+            let _result = unsafe {
+                if HSTDERR.is_none() {
+                    HSTDERR = Some(hio::hstderr().unwrap());
+                }
+
+                HSTDERR.as_mut().unwrap().write_str(s).map_err(drop)
+            };
+        }
+
+        pub fn hstderr_fmt(args: fmt::Arguments) {
+            let _result = unsafe {
+                if HSTDERR.is_none() {
+                    HSTDERR = Some(hio::hstderr().unwrap());
+                }
+
+                HSTDERR.as_mut().unwrap().write_fmt(args).map_err(drop)
+            };
+        }
+    }
+    else {
+        compile_error!("A privilege level has not been selected. Enable either \
+                        the machine-mode or user-mode features as appropriate \
+                        for your use case.");
+    }
 }