Update the functions for using the PSP

Now offers both Priv and Unpriv modes, and has a handle to represent
ownership of a static Stack object.

The load/store check on `Stack::taken` is not perfectly thread safe,
but it's probably good enough and doing better requires a
critical-section or CAS atomics.

Author: thejpster

cortex-m/src/asm.rs

@@ -176,9 +176,9 @@ pub unsafe fn semihosting_syscall(nr: u32, arg: u32) -> u32 {
     call_asm!(__sh_syscall(nr: u32, arg: u32) -> u32)
 }
 
-/// Switch to unprivileged mode.
+/// Switch to unprivileged mode using the Process Stack
 ///
-/// Sets CONTROL.SPSEL (setting the program stack to be the active
+/// Sets CONTROL.SPSEL (setting the Process Stack to be the active
 /// stack) and CONTROL.nPRIV (setting unprivileged mode), updates the
 /// program stack pointer to the address in `psp`, then jumps to the
 /// address in `entry`.
@@ -194,7 +194,7 @@ pub unsafe fn semihosting_syscall(nr: u32, arg: u32) -> u32 {
 ///   it, you may wish to set the `PSPLIM` register to guard against this.
 #[cfg(cortex_m)]
 #[inline(always)]
-pub unsafe fn enter_unprivileged(psp: *const u32, entry: extern "C" fn() -> !) -> ! {
+pub unsafe fn enter_unprivileged_psp(psp: *const u32, entry: extern "C" fn() -> !) -> ! {
     unsafe {
         core::arch::asm!(
             "mrs {tmp}, CONTROL",
@@ -211,6 +211,36 @@ pub unsafe fn enter_unprivileged(psp: *const u32, entry: extern "C" fn() -> !) -
     }
 }
 
+/// Switch to using the Process Stack, but remain in Privileged Mode
+///
+/// Sets CONTROL.SPSEL (setting the Process Stack to be the active stack) but
+/// leaves CONTROL.nPRIV alone, updates the program stack pointer to the
+/// address in `psp`, then jumps to the address in `entry`.
+///
+/// # Safety
+///
+/// * `psp` and `entry` must point to valid stack memory and executable code,
+///   respectively.
+/// * `psp` must be 8 bytes aligned and point to stack top as stack grows
+///   towards lower addresses.
+/// * The size of the stack provided here must be large enough for your
+///   program - stack overflows are obviously UB. If your processor supports
+///   it, you may wish to set the `PSPLIM` register to guard against this.
+#[cfg(cortex_m)]
+#[inline(always)]
+pub unsafe fn enter_privileged_psp(psp: *const u32, entry: extern "C" fn() -> !) -> ! {
+    unsafe {
+        core::arch::asm!(
+            "msr PSP, {psp}",
+            "isb",
+            "bx {ent}",
+            psp = in(reg) psp,
+            ent = in(reg) entry,
+            options(noreturn, nostack)
+        );
+    }
+}
+
 /// Bootstrap.
 ///
 /// Clears CONTROL.SPSEL (setting the main stack to be the active stack),

cortex-m/src/psp.rs

@@ -4,14 +4,34 @@
 // lint here.
 #![allow(clippy::missing_inline_in_public_items)]
 
-use core::cell::UnsafeCell;
+use core::{
+    cell::UnsafeCell,
+    sync::atomic::{AtomicBool, Ordering},
+};
+
+/// Represents access to a [`Stack`]
+pub struct StackHandle(*mut u32, usize);
+
+impl StackHandle {
+    /// Get the pointer to the top of the stack
+    pub const fn top(&mut self) -> *mut u32 {
+        // SAFETY: The stack was this big when we constructed the handle
+        unsafe { self.0.add(self.1) }
+    }
+
+    /// Get the pointer to the top of the stack
+    pub const fn bottom(&mut self) -> *mut u32 {
+        self.0
+    }
+}
 
 /// A stack you can use as your Process Stack (PSP)
 ///
 /// The const-param N is the size **in 32-bit words**
 #[repr(align(8), C)]
 pub struct Stack<const N: usize> {
     space: UnsafeCell<[u32; N]>,
+    taken: AtomicBool,
 }
 
 impl<const N: usize> Stack<N> {
@@ -22,17 +42,27 @@ impl<const N: usize> Stack<N> {
     /// ```rust
     /// # use cortex_m::psp::Stack;
     /// static PSP_STACK: Stack::<4096> = Stack::new();
+    /// fn example() {
+    ///    let handle = PSP_STACK.take_handle();
+    ///    // ...
+    /// }
     /// ```
     pub const fn new() -> Stack<N> {
         Stack {
             space: UnsafeCell::new([0; N]),
+            taken: AtomicBool::new(false),
         }
     }
 
     /// Return the top of the stack
-    pub fn get_top(&self) -> *mut u32 {
+    pub fn take_handle(&self) -> StackHandle {
+        if self.taken.load(Ordering::Acquire) {
+            panic!("Cannot get two handles to one stack!");
+        }
+        self.taken.store(true, Ordering::Release);
+
         let start = self.space.get() as *mut u32;
-        unsafe { start.add(N) }
+        StackHandle(start, N)
     }
 }
 
@@ -44,9 +74,18 @@ impl<const N: usize> core::default::Default for Stack<N> {
     }
 }
 
-/// Switch to running on the PSP
+/// Switch to unprivileged mode running on the Process Stack Pointer (PSP)
+///
+/// In Unprivileged Mode, code can no longer perform privileged operations,
+/// such as disabling interrupts.
+///
+#[cfg(cortex_m)]
+pub fn switch_to_unprivileged_psp(mut psp_stack: StackHandle, function: extern "C" fn() -> !) -> ! {
+    unsafe { crate::asm::enter_unprivileged_psp(psp_stack.top(), function) }
+}
+
+/// Switch to running on the Process Stack Pointer (PSP), but remain in privileged mode
 #[cfg(cortex_m)]
-pub fn switch_to_psp<const N: usize>(psp_stack: &Stack<N>, function: extern "C" fn() -> !) -> ! {
-    let stack_top = psp_stack.get_top();
-    unsafe { crate::asm::enter_unprivileged(stack_top, function) }
+pub fn switch_to_privileged_psp(mut psp_stack: StackHandle, function: extern "C" fn() -> !) -> ! {
+    unsafe { crate::asm::enter_privileged_psp(psp_stack.top(), function) }
 }

testsuite/src/main.rs

@@ -14,6 +14,10 @@ fn panic(info: &core::panic::PanicInfo) -> ! {
 
 static EXCEPTION_FLAG: AtomicBool = AtomicBool::new(false);
 
+const STACK_SIZE_WORDS: usize = 1024;
+
+static STACK: cortex_m::psp::Stack<STACK_SIZE_WORDS> = cortex_m::psp::Stack::new();
+
 #[cortex_m_rt::exception]
 fn PendSV() {
     EXCEPTION_FLAG.store(true, Ordering::SeqCst);
@@ -86,4 +90,13 @@ mod tests {
         });
         assert!(EXCEPTION_FLAG.load(Ordering::SeqCst));
     }
+
+    #[test]
+    fn check_stack_handles() {
+        let mut handle = super::STACK.take_handle();
+        let top = handle.top();
+        let bottom = handle.bottom();
+        let delta = unsafe { top.byte_offset_from(bottom) };
+        assert_eq!(delta as usize, super::STACK_SIZE_WORDS * 4);
+    }
 }