PeripheralRef init: uart

esp-hal-common/src/lib.rs

@@ -22,15 +22,23 @@
 #![cfg_attr(xtensa, feature(asm_experimental_arch))]
 
 #[cfg(esp32)]
-pub use esp32 as pac;
+pub(crate) use esp32 as pac;
 #[cfg(esp32c2)]
-pub use esp32c2 as pac;
+pub(crate) use esp32c2 as pac;
 #[cfg(esp32c3)]
-pub use esp32c3 as pac;
+pub(crate) use esp32c3 as pac;
 #[cfg(esp32s2)]
-pub use esp32s2 as pac;
+pub(crate) use esp32s2 as pac;
 #[cfg(esp32s3)]
-pub use esp32s3 as pac;
+pub(crate) use esp32s3 as pac;
+
+#[cfg_attr(esp32, path = "peripherals/esp32.rs")]
+#[cfg_attr(esp32c3, path = "peripherals/esp32c3.rs")]
+#[cfg_attr(esp32c2, path = "peripherals/esp32c2.rs")]
+#[cfg_attr(esp32s2, path = "peripherals/esp32s2.rs")]
+#[cfg_attr(esp32s3, path = "peripherals/esp32s3.rs")]
+pub mod peripherals;
+
 pub use procmacros as macros;
 
 #[cfg(rmt)]
@@ -43,7 +51,7 @@ pub use self::{
     interrupt::*,
     rng::Rng,
     rtc_cntl::{Rtc, Rwdt},
-    serial::Serial,
+    uart::Uart,
     spi::Spi,
     timer::Timer,
 };
@@ -63,14 +71,15 @@ pub mod ledc;
 pub mod mcpwm;
 #[cfg(usb_otg)]
 pub mod otg_fs;
+pub mod peripheral;
 pub mod prelude;
 #[cfg(rmt)]
 pub mod pulse_control;
 pub mod rng;
 pub mod rom;
 pub mod rtc_cntl;
-pub mod serial;
 pub mod sha;
+pub mod uart;
 pub mod spi;
 pub mod system;
 #[cfg(systimer)]

esp-hal-common/src/peripheral.rs

