Trait Peripheral

Source

pub trait Peripheral: Sized + Sealed {
    type P;

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

    // Provided methods
    fn into_ref<'a>(self) -> PeripheralRef<'a, Self::P>
       where Self: 'a { ... }
    fn map_into<U>(self) -> U
       where Self::P: Into<U>,
             U: Peripheral<P = U> { ... }
    fn map<U>(self, transform: impl FnOnce(Self::P) -> U) -> U
       where U: Peripheral<P = U> { ... }
}

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. UART0), or borrowed peripherals (e.g. &mut UART0).

For example, if you have a driver with a constructor like this:

impl<'d, T> Uart<'d, T, Blocking> {
    pub fn new<TX: PeripheralOutput, RX: PeripheralInput>(
        uart: impl Peripheral<P = T> + 'd,
        rx: impl Peripheral<P = RX> + 'd,
        tx: impl Peripheral<P = TX> + 'd,
    ) -> Result<Self, Error> {
        Ok(Self { .. })
    }
}

You may call it with owned peripherals, which yields an instance that can live forever ('static):

let mut uart: Uart<'static, ...> = Uart::new(p.UART0, p.GPIO0, p.GPIO1);

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 uart: Uart<'_, ...> = Uart::new(&mut p.UART0, &mut p.GPIO0, &mut p.GPIO1);

§Implementation details, for HAL authors

When writing a HAL, the intended way to use this trait is to take impl Peripheral 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.

Provided Methods§

Source

fn into_ref<'a>(self) -> PeripheralRef<'a, Self::P>
where Self: 'a,

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

Source

fn map_into(self) -> U
where Self::P: Into, U: Peripheral,

Map the peripheral using Into.

This converts from Peripheral to Peripheral, using an Into impl to convert from T to U.

Source

fn map(self, transform: impl FnOnce(Self::P) -> U) -> U
where U: Peripheral,

Map the peripheral using Into.

This converts from Peripheral to Peripheral, using an Into impl to convert from T to U.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Trait PeripheralCopy item path

§Implementation details, for HAL authors

Required Associated Types§

type P

Required Methods§

unsafe fn clone_unchecked(&self) -> Self::P

§Safety

Provided Methods§

fn into_ref<'a>(self) -> PeripheralRef<'a, Self::P>where Self: 'a,

fn map_into<U>(self) -> Uwhere Self::P: Into<U>, U: Peripheral<P = U>,

fn map<U>(self, transform: impl FnOnce(Self::P) -> U) -> Uwhere U: Peripheral<P = U>,

Dyn Compatibility§

Implementations on Foreign Types§

impl<T, P> Peripheral for &mut Twhere T: Peripheral<P = P>,

type P = P

unsafe fn clone_unchecked(&self) -> Self::P

Implementors§

impl Peripheral for Level

type P = Level

impl Peripheral for AnyI2sDmaChannel

type P = AnyI2sDmaChannel

impl Peripheral for AnyI2sDmaRxChannel

type P = AnyI2sDmaRxChannel

impl Peripheral for AnyI2sDmaTxChannel

type P = AnyI2sDmaTxChannel

impl Peripheral for AnySpiDmaChannel

type P = AnySpiDmaChannel

impl Peripheral for AnySpiDmaRxChannel

type P = AnySpiDmaRxChannel

impl Peripheral for AnySpiDmaTxChannel

type P = AnySpiDmaTxChannel

impl Peripheral for I2s0DmaChannel

type P = I2s0DmaChannel

impl Peripheral for I2s1DmaChannel

type P = I2s1DmaChannel

impl Peripheral for Spi2DmaChannel

type P = Spi2DmaChannel

impl Peripheral for Spi3DmaChannel

type P = Spi3DmaChannel

impl Peripheral for InputConnection

type P = InputConnection

impl Peripheral for InputSignal

type P = InputSignal

impl Peripheral for OutputConnection

type P = OutputConnection

impl Peripheral for OutputSignal

type P = OutputSignal

impl Peripheral for AnyPin

type P = AnyPin

impl Peripheral for Flex<'_>

type P = Flex<'_>

impl Peripheral for NoPin

type P = NoPin

impl Peripheral for AnyI2c

type P = AnyI2c

impl Peripheral for esp_hal::i2s::master::AnyI2s

type P = AnyI2s

impl Peripheral for esp_hal::i2s::parallel::AnyI2s

type P = AnyI2s

impl Peripheral for ADC1

type P = ADC1

impl Peripheral for ADC2

type P = ADC2

impl Peripheral for AES

type P = AES

impl Peripheral for APB_CTRL

type P = APB_CTRL

impl Peripheral for BB

type P = BB

impl Peripheral for BT

type P = BT

impl Peripheral for CPU_CTRL

type P = CPU_CTRL

impl Peripheral for DAC1

type P = DAC1

impl Peripheral for DAC2

type P = DAC2

impl Peripheral for EFUSE

type P = EFUSE

impl Peripheral for FLASH_ENCRYPTION

Trait Peripheral

fn into_ref<'a>(self) -> PeripheralRef<'a, Self::P>
where Self: 'a,

fn map_into<U>(self) -> U
where Self::P: Into<U>, U: Peripheral<P = U>,

fn map<U>(self, transform: impl FnOnce(Self::P) -> U) -> U
where U: Peripheral<P = U>,

impl<T, P> Peripheral for &mut T
where T: Peripheral<P = P>,