diff --git a/esp-hal/MIGRATING-0.22.md b/esp-hal/MIGRATING-0.22.md index d50fd69c2..76fa15d7f 100644 --- a/esp-hal/MIGRATING-0.22.md +++ b/esp-hal/MIGRATING-0.22.md @@ -372,7 +372,7 @@ The `Config` struct's setters are now prefixed with `with_`. `parity_none`, `par The `DataBits`, `Parity`, and `StopBits` enum variants are no longer prefixed with the name of the enum. -e.g.) +e.g. ```diff - DataBits::DataBits8 @@ -387,6 +387,15 @@ The previous blocking implementation of `read_bytes` has been removed, and the n Any code which was previously using `read_bytes` to fill a buffer in a blocking manner will now need to implement the necessary logic to block until the buffer is filled in their application instead. +The `Error` enum variant uses object+verb naming. + +e.g. + +```diff +- RxGlichDetected ++ GlitchOccurred +``` + ## Spi `with_miso` has been split Previously, `with_miso` set up the provided pin as an input and output, which was necessary for half duplex. diff --git a/esp-hal/src/uart.rs b/esp-hal/src/uart.rs index 7ca3ed6cd..bfedac448 100644 --- a/esp-hal/src/uart.rs +++ b/esp-hal/src/uart.rs @@ -257,36 +257,29 @@ const CMD_CHAR_DEFAULT: u8 = 0x2b; #[cfg_attr(feature = "defmt", derive(defmt::Format))] #[non_exhaustive] pub enum Error { - /// An invalid configuration argument was provided. + /// The RX FIFO overflow happened. /// - /// This error occurs when an incorrect or invalid argument is passed during - /// the configuration of the UART peripheral. - InvalidArgument, - - /// The RX FIFO overflowed. - RxFifoOvf, + /// This error occurs when RX FIFO is full and a new byte is received. + FifoOverflowed, /// A glitch was detected on the RX line. /// /// This error occurs when an unexpected or erroneous signal (glitch) is /// detected on the UART RX line, which could lead to incorrect data /// reception. - RxGlitchDetected, + GlitchOccurred, /// A framing error was detected on the RX line. /// /// This error occurs when the received data does not conform to the /// expected UART frame format. - #[allow(clippy::enum_variant_names, reason = "Frame error is a common term")] - RxFrameError, + FrameFormatViolated, /// A parity error was detected on the RX line. /// /// This error occurs when the parity bit in the received data does not /// match the expected parity configuration. - /// with the `async` feature. - #[allow(clippy::enum_variant_names, reason = "Parity error is a common term")] - RxParityError, + ParityMismatch, } impl core::error::Error for Error {} @@ -294,11 +287,10 @@ impl core::error::Error for Error {} impl core::fmt::Display for Error { fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { match self { - Error::InvalidArgument => write!(f, "An invalid configuration argument was provided"), - Error::RxFifoOvf => write!(f, "The RX FIFO overflowed"), - Error::RxGlitchDetected => write!(f, "A glitch was detected on the RX line"), - Error::RxFrameError => write!(f, "A framing error was detected on the RX line"), - Error::RxParityError => write!(f, "A parity error was detected on the RX line"), + Error::FifoOverflowed => write!(f, "The RX FIFO overflowed"), + Error::GlitchOccurred => write!(f, "A glitch was detected on the RX line"), + Error::FrameFormatViolated => write!(f, "A framing error was detected on the RX line"), + Error::ParityMismatch => write!(f, "A parity error was detected on the RX line"), } } } @@ -1527,8 +1519,8 @@ where #[derive(Debug, EnumSetType)] pub(crate) enum TxEvent { - TxDone, - TxFiFoEmpty, + Done, + FiFoEmpty, } #[derive(Debug, EnumSetType)] @@ -1659,8 +1651,8 @@ impl UartTxFuture { let mut event_triggered = false; for event in self.events { event_triggered |= match event { - TxEvent::TxDone => interrupts_enabled.tx_done().bit_is_clear(), - TxEvent::TxFiFoEmpty => interrupts_enabled.txfifo_empty().bit_is_clear(), + TxEvent::Done => interrupts_enabled.tx_done().bit_is_clear(), + TxEvent::FiFoEmpty => interrupts_enabled.txfifo_empty().bit_is_clear(), } } event_triggered @@ -1670,8 +1662,8 @@ impl UartTxFuture { self.uart.register_block().int_ena().modify(|_, w| { for event in self.events { match event { - TxEvent::TxDone => w.tx_done().bit(enable), - TxEvent::TxFiFoEmpty => w.txfifo_empty().bit(enable), + TxEvent::Done => w.tx_done().bit(enable), + TxEvent::FiFoEmpty => w.txfifo_empty().bit(enable), }; } w @@ -1759,7 +1751,7 @@ where } offset = next_offset; - UartTxFuture::new(self.uart.reborrow(), TxEvent::TxFiFoEmpty).await; + UartTxFuture::new(self.uart.reborrow(), TxEvent::FiFoEmpty).await; } Ok(count) @@ -1773,7 +1765,7 @@ where pub async fn flush_async(&mut self) -> Result<(), Error> { let count = self.tx_fifo_count(); if count > 0 { - UartTxFuture::new(self.uart.reborrow(), TxEvent::TxDone).await; + UartTxFuture::new(self.uart.reborrow(), TxEvent::Done).await; } Ok(()) @@ -1803,10 +1795,10 @@ where /// /// # Ok /// When successful, returns the number of bytes written to buf. - /// This method will never return Ok(0) + /// If the passed in buffer is of length 0, Ok(0) is returned. pub async fn read_async(&mut self, buf: &mut [u8]) -> Result { if buf.is_empty() { - return Err(Error::InvalidArgument); + return Ok(0); } loop { @@ -1838,10 +1830,10 @@ where // check error events for event_happened in events_happened { match event_happened { - RxEvent::FifoOvf => return Err(Error::RxFifoOvf), - RxEvent::GlitchDetected => return Err(Error::RxGlitchDetected), - RxEvent::FrameError => return Err(Error::RxFrameError), - RxEvent::ParityError => return Err(Error::RxParityError), + RxEvent::FifoOvf => return Err(Error::FifoOverflowed), + RxEvent::GlitchDetected => return Err(Error::GlitchOccurred), + RxEvent::FrameError => return Err(Error::FrameFormatViolated), + RxEvent::ParityError => return Err(Error::ParityMismatch), RxEvent::FifoFull | RxEvent::CmdCharDetected | RxEvent::FifoTout => continue, } }