@@ -0,0 +1,308 @@
+use core::{
+    marker::PhantomData,
+    ops::{Deref, DerefMut},
+};
+
+/// An exclusive reference to a peripheral.
+///
+/// This is functionally the same as a `&'a mut T`. The reason for having a
+/// dedicated struct is memory efficiency:
+///
+/// Peripheral singletons are typically either zero-sized (for concrete
+/// peripehrals like `PA9` or `Spi4`) or very small (for example `AnyPin` which
+/// is 1 byte). However `&mut T` is always 4 bytes for 32-bit targets, even if T
+/// is zero-sized. PeripheralRef stores a copy of `T` instead, so it's the same
+/// size.
+///
+/// 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 PeripheralRef<'a, T> {
+    inner: T,
+    _lifetime: PhantomData<&'a mut T>,
+}
+
+impl<'a, T> PeripheralRef<'a, T> {
+    #[inline]
+    pub fn new(inner: T) -> Self {
+        Self {
+            inner,
+            _lifetime: PhantomData,
+        }
+    }
+
+    /// Unsafely clone (duplicate) a peripheral singleton.
+    ///
+    /// # Safety
+    ///
+    /// This returns an owned clone of the peripheral. You must manually ensure
+    /// only one copy of the peripheral is in use at a time. For example, don't
+    /// create two SPI drivers on `SPI1`, because they will "fight" each other.
+    ///
+    /// You should strongly prefer using `reborrow()` instead. It returns a
+    /// `PeripheralRef` that borrows `self`, which allows the borrow checker
+    /// to enforce this at compile time.
+    pub unsafe fn clone_unchecked(&mut self) -> PeripheralRef<'a, T>
+    where
+        T: Peripheral<P = T>,
+    {
+        PeripheralRef::new(self.inner.clone_unchecked())
+    }
+
+    /// Reborrow into a "child" PeripheralRef.
+    ///
+    /// `self` will stay borrowed until the child PeripheralRef is dropped.
+    pub fn reborrow(&mut self) -> PeripheralRef<'_, T>
+    where
+        T: Peripheral<P = T>,
+    {
+        // safety: we're returning the clone inside a new PeripheralRef that borrows
+        // self, so user code can't use both at the same time.
+        PeripheralRef::new(unsafe { self.inner.clone_unchecked() })
+    }
+
+    /// Map the inner peripheral using `Into`.
+    ///
+    /// This converts from `PeripheralRef<'a, T>` to `PeripheralRef<'a, U>`,
+    /// using an `Into` impl to convert from `T` to `U`.
+    ///
+    /// For example, this can be useful to degrade GPIO pins: converting from
+    /// PeripheralRef<'a, PB11>` to `PeripheralRef<'a, AnyPin>`.
+    #[inline]
+    pub fn map_into<U>(self) -> PeripheralRef<'a, U>
+    where
+        T: Into<U>,
+    {
+        PeripheralRef {
+            inner: self.inner.into(),
+            _lifetime: PhantomData,
+        }
+    }
+}
+
+impl<'a, T> Deref for PeripheralRef<'a, T> {
+    type Target = T;
+
+    #[inline]
+    fn deref(&self) -> &Self::Target {
+        &self.inner
+    }
+}
+
+impl<'a, T> DerefMut for PeripheralRef<'a, T> {
+    #[inline]
+    fn deref_mut(&mut self) -> &mut Self::Target {
+        &mut self.inner
+    }
+}
+
+/// Trait for any type that can be used as a peripheral of type `P`.
+///
+/// This is used in driver constructors, to allow passing either owned
+/// peripherals (e.g. `TWISPI0`), or borrowed peripherals (e.g. `&mut TWISPI0`).
+///
+/// For example, if you have a driver with a constructor like this:
+///
+/// ```ignore
+/// impl<'d, T: Instance> Twim<'d, T> {
+///     pub fn new(
+///         twim: impl Peripheral<P = T> + 'd,
+///         irq: impl Peripheral<P = T::Interrupt> + 'd,
+///         sda: impl Peripheral<P = impl GpioPin> + 'd,
+///         scl: impl Peripheral<P = impl GpioPin> + 'd,
+///         config: Config,
+///     ) -> Self { .. }
+/// }
+/// ```
+///
+/// You may call it with owned peripherals, which yields an instance that can
+/// live forever (`'static`):
+///
+/// ```ignore
+/// let mut twi: Twim<'static, ...> = Twim::new(p.TWISPI0, irq, p.P0_03, p.P0_04, config);
+/// ```
+///
+/// Or you may call it with borrowed peripherals, which yields an instance that
+/// can only live for as long as the borrows last:
+///
+/// ```ignore
+/// let mut twi: Twim<'_, ...> = Twim::new(&mut p.TWISPI0, &mut irq, &mut p.P0_03, &mut p.P0_04, config);
+/// ```
+///
+/// # Implementation details, for HAL authors
+///
+/// When writing a HAL, the intended way to use this trait is to take `impl
+/// Peripheral<P = ..>` in the HAL's public API (such as driver constructors),
+/// calling `.into_ref()` to obtain a `PeripheralRef`, and storing that in the
+/// driver struct.
+///
+/// `.into_ref()` on an owned `T` yields a `PeripheralRef<'static, T>`.
+/// `.into_ref()` on an `&'a mut T` yields a `PeripheralRef<'a, T>`.
+pub trait Peripheral: Sized + sealed::Sealed {
+    /// Peripheral singleton type
+    type P;
+
+    /// Unsafely clone (duplicate) a peripheral singleton.
+    ///
+    /// # Safety
+    ///
+    /// This returns an owned clone of the peripheral. You must manually ensure
+    /// only one copy of the peripheral is in use at a time. For example, don't
+    /// create two SPI drivers on `SPI1`, because they will "fight" each other.
+    ///
+    /// You should strongly prefer using `into_ref()` instead. It returns a
+    /// `PeripheralRef`, which allows the borrow checker to enforce this at
+    /// compile time.
+    unsafe fn clone_unchecked(&mut self) -> Self::P;
+
+    /// Convert a value into a `PeripheralRef`.
+    ///
+    /// When called on an owned `T`, yields a `PeripheralRef<'static, T>`.
+    /// When called on an `&'a mut T`, yields a `PeripheralRef<'a, T>`.
+    #[inline]
+    fn into_ref<'a>(mut self) -> PeripheralRef<'a, Self::P>
+    where
+        Self: 'a,
+    {
+        PeripheralRef::new(unsafe { self.clone_unchecked() })
+    }
+}
+
+impl<T: DerefMut> sealed::Sealed for T {}
+
+pub(crate) mod sealed {
+    pub trait Sealed {}
+}
+
+mod peripheral_macros {
+    #[macro_export]
+    macro_rules! peripherals {
+        ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
+            #[allow(non_snake_case)]
+            pub struct Peripherals {
+                $(
+                    $(#[$cfg])?
+                    pub $name: peripherals::$name,
+                )*
+            }
+
+            impl Peripherals {
+                /// Returns all the peripherals *once*
+                #[inline]
+                pub fn take() -> Self {
+
+                    #[no_mangle]
+                    static mut _ESP_HAL_DEVICE_PERIPHERALS: bool = false;
+
+                    critical_section::with(|_| unsafe {
+                        if _ESP_HAL_DEVICE_PERIPHERALS {
+                            panic!("init called more than once!")
+                        }
+                        _ESP_HAL_DEVICE_PERIPHERALS = true;
+                        Self::steal()
+                    })
+                }
+            }
+
+            impl Peripherals {
+                /// Unsafely create an instance of this peripheral out of thin air.
+                ///
+                /// # Safety
+                ///
+                /// You must ensure that you're only using one instance of this type at a time.
+                #[inline]
+                pub unsafe fn steal() -> Self {
+                    Self {
+                        $(
+                            $(#[$cfg])?
+                            // $name: peripherals::$name::steal(), // FIXME add this back once we have removed pac::Peripherals completely
+                            $name: unsafe { core::mem::zeroed() }, // this is well defined for zero sized types: https://github.com/rust-lang/unsafe-code-guidelines/issues/250
+                        )*
+                    }
+                }
+            }
+
+            // expose the new structs
+            $(
+                pub use peripherals::$name;
+            )*
+        }
+    }
+
+    #[macro_export]
+    macro_rules! create_peripherals {
+        ($($(#[$cfg:meta])? $name:ident),*$(,)?) => {
+            $(
+                $(#[$cfg])?
+                #[derive(Debug)]
+                #[allow(non_camel_case_types)]
+                pub struct $name { _inner: () }
+
+                $(#[$cfg])?
+                impl $name {
+                    /// Unsafely create an instance of this peripheral out of thin air.
+                    ///
+                    /// # Safety
+                    ///
+                    /// You must ensure that you're only using one instance of this type at a time.
+                    #[inline]
+                    pub unsafe fn steal() -> Self {
+                        Self { _inner: () }
+                    }
+
+                    #[doc = r"Pointer to the register block"]
+                    pub const PTR: *const <super::pac::$name as core::ops::Deref>::Target = super::pac::$name::PTR;
+
+                    #[doc = r"Return the pointer to the register block"]
+                    #[inline(always)]
+                    pub const fn ptr() -> *const <super::pac::$name as core::ops::Deref>::Target {
+                        super::pac::$name::PTR
+                    }
+                }
+
+                impl core::ops::Deref for $name {
+                    type Target = <super::pac::$name as core::ops::Deref>::Target;
+
+                    fn deref(&self) -> &Self::Target {
+                        unsafe { &*Self::PTR }
+                    }
+                }
+
+                impl core::ops::DerefMut for $name {
+
+                    fn deref_mut(&mut self) -> &mut Self::Target {
+                        unsafe { &mut *(Self::PTR as *mut _)  }
+                    }
+                }
+
+                impl crate::peripheral::Peripheral for $name {
+                    type P = $name;
+
+                    #[inline]
+                    unsafe fn clone_unchecked(&mut self) -> Self::P {
+                        Self::steal()
+                    }
+                }
+
+                impl crate::peripheral::Peripheral for &mut $name {
+                    type P = $name;
+
+                    #[inline]
+                    unsafe fn clone_unchecked(&mut self) -> Self::P {
+                        $name::steal()
+                    }
+                }
+
+
+            )*
+        }
+    }
+
+    #[macro_export]
+    macro_rules! into_ref {
+    ($($name:ident),*) => {
+        $(
+            let $name = $name.into_ref();
+        )*
+    }
+}
+}