embassy_hal_internal/
peripheral.rs

1use core::marker::PhantomData;
2use core::ops::Deref;
3
4/// An exclusive reference to a peripheral.
5///
6/// This is functionally the same as a `&'a mut T`. There's a few advantages in having
7/// a dedicated struct instead:
8///
9/// - Memory efficiency: Peripheral singletons are typically either zero-sized (for concrete
10///   peripherals like `PA9` or `SPI4`) or very small (for example `AnyPin`, which is 1 byte).
11///   However `&mut T` is always 4 bytes for 32-bit targets, even if T is zero-sized.
12///   Peripheral stores a copy of `T` instead, so it's the same size.
13/// - Code size efficiency. If the user uses the same driver with both `SPI4` and `&mut SPI4`,
14///   the driver code would be monomorphized two times. With Peri, the driver is generic
15///   over a lifetime only. `SPI4` becomes `Peri<'static, SPI4>`, and `&mut SPI4` becomes
16///   `Peri<'a, SPI4>`. Lifetimes don't cause monomorphization.
17#[derive(Debug)]
18#[cfg_attr(feature = "defmt", derive(defmt::Format))]
19pub struct Peri<'a, T: PeripheralType> {
20    inner: T,
21    _lifetime: PhantomData<&'a mut T>,
22}
23
24impl<'a, T: PeripheralType> Peri<'a, T> {
25    /// Create a new owned a peripheral.
26    ///
27    /// For use by HALs only.
28    ///
29    /// If you're an end user you shouldn't use this, you should use `steal()`
30    /// on the actual peripheral types instead.
31    #[inline]
32    #[doc(hidden)]
33    pub unsafe fn new_unchecked(inner: T) -> Self {
34        Self {
35            inner,
36            _lifetime: PhantomData,
37        }
38    }
39
40    /// Unsafely clone (duplicate) a peripheral singleton.
41    ///
42    /// # Safety
43    ///
44    /// This returns an owned clone of the peripheral. You must manually ensure
45    /// only one copy of the peripheral is in use at a time. For example, don't
46    /// create two SPI drivers on `SPI1`, because they will "fight" each other.
47    ///
48    /// You should strongly prefer using `reborrow()` instead. It returns a
49    /// `Peri` that borrows `self`, which allows the borrow checker
50    /// to enforce this at compile time.
51    pub unsafe fn clone_unchecked(&self) -> Peri<'a, T> {
52        Peri::new_unchecked(self.inner)
53    }
54
55    /// Reborrow into a "child" Peri.
56    ///
57    /// `self` will stay borrowed until the child Peripheral is dropped.
58    pub fn reborrow(&mut self) -> Peri<'_, T> {
59        // safety: we're returning the clone inside a new Peripheral that borrows
60        // self, so user code can't use both at the same time.
61        unsafe { self.clone_unchecked() }
62    }
63
64    /// Map the inner peripheral using `Into`.
65    ///
66    /// This converts from `Peri<'a, T>` to `Peri<'a, U>`, using an
67    /// `Into` impl to convert from `T` to `U`.
68    ///
69    /// For example, this can be useful to.into() GPIO pins: converting from Peri<'a, PB11>` to `Peri<'a, AnyPin>`.
70    #[inline]
71    pub fn into<U>(self) -> Peri<'a, U>
72    where
73        T: Into<U>,
74        U: PeripheralType,
75    {
76        unsafe { Peri::new_unchecked(self.inner.into()) }
77    }
78}
79
80impl<'a, T: PeripheralType> Deref for Peri<'a, T> {
81    type Target = T;
82
83    #[inline]
84    fn deref(&self) -> &Self::Target {
85        &self.inner
86    }
87}
88
89/// Marker trait for peripheral types.
90pub trait PeripheralType: Copy + Sized {}
embassy_hal_internal/peripheral.rs

embassy_hal_internal/
peripheral.rs
