Trait embassy_hal_internal::Peripheral

source ·

pub trait Peripheral: Sized {
    type P;

    // Required method
    unsafe fn clone_unchecked(&self) -> Self::P;

    // Provided method
    fn into_ref<'a>(self) -> PeripheralRef<'a, Self::P>
       where Self: 'a { ... }
}

Expand description

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:

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):

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:

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

Required Associated Types§

source

type P

Peripheral singleton type

Required Methods§

source

unsafe fn clone_unchecked(&self) -> Self::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.