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.
17pub struct Peri<'a, T: PeripheralType> {
18    inner: T,
19    _lifetime: PhantomData<&'a mut T>,
20}
21
22impl<'a, T: PeripheralType> Peri<'a, T> {
23    /// Create a new owned a peripheral.
24    ///
25    /// For use by HALs only.
26    ///
27    /// If you're an end user you shouldn't use this, you should use `steal()`
28    /// on the actual peripheral types instead.
29    #[inline]
30    #[doc(hidden)]
31    pub const unsafe fn new_unchecked(inner: T) -> Self {
32        Self {
33            inner,
34            _lifetime: PhantomData,
35        }
36    }
37
38    /// Unsafely clone (duplicate) a peripheral singleton.
39    ///
40    /// # Safety
41    ///
42    /// This returns an owned clone of the peripheral. You must manually ensure
43    /// only one copy of the peripheral is in use at a time. For example, don't
44    /// create two SPI drivers on `SPI1`, because they will "fight" each other.
45    ///
46    /// You should strongly prefer using `reborrow()` instead. It returns a
47    /// `Peri` that borrows `self`, which allows the borrow checker
48    /// to enforce this at compile time.
49    pub const unsafe fn clone_unchecked(&self) -> Peri<'a, T> {
50        Peri::new_unchecked(self.inner)
51    }
52
53    /// Reborrow into a "child" Peri.
54    ///
55    /// `self` will stay borrowed until the child Peripheral is dropped.
56    pub const fn reborrow(&mut self) -> Peri<'_, T> {
57        // safety: we're returning the clone inside a new Peripheral that borrows
58        // self, so user code can't use both at the same time.
59        unsafe { self.clone_unchecked() }
60    }
61
62    /// Map the inner peripheral using `Into`.
63    ///
64    /// This converts from `Peri<'a, T>` to `Peri<'a, U>`, using an
65    /// `Into` impl to convert from `T` to `U`.
66    ///
67    /// For example, this can be useful to.into() GPIO pins: converting from Peri<'a, PB11>` to `Peri<'a, AnyPin>`.
68    #[inline]
69    pub fn into<U>(self) -> Peri<'a, U>
70    where
71        T: Into<U>,
72        U: PeripheralType,
73    {
74        unsafe { Peri::new_unchecked(self.inner.into()) }
75    }
76}
77
78impl<'a, T: PeripheralType> Deref for Peri<'a, T> {
79    type Target = T;
80
81    #[inline]
82    fn deref(&self) -> &Self::Target {
83        &self.inner
84    }
85}
86
87impl<'a, T: PeripheralType + core::fmt::Debug> core::fmt::Debug for Peri<'a, T> {
88    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
89        self.inner.fmt(f)
90    }
91}
92
93impl<'a, T: PeripheralType + core::fmt::Display> core::fmt::Display for Peri<'a, T> {
94    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
95        self.inner.fmt(f)
96    }
97}
98
99#[cfg(feature = "defmt")]
100impl<'a, T: PeripheralType + defmt::Format> defmt::Format for Peri<'a, T> {
101    fn format(&self, fmt: defmt::Formatter) {
102        self.inner.format(fmt);
103    }
104}
105
106/// Marker trait for peripheral types.
107pub trait PeripheralType: Copy + Sized {}
embassy_hal_internal/peripheral.rs

embassy_hal_internal/
peripheral.rs
