From 03b3245eebeba7ac40b37fed6c3dc796fdda7656 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Quentin?= Date: Wed, 24 Apr 2024 15:39:31 +0200 Subject: [PATCH] Cleanup PARL_IO (#1508) * Cleanup PARL_IO * remove not-needed `#[non_exhaustive]` --- esp-hal/src/parl_io.rs | 114 +++++++++++++++++++++++++---------------- 1 file changed, 70 insertions(+), 44 deletions(-) diff --git a/esp-hal/src/parl_io.rs b/esp-hal/src/parl_io.rs index 8d76bf17a12..c8fdc837cbb 100644 --- a/esp-hal/src/parl_io.rs +++ b/esp-hal/src/parl_io.rs @@ -76,6 +76,7 @@ //! let mut transfer = parl_io_rx.read_dma(buffer).unwrap(); //! transfer.wait().unwrap(); //! ``` +#![warn(missing_docs)] use core::marker::PhantomData; @@ -100,10 +101,16 @@ use crate::{ #[allow(unused)] const MAX_DMA_SIZE: usize = 32736; +/// Interrupts generated by the peripheral #[derive(EnumSetType)] pub enum ParlIoInterrupt { + /// Triggered when TX FIFO is empty. This interrupt indicates that there + /// might be error in the data sent by TX. TxFifoReEmpty, + /// Triggered when RX FIFO is full. This interrupt indicates that there + /// might be error in the data received by RX. RxFifoWOvf, + /// Triggered when TX finishes sending a complete frame of data. TxEof, } @@ -313,6 +320,7 @@ impl<'d, P> ClkOutPin<'d, P> where P: OutputPin, { + /// Create a ClkOutPin pub fn new(pin: impl Peripheral

+ 'd) -> Self { crate::into_ref!(pin); Self { pin } @@ -340,6 +348,7 @@ impl<'d, P> ClkInPin<'d, P> where P: InputPin, { + /// Create a new ClkInPin pub fn new(pin: impl Peripheral

+ 'd) -> Self { crate::into_ref!(pin); Self { pin } @@ -372,6 +381,7 @@ impl<'d, P> RxClkInPin<'d, P> where P: InputPin, { + /// Create a new RxClkInPin pub fn new(pin: impl Peripheral

+ 'd, sample_edge: SampleEdge) -> Self { crate::into_ref!(pin); Self { pin, sample_edge } @@ -409,6 +419,7 @@ where P: NotContainsValidSignalPin + TxPins + ConfigurePins, VP: OutputPin, { + /// Create a [TxPinConfigWithValidPin] pub fn new(tx_pins: P, valid_pin: impl Peripheral

+ 'd) -> Self { crate::into_ref!(valid_pin); Self { tx_pins, valid_pin } @@ -449,6 +460,7 @@ impl

TxPinConfigIncludingValidPin

where P: ContainsValidSignalPin + TxPins + ConfigurePins, { + /// Create a new [TxPinConfigIncludingValidPin] pub fn new(tx_pins: P) -> Self { Self { tx_pins } } @@ -486,6 +498,7 @@ macro_rules! tx_pins { where $($pin: OutputPin),+ { + /// Create a new TX pin #[allow(clippy::too_many_arguments)] pub fn new( $( @@ -615,6 +628,7 @@ where P: NotContainsValidSignalPin + RxPins + ConfigurePins, VP: InputPin, { + /// Create a new [RxPinConfigWithValidPin] pub fn new( rx_pins: P, valid_pin: impl Peripheral

+ 'd, @@ -678,6 +692,7 @@ impl

RxPinConfigIncludingValidPin

where P: ContainsValidSignalPin + RxPins + ConfigurePins, { + /// Create a new [RxPinConfigIncludingValidPin] pub fn new(rx_pins: P, enable_mode: EnableMode, eof_mode: EofMode) -> Self { Self { rx_pins, @@ -730,6 +745,7 @@ macro_rules! rx_pins { where $($pin: InputPin),+ { + /// Create a new RX pin #[allow(clippy::too_many_arguments)] pub fn new( $( @@ -847,6 +863,7 @@ where CH: ChannelTypes, DM: Mode, { + /// Configure TX to use the given pins and settings pub fn with_config( self, mut tx_pins: P, @@ -880,6 +897,7 @@ where CH: ChannelTypes, DM: Mode, { + /// Configure TX to use the given pins and settings pub fn with_config( self, mut tx_pins: P, @@ -939,6 +957,7 @@ where CH: ChannelTypes, DM: Mode, { + /// Configure RX to use the given pins and settings pub fn with_config( self, mut rx_pins: P, @@ -970,6 +989,7 @@ where CH: ChannelTypes, DM: Mode, { + /// Configure RX to use the given pins and settings pub fn with_config( self, mut rx_pins: P, @@ -1115,6 +1135,7 @@ fn internal_clear_interrupts(interrupts: EnumSet) { /// Parallel IO in full duplex mode /// /// Full duplex mode might limit the maximum possible bit width. +#[allow(missing_docs)] pub struct ParlIoFullDuplex<'d, CH, DM> where CH: ChannelTypes, @@ -1131,6 +1152,7 @@ where CH::P: ParlIoPeripheral, DM: Mode, { + /// Create a new instance of [ParlIoFullDuplex] pub fn new( _parl_io: impl Peripheral

+ 'd, mut dma_channel: Channel<'d, CH, DM>, @@ -1187,6 +1209,7 @@ where } /// Parallel IO in half duplex / TX only mode +#[allow(missing_docs)] pub struct ParlIoTxOnly<'d, CH, DM> where CH: ChannelTypes, @@ -1202,6 +1225,7 @@ where CH::P: ParlIoPeripheral, DM: Mode, { + /// Create a new [ParlIoTxOnly] pub fn new( _parl_io: impl Peripheral

+ 'd, mut dma_channel: Channel<'d, CH, DM>, @@ -1254,6 +1278,7 @@ where } /// Parallel IO in half duplex / RX only mode +#[allow(missing_docs)] pub struct ParlIoRxOnly<'d, CH, DM> where CH: ChannelTypes, @@ -1269,6 +1294,7 @@ where CH::P: ParlIoPeripheral, DM: Mode, { + /// Create a new [ParlIoRxOnly] instance pub fn new( _parl_io: impl Peripheral

+ 'd, mut dma_channel: Channel<'d, CH, DM>, @@ -1378,8 +1404,7 @@ where { /// Perform a DMA write. /// - /// This will return a [DmaTransfer] owning the buffer(s) and the driver - /// instance. + /// This will return a [DmaTransfer] /// /// The maximum amount of data to be sent is 32736 bytes. pub fn write_dma<'t, TXBUF>( @@ -1481,8 +1506,7 @@ where { /// Perform a DMA read. /// - /// This will return a [RxDmaTransfer] owning the buffer(s) and the driver - /// instance. + /// This will return a [RxDmaTransfer] /// /// The maximum amount of data is 32736 bytes when using [EofMode::ByteLen]. /// @@ -1585,6 +1609,47 @@ where } } +/// Creates a TX channel +pub struct TxCreator<'d, CH, DM> +where + CH: ChannelTypes, + DM: Mode, +{ + tx_channel: CH::Tx<'d>, + phantom: PhantomData, +} + +/// Creates a RX channel +pub struct RxCreator<'d, CH, DM> +where + CH: ChannelTypes, + DM: Mode, +{ + rx_channel: CH::Rx<'d>, + phantom: PhantomData, +} + +/// Creates a TX channel +pub struct TxCreatorFullDuplex<'d, CH, DM> +where + CH: ChannelTypes, + DM: Mode, +{ + tx_channel: CH::Tx<'d>, + phantom: PhantomData, +} + +/// Creates a RX channel +pub struct RxCreatorFullDuplex<'d, CH, DM> +where + CH: ChannelTypes, + DM: Mode, +{ + rx_channel: CH::Rx<'d>, + phantom: PhantomData, +} + +#[doc(hidden)] #[cfg(feature = "async")] pub mod asynch { use core::task::Poll; @@ -1606,7 +1671,7 @@ pub mod asynch { static TX_WAKER: AtomicWaker = AtomicWaker::new(); - pub struct TxDoneFuture {} + struct TxDoneFuture {} impl TxDoneFuture { pub fn new() -> Self { @@ -1708,10 +1773,7 @@ pub mod asynch { } mod private { - use core::marker::PhantomData; - use super::{BitPackOrder, EofMode, Error, SampleEdge}; - use crate::{dma::ChannelTypes, Mode}; pub trait FullDuplex {} @@ -1735,42 +1797,6 @@ mod private { fn configure(&mut self) -> Result<(), Error>; } - pub struct TxCreator<'d, CH, DM> - where - CH: ChannelTypes, - DM: Mode, - { - pub tx_channel: CH::Tx<'d>, - pub(crate) phantom: PhantomData, - } - - pub struct RxCreator<'d, CH, DM> - where - CH: ChannelTypes, - DM: Mode, - { - pub rx_channel: CH::Rx<'d>, - pub(crate) phantom: PhantomData, - } - - pub struct TxCreatorFullDuplex<'d, CH, DM> - where - CH: ChannelTypes, - DM: Mode, - { - pub tx_channel: CH::Tx<'d>, - pub(crate) phantom: PhantomData, - } - - pub struct RxCreatorFullDuplex<'d, CH, DM> - where - CH: ChannelTypes, - DM: Mode, - { - pub rx_channel: CH::Rx<'d>, - pub(crate) phantom: PhantomData, - } - #[cfg(esp32c6)] pub(super) enum WidSel { Bits16 = 0,