doc(port_riscv): enhance the documentation regarding non-M-mode

Author: yvt

src/r3_port_riscv/src/lib.md

@@ -197,4 +197,4 @@ The trap handler stores a first-level state directly below the current stack poi
 
 ## Processor Modes
 
-All code executes in Machine mode. The value of `mstatus.MPP` is always `M` (`0b11`).
+All code executes in Machine mode by default. The value of `mstatus.MPP` is always `M` (`0b11`). Other modes can be selected by [`ThreadingOptions::PRIVILEGE_LEVEL`], which changes all CSRs and CSR values accordingly.

src/r3_port_riscv/src/lib.rs

@@ -97,7 +97,7 @@ pub trait EntryPoint {
     ///
     ///  - The processor should be in the privilege mode specified by
     ///    [`ThreadingOptions::PRIVILEGE_LEVEL`] and have interrupts masked for
-    //     this privilege level.
+    ///    this privilege level.
     ///  - This method hasn't been entered yet.
     ///
     unsafe fn start() -> !;
@@ -110,7 +110,7 @@ pub trait EntryPoint {
     ///
     ///  - The processor should be in the privilege mode specified by
     ///    [`ThreadingOptions::PRIVILEGE_LEVEL`] and have interrupts masked for
-    //     this privilege level
+    ///    this privilege level
     ///  - The register state of the background context should be preserved so
     ///    that the handler can restore it later.
     ///

src/r3_port_riscv/src/threading/cfg.rs

@@ -18,6 +18,25 @@ pub trait ThreadingOptions {
     /// The RISC-V privilege level wherein the kernel and apllication operate.
     /// The default value is [`PRIVILEGE_LEVEL_MACHINE`]. Must be in the range
     /// `0..4`.
+    ///
+    /// There are a few points that should be kept in mind when specifying this
+    /// option:
+    ///
+    ///  - It's [`EntryPoint`][]'s caller that is responsible for ensuring the
+    ///    specified privilege level is entered. Calling the entry points from
+    ///    other privilege levels will cause an undefined behavior.
+    ///
+    ///  - The current version of `riscv-rt` can only start in M-mode.
+    ///    Consequently, [`use_rt!`][] is incompatible with other modes.
+    ///
+    ///  - The current version of [`riscv`][] provides wrapper functions which
+    ///    are hard-coded to use M-mode-only CSRs, such as `mstatus.MIE`.
+    ///    They don't work in lower privilege levels. You must use [CPU Lock][]
+    ///    or the correct CSR (e.g., [`riscv::register::sstatus`]) the
+    ///    specified privilege level directly.
+    ///
+    /// [`EntryPoint`]: crate::EntryPoint
+    /// [CPU Lock]: r3_core#system-states
     const PRIVILEGE_LEVEL: u8 = PRIVILEGE_LEVEL_MACHINE;
 }