1use core::marker::PhantomData;
2use core::ops::{Deref, DerefMut};
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/// PeripheralRef 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 PeripheralRef, the driver is generic
15/// over a lifetime only. `SPI4` becomes `PeripheralRef<'static, SPI4>`, and `&mut SPI4` becomes
16/// `PeripheralRef<'a, SPI4>`. Lifetimes don't cause monomorphization.
17pub struct PeripheralRef<'a, T> {
18 inner: T,
19 _lifetime: PhantomData<&'a mut T>,
20}
21
22impl<'a, T> PeripheralRef<'a, T> {
23 /// Create a new reference to a peripheral.
24 #[inline]
25 pub fn new(inner: T) -> Self {
26 Self {
27 inner,
28 _lifetime: PhantomData,
29 }
30 }
31
32 /// Unsafely clone (duplicate) a peripheral singleton.
33 ///
34 /// # Safety
35 ///
36 /// This returns an owned clone of the peripheral. You must manually ensure
37 /// only one copy of the peripheral is in use at a time. For example, don't
38 /// create two SPI drivers on `SPI1`, because they will "fight" each other.
39 ///
40 /// You should strongly prefer using `reborrow()` instead. It returns a
41 /// `PeripheralRef` that borrows `self`, which allows the borrow checker
42 /// to enforce this at compile time.
43 pub unsafe fn clone_unchecked(&self) -> PeripheralRef<'a, T>
44 where
45 T: Peripheral<P = T>,
46 {
47 PeripheralRef::new(self.inner.clone_unchecked())
48 }
49
50 /// Reborrow into a "child" PeripheralRef.
51 ///
52 /// `self` will stay borrowed until the child PeripheralRef is dropped.
53 pub fn reborrow(&mut self) -> PeripheralRef<'_, T>
54 where
55 T: Peripheral<P = T>,
56 {
57 // safety: we're returning the clone inside a new PeripheralRef that borrows
58 // self, so user code can't use both at the same time.
59 PeripheralRef::new(unsafe { self.inner.clone_unchecked() })
60 }
61
62 /// Map the inner peripheral using `Into`.
63 ///
64 /// This converts from `PeripheralRef<'a, T>` to `PeripheralRef<'a, U>`, using an
65 /// `Into` impl to convert from `T` to `U`.
66 ///
67 /// For example, this can be useful to degrade GPIO pins: converting from PeripheralRef<'a, PB11>` to `PeripheralRef<'a, AnyPin>`.
68 #[inline]
69 pub fn map_into<U>(self) -> PeripheralRef<'a, U>
70 where
71 T: Into<U>,
72 {
73 PeripheralRef {
74 inner: self.inner.into(),
75 _lifetime: PhantomData,
76 }
77 }
78}
79
80impl<'a, T> Deref for PeripheralRef<'a, T> {
81 type Target = T;
82
83 #[inline]
84 fn deref(&self) -> &Self::Target {
85 &self.inner
86 }
87}
88
89/// Trait for any type that can be used as a peripheral of type `P`.
90///
91/// This is used in driver constructors, to allow passing either owned peripherals (e.g. `TWISPI0`),
92/// or borrowed peripherals (e.g. `&mut TWISPI0`).
93///
94/// For example, if you have a driver with a constructor like this:
95///
96/// ```ignore
97/// impl<'d, T: Instance> Twim<'d, T> {
98/// pub fn new(
99/// twim: impl Peripheral<P = T> + 'd,
100/// irq: impl Peripheral<P = T::Interrupt> + 'd,
101/// sda: impl Peripheral<P = impl GpioPin> + 'd,
102/// scl: impl Peripheral<P = impl GpioPin> + 'd,
103/// config: Config,
104/// ) -> Self { .. }
105/// }
106/// ```
107///
108/// You may call it with owned peripherals, which yields an instance that can live forever (`'static`):
109///
110/// ```ignore
111/// let mut twi: Twim<'static, ...> = Twim::new(p.TWISPI0, irq, p.P0_03, p.P0_04, config);
112/// ```
113///
114/// Or you may call it with borrowed peripherals, which yields an instance that can only live for as long
115/// as the borrows last:
116///
117/// ```ignore
118/// let mut twi: Twim<'_, ...> = Twim::new(&mut p.TWISPI0, &mut irq, &mut p.P0_03, &mut p.P0_04, config);
119/// ```
120///
121/// # Implementation details, for HAL authors
122///
123/// When writing a HAL, the intended way to use this trait is to take `impl Peripheral<P = ..>` in
124/// the HAL's public API (such as driver constructors), calling `.into_ref()` to obtain a `PeripheralRef`,
125/// and storing that in the driver struct.
126///
127/// `.into_ref()` on an owned `T` yields a `PeripheralRef<'static, T>`.
128/// `.into_ref()` on an `&'a mut T` yields a `PeripheralRef<'a, T>`.
129pub trait Peripheral: Sized {
130 /// Peripheral singleton type
131 type P;
132
133 /// Unsafely clone (duplicate) a peripheral singleton.
134 ///
135 /// # Safety
136 ///
137 /// This returns an owned clone of the peripheral. You must manually ensure
138 /// only one copy of the peripheral is in use at a time. For example, don't
139 /// create two SPI drivers on `SPI1`, because they will "fight" each other.
140 ///
141 /// You should strongly prefer using `into_ref()` instead. It returns a
142 /// `PeripheralRef`, which allows the borrow checker to enforce this at compile time.
143 unsafe fn clone_unchecked(&self) -> Self::P;
144
145 /// Convert a value into a `PeripheralRef`.
146 ///
147 /// When called on an owned `T`, yields a `PeripheralRef<'static, T>`.
148 /// When called on an `&'a mut T`, yields a `PeripheralRef<'a, T>`.
149 #[inline]
150 fn into_ref<'a>(self) -> PeripheralRef<'a, Self::P>
151 where
152 Self: 'a,
153 {
154 PeripheralRef::new(unsafe { self.clone_unchecked() })
155 }
156}
157
158impl<'b, T: DerefMut> Peripheral for T
159where
160 T::Target: Peripheral,
161{
162 type P = <T::Target as Peripheral>::P;
163
164 #[inline]
165 unsafe fn clone_unchecked(&self) -> Self::P {
166 T::Target::clone_unchecked(self)
167 }
168}
169
170impl<'b, T: Peripheral> Peripheral for PeripheralRef<'_, T> {
171 type P = T::P;
172
173 #[inline]
174 unsafe fn clone_unchecked(&self) -> Self::P {
175 T::clone_unchecked(self)
176 }
177}
178