Merge #150

150: add NVIC::{mask,unmask} r=therealprof a=japaric

these are the "static method" (methods that don't take `self`) versions of
NVIC::{enable,disable} in the same vein as the existing NVIC::{pend,unpend}

this commit also deprecates the existing NVIC::{enable,disable} methods and
notes that NVIC::enable is unsound because it should be an `unsafe` method (like
interrupt::enable and basepri::write, it can break critical sections) but it's
marked as safe. Its replacement, NVIC::unmask, has the correct unsafety setting:
it's an `unsafe` function.

Co-authored-by: Jorge Aparicio <jorge@japaric.io>

1 files changed, 26 insertions, 5 deletions

diff --git a/src/peripheral/nvic.rs b/src/peripheral/nvic.rs
index 57ce009..d123b7d 100644
--- a/src/peripheral/nvic.rs
+++ b/src/peripheral/nvic.rs
@@ -104,23 +104,44 @@ impl NVIC {
     }
 
     /// Disables `interrupt`
-    pub fn disable<I>(&mut self, interrupt: I)
+    pub fn mask<I>(interrupt: I)
     where
         I: Nr,
     {
         let nr = interrupt.nr();
-
-        unsafe { self.icer[usize::from(nr / 32)].write(1 << (nr % 32)) }
+        // NOTE(unsafe) this is a write to a stateless register
+        unsafe { (*Self::ptr()).icer[usize::from(nr / 32)].write(1 << (nr % 32)) }
     }
 
     /// Enables `interrupt`
-    pub fn enable<I>(&mut self, interrupt: I)
+    ///
+    /// This function is `unsafe` because it can break mask-based critical sections
+    pub unsafe fn unmask<I>(interrupt: I)
     where
         I: Nr,
     {
         let nr = interrupt.nr();
+        // NOTE(ptr) this is a write to a stateless register
+        (*Self::ptr()).iser[usize::from(nr / 32)].write(1 << (nr % 32))
+    }
+
+    /// Disables `interrupt`
+    #[deprecated(since = "0.6.1", note = "Use `NVIC::mask`")]
+    pub fn disable<I>(&mut self, interrupt: I)
+    where
+        I: Nr,
+    {
+        Self::mask(interrupt)
+    }
 
-        unsafe { self.iser[usize::from(nr / 32)].write(1 << (nr % 32)) }
+    /// **WARNING** This method is a soundness hole in the API; it should actually be an `unsafe`
+    /// function. Use `NVIC::unmask` which has the right unsafety.
+    #[deprecated(since = "0.6.1", note = "Use `NVIC::unmask`")]
+    pub fn enable<I>(&mut self, interrupt: I)
+    where
+        I: Nr,
+    {
+        unsafe { Self::unmask(interrupt) }
     }
 
     /// Returns the NVIC priority of `interrupt`