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]>

4 files changed, 32 insertions, 23 deletions

diff --git a/examples/stm32f4/src/bin/sdmmc.rs b/examples/stm32f4/src/bin/sdmmc.rs
index 665670261..752ad57bf 100644
--- a/examples/stm32f4/src/bin/sdmmc.rs
+++ b/examples/stm32f4/src/bin/sdmmc.rs
@@ -21,12 +21,17 @@ async fn main(_spawner: Spawner, p: Peripherals) -> ! {
 
     let irq = interrupt::take!(SDIO);
 
-    let mut sdmmc = Sdmmc::new(
+    let mut sdmmc = Sdmmc::new_4bit(
         p.SDIO,
-        (p.PC12, p.PD2, p.PC8, p.PC9, p.PC10, p.PC11),
         irq,
-        Default::default(),
         p.DMA2_CH3,
+        p.PC12,
+        p.PD2,
+        p.PC8,
+        p.PC9,
+        p.PC10,
+        p.PC11,
+        Default::default(),
     );
 
     // Should print 400kHz for initialization
diff --git a/examples/stm32f7/src/bin/sdmmc.rs b/examples/stm32f7/src/bin/sdmmc.rs
index 011e1fd95..be1c2b152 100644
--- a/examples/stm32f7/src/bin/sdmmc.rs
+++ b/examples/stm32f7/src/bin/sdmmc.rs
@@ -21,12 +21,17 @@ async fn main(_spawner: Spawner, p: Peripherals) -> ! {
 
     let irq = interrupt::take!(SDMMC1);
 
-    let mut sdmmc = Sdmmc::new(
+    let mut sdmmc = Sdmmc::new_4bit(
         p.SDMMC1,
-        (p.PC12, p.PD2, p.PC8, p.PC9, p.PC10, p.PC11),
         irq,
-        Default::default(),
         p.DMA2_CH3,
+        p.PC12,
+        p.PD2,
+        p.PC8,
+        p.PC9,
+        p.PC10,
+        p.PC11,
+        Default::default(),
     );
 
     // Should print 400kHz for initialization
diff --git a/examples/stm32h7/src/bin/low_level_timer_api.rs b/examples/stm32h7/src/bin/low_level_timer_api.rs
index fc19d84e4..d7c6da5bd 100644
--- a/examples/stm32h7/src/bin/low_level_timer_api.rs
+++ b/examples/stm32h7/src/bin/low_level_timer_api.rs
@@ -2,8 +2,6 @@
 #![no_main]
 #![feature(type_alias_impl_trait)]
 
-use core::marker::PhantomData;
-
 use defmt::*;
 use embassy::executor::Spawner;
 use embassy::time::{Duration, Timer};
@@ -11,7 +9,7 @@ use embassy_stm32::gpio::low_level::AFType;
 use embassy_stm32::gpio::Speed;
 use embassy_stm32::pwm::*;
 use embassy_stm32::time::{khz, mhz, Hertz};
-use embassy_stm32::{unborrow, Config, Peripherals, Unborrow};
+use embassy_stm32::{into_ref, Config, Peripheral, PeripheralRef, Peripherals};
 use {defmt_rtt as _, panic_probe as _};
 
 pub fn config() -> Config {
@@ -49,20 +47,19 @@ async fn main(_spawner: Spawner, p: Peripherals) {
     }
 }
 pub struct SimplePwm32<'d, T: CaptureCompare32bitInstance> {
-    phantom: PhantomData<&'d mut T>,
-    inner: T,
+    inner: PeripheralRef<'d, T>,
 }
 
 impl<'d, T: CaptureCompare32bitInstance> SimplePwm32<'d, T> {
     pub fn new(
-        tim: impl Unborrow<Target = T> + 'd,
-        ch1: impl Unborrow<Target = impl Channel1Pin<T>> + 'd,
-        ch2: impl Unborrow<Target = impl Channel2Pin<T>> + 'd,
-        ch3: impl Unborrow<Target = impl Channel3Pin<T>> + 'd,
-        ch4: impl Unborrow<Target = impl Channel4Pin<T>> + 'd,
+        tim: impl Peripheral<P = T> + 'd,
+        ch1: impl Peripheral<P = impl Channel1Pin<T>> + 'd,
+        ch2: impl Peripheral<P = impl Channel2Pin<T>> + 'd,
+        ch3: impl Peripheral<P = impl Channel3Pin<T>> + 'd,
+        ch4: impl Peripheral<P = impl Channel4Pin<T>> + 'd,
         freq: Hertz,
     ) -> Self {
-        unborrow!(tim, ch1, ch2, ch3, ch4);
+        into_ref!(tim, ch1, ch2, ch3, ch4);
 
         T::enable();
         <T as embassy_stm32::rcc::low_level::RccPeripheral>::reset();
@@ -78,10 +75,7 @@ impl<'d, T: CaptureCompare32bitInstance> SimplePwm32<'d, T> {
             ch4.set_as_af(ch1.af_num(), AFType::OutputPushPull);
         }
 
-        let mut this = Self {
-            inner: tim,
-            phantom: PhantomData,
-        };
+        let mut this = Self { inner: tim };
 
         this.set_freq(freq);
         this.inner.start();
diff --git a/examples/stm32h7/src/bin/sdmmc.rs b/examples/stm32h7/src/bin/sdmmc.rs
index 787f700ae..163807d86 100644
--- a/examples/stm32h7/src/bin/sdmmc.rs
+++ b/examples/stm32h7/src/bin/sdmmc.rs
@@ -21,10 +21,15 @@ async fn main(_spawner: Spawner, p: Peripherals) -> ! {
 
     let irq = interrupt::take!(SDMMC1);
 
-    let mut sdmmc = Sdmmc::new(
+    let mut sdmmc = Sdmmc::new_4bit(
         p.SDMMC1,
-        (p.PC12, p.PD2, p.PC8, p.PC9, p.PC10, p.PC11),
         irq,
+        p.PC12,
+        p.PD2,
+        p.PC8,
+        p.PC9,
+        p.PC10,
+        p.PC11,
         Default::default(),
     );