Merge #842

842: WIP: Make unborrow safe to use r=Dirbaio a=GrantM11235

The basic idea is that `Unborrow::unborrow` is now safe to call and returns an `Unborrowed<'a, T>` which impls `Deref` and `DerefMut`

```rust
/// This is essentially a `&mut T`, but it is the size of `T` not the size
/// of a pointer. This is useful if T is a zero sized type.
pub struct Unborrowed<'a, T> {
    inner: T,
    _lifetime: PhantomData<&'a mut T>,
}
```

## Todo

- [x] Update other crates
  - [x] embassy-cortex-m
  - [x] embassy-hal-common
  - [x] embassy-lora
  - [x] embassy-nrf
  - [x] embassy-rp
  - [x] embassy-stm32
- [x] Remove usage of the unsafe `into_inner` method if possible
- [x] Review and amend docs for `Unborrow` and `Unborrowed`

Co-authored-by: Grant Miller <[email protected]>
Co-authored-by: Dario Nieuwenhuis <[email protected]>

2 files changed, 13 insertions, 12 deletions

diff --git a/embassy-cortex-m/src/interrupt.rs b/embassy-cortex-m/src/interrupt.rs
index 715f00381..7358caa46 100644
--- a/embassy-cortex-m/src/interrupt.rs
+++ b/embassy-cortex-m/src/interrupt.rs
@@ -3,7 +3,7 @@ use core::{mem, ptr};
 
 use atomic_polyfill::{compiler_fence, AtomicPtr, Ordering};
 use cortex_m::peripheral::NVIC;
-use embassy_hal_common::Unborrow;
+use embassy_hal_common::Peripheral;
 pub use embassy_macros::cortex_m_interrupt_take as take;
 
 /// Implementation detail, do not use outside embassy crates.
@@ -32,7 +32,7 @@ unsafe impl cortex_m::interrupt::InterruptNumber for NrWrap {
 
 /// Represents an interrupt type that can be configured by embassy to handle
 /// interrupts.
-pub unsafe trait Interrupt: Unborrow<Target = Self> {
+pub unsafe trait Interrupt: Peripheral<P = Self> {
     /// Return the NVIC interrupt number for this interrupt.
     fn number(&self) -> u16;
     /// Steal an instance of this interrupt
diff --git a/embassy-cortex-m/src/peripheral.rs b/embassy-cortex-m/src/peripheral.rs
index 6a03bfb9f..e2f295579 100644
--- a/embassy-cortex-m/src/peripheral.rs
+++ b/embassy-cortex-m/src/peripheral.rs
@@ -1,9 +1,9 @@
 //! Peripheral interrupt handling specific to cortex-m devices.
-use core::marker::PhantomData;
 use core::mem::MaybeUninit;
 
 use cortex_m::peripheral::scb::VectActive;
 use cortex_m::peripheral::{NVIC, SCB};
+use embassy_hal_common::{into_ref, Peripheral, PeripheralRef};
 
 use crate::interrupt::{Interrupt, InterruptExt, Priority};
 
@@ -33,8 +33,7 @@ impl<S> StateStorage<S> {
 /// a safe way.
 pub struct PeripheralMutex<'a, S: PeripheralState> {
     state: *mut S,
-    _phantom: PhantomData<&'a mut S>,
-    irq: S::Interrupt,
+    irq: PeripheralRef<'a, S::Interrupt>,
 }
 
 /// Whether `irq` can be preempted by the current interrupt.
@@ -62,8 +61,14 @@ impl<'a, S: PeripheralState> PeripheralMutex<'a, S> {
     /// Create a new `PeripheralMutex` wrapping `irq`, with `init` initializing the initial state.
     ///
     /// Registers `on_interrupt` as the `irq`'s handler, and enables it.
-    pub fn new(irq: S::Interrupt, storage: &'a mut StateStorage<S>, init: impl FnOnce() -> S) -> Self {
-        if can_be_preempted(&irq) {
+    pub fn new(
+        irq: impl Peripheral<P = S::Interrupt> + 'a,
+        storage: &'a mut StateStorage<S>,
+        init: impl FnOnce() -> S,
+    ) -> Self {
+        into_ref!(irq);
+
+        if can_be_preempted(&*irq) {
             panic!(
                 "`PeripheralMutex` cannot be created in an interrupt with higher priority than the interrupt it wraps"
             );
@@ -88,11 +93,7 @@ impl<'a, S: PeripheralState> PeripheralMutex<'a, S> {
         irq.set_handler_context(state_ptr as *mut ());
         irq.enable();
 
-        Self {
-            irq,
-            state: state_ptr,
-            _phantom: PhantomData,
-        }
+        Self { irq, state: state_ptr }
     }
 
     /// Access the peripheral state ensuring interrupts are disabled so that the state can be