use unchecked functions, improve safety docs

Author: robamu

cortex-m/src/peripheral/nvic.rs

@@ -122,10 +122,10 @@ impl NVIC {
         I: InterruptNumber,
     {
         let nr = interrupt.number();
-        // NOTE(unsafe) this is a write to a stateless register
+        // SAFETY: this is a write to a stateless register.
         let mut nvic = unsafe { Self::steal() };
-        nvic.write_icer(usize::from(nr / 32), 1 << (nr % 32))
-            .expect("invalid interrupt number");
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.write_icer_unchecked(usize::from(nr / 32), 1 << (nr % 32)) }
     }
 
     /// Enables `interrupt`
@@ -137,10 +137,10 @@ impl NVIC {
         I: InterruptNumber,
     {
         let nr = interrupt.number();
-        // NOTE(ptr) this is a write to a stateless register
+        // SAFETY: this is a write to a stateless register,
         let mut nvic = unsafe { Self::steal() };
-        nvic.write_iser(usize::from(nr / 32), 1 << (nr % 32))
-            .expect("invalid interrupt number");
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.write_iser_unchecked(usize::from(nr / 32), 1 << (nr % 32)) }
     }
 
     /// Returns the NVIC priority of `interrupt`
@@ -156,24 +156,21 @@ impl NVIC {
         #[cfg(not(armv6m))]
         {
             let nr = interrupt.number();
-            // note(unsafe) atomic read with no side effects
+            // SAFETY: atomic read with no side effects
             let nvic = unsafe { Self::steal() };
             let ipr_ptr = nvic.pointer_to_ipr_start() as *const u8;
-            // This should never happen for correct `InterruptNumber` implementations.
-            if nr >= 124 {
-                panic!("unexpected interrupt number");
-            }
-            // note(unsafe) atomic read with no side effects
+            // SAFETY:
+            //  - atomic read with no side effects
+            //  - InterruptNumber is an unsafe trait, we can assume correct implementation.
             unsafe { core::ptr::read_volatile(ipr_ptr.offset(nr as isize)) }
         }
 
         #[cfg(armv6m)]
         {
-            // note(unsafe) atomic read with no side effects
+            // SAFETY: atomic read with no side effects
             let nvic = unsafe { Self::steal() };
-            let ipr_n = nvic
-                .read_ipr(Self::ipr_index(interrupt))
-                .expect("unexpected interrupt number");
+            // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+            let ipr_n = unsafe { nvic.read_ipr_unchecked(Self::ipr_index(interrupt)) };
             ((ipr_n >> Self::ipr_shift(interrupt)) & 0x0000_00ff) as u8
         }
     }
@@ -188,12 +185,10 @@ impl NVIC {
         let nr = interrupt.number();
         let mask = 1 << (nr % 32);
 
-        // note(unsafe) atomic read with no side effects
+        // SAFETY: atomic read with no side effects
         let nvic = unsafe { Self::steal() };
-        nvic.read_iabr(usize::from(nr / 32))
-            .expect("unexpected interrupt number")
-            & mask
-            == mask
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.read_iabr_unchecked(usize::from(nr / 32)) & mask == mask }
     }
 
     /// Checks if `interrupt` is enabled
@@ -205,12 +200,10 @@ impl NVIC {
         let nr = interrupt.number();
         let mask = 1 << (nr % 32);
 
-        // note(unsafe) atomic read with no side effects
+        // SAFETY: atomic read with no side effects
         let nvic = unsafe { Self::steal() };
-        nvic.read_iser(usize::from(nr / 32))
-            .expect("unexpected interrupt number")
-            & mask
-            == mask
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.read_iser_unchecked(usize::from(nr / 32)) & mask == mask }
     }
 
     /// Checks if `interrupt` is pending
@@ -222,12 +215,10 @@ impl NVIC {
         let nr = interrupt.number();
         let mask = 1 << (nr % 32);
 
-        // note(unsafe) atomic read with no side effects
+        // SAFETY: atomic read with no side effects
         let nvic = unsafe { Self::steal() };
-        nvic.read_ispr(usize::from(nr / 32))
-            .expect("unexpected interrupt number")
-            & mask
-            == mask
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.read_ispr_unchecked(usize::from(nr / 32)) & mask == mask }
     }
 
     /// Forces `interrupt` into pending state
@@ -238,10 +229,10 @@ impl NVIC {
     {
         let nr = interrupt.number();
 
-        // NOTE(unsafe) atomic stateless write; ICPR doesn't store any state
+        // SAFETY: atomic stateless write; ICPR doesn't store any state
         let mut nvic = unsafe { Self::steal() };
-        nvic.write_ispr(usize::from(nr / 32), 1 << (nr % 32))
-            .expect("unexpected interrupt number")
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.write_ispr_unchecked(usize::from(nr / 32), 1 << (nr % 32)) }
     }
 
     /// Sets the "priority" of `interrupt` to `prio`
@@ -264,28 +255,26 @@ impl NVIC {
         #[cfg(not(armv6m))]
         {
             let nr = interrupt.number();
-            // NOTE(unsafe) atomic stateless write; IPR doesn't store any state
+            // SAFETY: atomic stateless write; IPR doesn't store any state
             let nvic = unsafe { Self::steal() };
             let ipr_ptr = nvic.pointer_to_ipr_start() as *mut u8;
-            // This should never happen for correct `InterruptNumber` implementations.
-            if nr >= 124 {
-                panic!("unexpected interrupt number");
-            }
-            // NOTE(unsafe) atomic stateless write; IPR doesn't store any state
+            // SAFETY:
+            // - atomic stateless write; IPR doesn't store any state
+            // - InterruptNumber is an unsafe trait, we can assume correct implementation.
             unsafe { core::ptr::write_volatile(ipr_ptr.offset(nr as isize), prio) }
         }
 
         #[cfg(armv6m)]
         {
-            // NOTE(unsafe) atomic stateless write; IPR doesn't store any state
+            // SAFETY: atomic stateless write; IPR doesn't store any state
             let mut nvic = unsafe { Self::steal() };
-            nvic.modify_ipr(Self::ipr_index(interrupt), |mut value| {
+            // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+            nvic.modify_ipr_unchecked(Self::ipr_index(interrupt), |mut value| {
                 let mask = 0x0000_00ff << Self::ipr_shift(interrupt);
                 let prio = u32::from(prio) << Self::ipr_shift(interrupt);
 
                 (value & !mask) | prio
-            })
-            .expect("unexpected interrupt number");
+            });
         }
     }
 
@@ -297,10 +286,10 @@ impl NVIC {
     {
         let nr = interrupt.number();
 
-        // NOTE(unsafe) atomic stateless write; ICPR doesn't store any state
+        // SAFETY: atomic stateless write; ICPR doesn't store any state
         let mut nvic = unsafe { Self::steal() };
-        nvic.write_icpr(usize::from(nr / 32), 1 << (nr % 32))
-            .expect("unexpected interrupt number")
+        // SAFETY: InterruptNumber is an unsafe trait, we can assume correct implementation.
+        unsafe { nvic.write_icpr_unchecked(usize::from(nr / 32), 1 << (nr % 32)) }
     }
 
     #[cfg(armv6m)]