Add error traits for communication interfaces

Author: eldruin

src/blocking/i2c.rs

@@ -22,13 +22,21 @@
 //! Here is an example of an embedded-hal implementation of the `Write` trait
 //! for both modes:
 //! ```
-//! # use embedded_hal::blocking::i2c::{SevenBitAddress, TenBitAddress, Write};
+//! # use embedded_hal::blocking::i2c::{Error, ErrorKind, SevenBitAddress, TenBitAddress, Write};
 //! /// I2C0 hardware peripheral which supports both 7-bit and 10-bit addressing.
 //! pub struct I2c0;
 //!
+//! # #[derive(Debug)]
+//! # pub struct I2cError;
+//! # impl Error for I2cError {
+//! #     fn kind(&self) -> ErrorKind {
+//! #         unreachable!()
+//! #     }
+//! # }
+//! #
 //! impl Write<SevenBitAddress> for I2c0
 //! {
-//! #   type Error = ();
+//! #   type Error = I2cError;
 //! #
 //!     fn write(&mut self, addr: u8, output: &[u8]) -> Result<(), Self::Error> {
 //!         // ...
@@ -38,7 +46,7 @@
 //!
 //! impl Write<TenBitAddress> for I2c0
 //! {
-//! #   type Error = ();
+//! #   type Error = I2cError;
 //! #
 //!     fn write(&mut self, addr: u16, output: &[u8]) -> Result<(), Self::Error> {
 //!         // ...
@@ -52,7 +60,7 @@
 //! For demonstration purposes the address mode parameter has been omitted in this example.
 //!
 //! ```
-//! # use embedded_hal::blocking::i2c::WriteRead;
+//! # use embedded_hal::blocking::i2c::{Error, WriteRead};
 //! const ADDR: u8  = 0x15;
 //! # const TEMP_REGISTER: u8 = 0x1;
 //! pub struct TemperatureSensorDriver<I2C> {
@@ -62,6 +70,7 @@
 //! impl<I2C, E> TemperatureSensorDriver<I2C>
 //! where
 //!     I2C: WriteRead<Error = E>,
+//!     E: Error,
 //! {
 //!     pub fn read_temperature(&mut self) -> Result<u8, E> {
 //!         let mut temp = [0];
@@ -75,7 +84,7 @@
 //! ### Device driver compatible only with 10-bit addresses
 //!
 //! ```
-//! # use embedded_hal::blocking::i2c::{TenBitAddress, WriteRead};
+//! # use embedded_hal::blocking::i2c::{Error, TenBitAddress, WriteRead};
 //! const ADDR: u16  = 0x158;
 //! # const TEMP_REGISTER: u8 = 0x1;
 //! pub struct TemperatureSensorDriver<I2C> {
@@ -85,6 +94,7 @@
 //! impl<I2C, E> TemperatureSensorDriver<I2C>
 //! where
 //!     I2C: WriteRead<TenBitAddress, Error = E>,
+//!     E: Error,
 //! {
 //!     pub fn read_temperature(&mut self) -> Result<u8, E> {
 //!         let mut temp = [0];
@@ -112,10 +122,12 @@ impl AddressMode for SevenBitAddress {}
 
 impl AddressMode for TenBitAddress {}
 
+pub use crate::errors::i2c::{Error, ErrorKind};
+
 /// Blocking read
 pub trait Read<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Reads enough bytes from slave with `address` to fill `buffer`
     ///
@@ -141,7 +153,7 @@ pub trait Read<A: AddressMode = SevenBitAddress> {
 /// Blocking write
 pub trait Write<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes bytes to slave with address `address`
     ///
@@ -165,7 +177,7 @@ pub trait Write<A: AddressMode = SevenBitAddress> {
 /// Blocking write (iterator version)
 pub trait WriteIter<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes bytes to slave with address `address`
     ///
@@ -180,7 +192,7 @@ pub trait WriteIter<A: AddressMode = SevenBitAddress> {
 /// Blocking write + read
 pub trait WriteRead<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes bytes to slave with address `address` and then reads enough bytes to fill `buffer` *in a
     /// single transaction*
@@ -215,7 +227,7 @@ pub trait WriteRead<A: AddressMode = SevenBitAddress> {
 /// Blocking write (iterator version) + read
 pub trait WriteIterRead<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes bytes to slave with address `address` and then reads enough bytes to fill `buffer` *in a
     /// single transaction*
@@ -249,7 +261,7 @@ pub enum Operation<'a> {
 /// This allows combining operations within an I2C transaction.
 pub trait Transactional<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Execute the provided operations on the I2C bus.
     ///
@@ -273,7 +285,7 @@ pub trait Transactional<A: AddressMode = SevenBitAddress> {
 /// This allows combining operation within an I2C transaction.
 pub trait TransactionalIter<A: AddressMode = SevenBitAddress> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Execute the provided operations on the I2C bus (iterator version).
     ///

src/blocking/serial.rs

@@ -1,9 +1,11 @@
 //! Blocking serial API
 
+pub use crate::errors::serial::{Error, ErrorKind};
+
 /// Write half of a serial interface (blocking variant)
 pub trait Write<Word> {
     /// The type of error that can occur when writing
-    type Error;
+    type Error: Error;
 
     /// Writes a slice, blocking until everything has been written
     ///

src/blocking/spi.rs

@@ -1,9 +1,11 @@
 //! Blocking SPI API
 
+pub use crate::errors::spi::{Error, ErrorKind};
+
 /// Blocking transfer
 pub trait Transfer<W> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes and reads simultaneously. The contents of `words` are
     /// written to the slave, and the received words are stored into the same
@@ -14,7 +16,7 @@ pub trait Transfer<W> {
 /// Blocking write
 pub trait Write<W> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes `words` to the slave, ignoring all the incoming words
     fn write(&mut self, words: &[W]) -> Result<(), Self::Error>;
@@ -23,7 +25,7 @@ pub trait Write<W> {
 /// Blocking write (iterator version)
 pub trait WriteIter<W> {
     /// Error type
-    type Error;
+    type Error: Error;
 
     /// Writes `words` to the slave, ignoring all the incoming words
     fn write_iter<WI>(&mut self, words: WI) -> Result<(), Self::Error>
@@ -46,7 +48,7 @@ pub enum Operation<'a, W: 'static> {
 /// as part of a single SPI transaction
 pub trait Transactional<W: 'static> {
     /// Associated error type
-    type Error;
+    type Error: Error;
 
     /// Execute the provided transactions
     fn exec<'a>(&mut self, operations: &mut [Operation<'a, W>]) -> Result<(), Self::Error>;

src/errors.rs

@@ -0,0 +1,121 @@
+//! Error definitions
+
+pub mod i2c {
+    /// I2C error
+    pub trait Error: core::fmt::Debug {
+        /// Convert error to a generic I2C error kind
+        ///
+        /// By using this method I2C errors freely defined by HAL implementations
+        /// can be converted to a set of generic I2C errors upon which generic
+        /// code can act.
+        fn kind(&self) -> ErrorKind;
+    }
+
+    /// I2C error kind
+    ///
+    /// This represents a common set of I2C operation errors. HAL implementations are
+    /// free to define more specific or additional error types. However, by providing
+    /// a mapping to these common I2C errors, generic code can still react to them.
+    #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+    #[non_exhaustive]
+    pub enum ErrorKind {
+        /// An unspecific bus error occurred
+        Bus,
+        /// The arbitration was lost, e.g. electrical problems with the clock signal
+        ArbitrationLoss,
+        /// A bus operation was not acknowledged, e.g. due to the addressed device not being available on
+        /// the bus or the device not being ready to process requests at the moment
+        NoAcknowledge,
+        /// The peripheral receive buffer was overrun
+        Overrun,
+        /// The peripheral send buffer ran out of data
+        Underrun,
+        /// A different error occurred. The original error may contain more information.
+        Other,
+    }
+
+    impl Error for ErrorKind {
+        fn kind(&self) -> ErrorKind {
+            *self
+        }
+    }
+}
+
+pub mod spi {
+    /// SPI error
+    pub trait Error: core::fmt::Debug {
+        /// Convert error to a generic SPI error kind
+        ///
+        /// By using this method SPI errors freely defined by HAL implementations
+        /// can be converted to a set of generic SPI errors upon which generic
+        /// code can act.
+        fn kind(&self) -> ErrorKind;
+    }
+
+    /// SPI error kind
+    ///
+    /// This represents a common set of SPI operation errors. HAL implementations are
+    /// free to define more specific or additional error types. However, by providing
+    /// a mapping to these common SPI errors, generic code can still react to them.
+    #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+    #[non_exhaustive]
+    pub enum ErrorKind {
+        /// An unspecific bus error occurred
+        Bus,
+        /// The peripheral receive buffer was overrun
+        Overrun,
+        /// Multiple devices on the SPI bus are trying across each other, e.g. in a multi-master setup
+        ModeFault,
+        /// CRC does not match the received data
+        CrcError,
+        /// Received data does not conform to the peripheral configuration
+        FrameFormat,
+        /// A different error occurred. The original error may contain more information.
+        Other,
+    }
+
+    impl Error for ErrorKind {
+        fn kind(&self) -> ErrorKind {
+            *self
+        }
+    }
+}
+
+pub mod serial {
+    /// Serial error
+    pub trait Error: core::fmt::Debug {
+        /// Convert error to a generic serial error kind
+        ///
+        /// By using this method serial errors freely defined by HAL implementations
+        /// can be converted to a set of generic serial errors upon which generic
+        /// code can act.
+        fn kind(&self) -> ErrorKind;
+    }
+
+    /// Serial error kind
+    ///
+    /// This represents a common set of serial operation errors. HAL implementations are
+    /// free to define more specific or additional error types. However, by providing
+    /// a mapping to these common serial errors, generic code can still react to them.
+    #[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)]
+    #[non_exhaustive]
+    pub enum ErrorKind {
+        /// The peripheral receive buffer was overrun.
+        Overrun,
+        /// Received data does not conform to the peripheral configuration.
+        /// Can be caused by a misconfigured device on either end of the serial line.
+        FrameFormat,
+        /// Parity check failed.
+        Parity,
+        /// Serial line is too noisy to read valid data.
+        Noise,
+        /// A different error occurred. The original error may contain more information.
+        Other,
+    }
+
+    impl Error for ErrorKind {
+        fn kind(&self) -> ErrorKind {
+            *self
+        }
+    }
+}

src/fmt.rs

@@ -6,6 +6,7 @@ use core::fmt::{Result, Write};
 impl<Word, Error> Write for dyn crate::nb::serial::Write<Word, Error = Error> + '_
 where
     Word: From<u8>,
+    Error: crate::nb::serial::Error,
 {
     fn write_str(&mut self, s: &str) -> Result {
         let _ = s

src/lib.rs

@@ -327,11 +327,10 @@
 //! use nb;
 //!
 //! use hal::nb::serial::Write;
-//! use ::core::convert::Infallible;
 //!
 //! fn flush<S>(serial: &mut S, cb: &mut CircularBuffer)
 //! where
-//!     S: hal::nb::serial::Write<u8, Error = Infallible>,
+//!     S: hal::nb::serial::Write<u8, Error = SerialError>,
 //! {
 //!     loop {
 //!         if let Some(byte) = cb.peek() {
@@ -396,16 +395,23 @@
 //! # }
 //! # struct Serial1;
 //! # impl hal::nb::serial::Write<u8> for Serial1 {
-//! #   type Error = Infallible;
-//! #   fn write(&mut self, _: u8) -> nb::Result<(), Infallible> { Err(::nb::Error::WouldBlock) }
-//! #   fn flush(&mut self) -> nb::Result<(), Infallible> { Err(::nb::Error::WouldBlock) }
+//! #   type Error = SerialError;
+//! #   fn write(&mut self, _: u8) -> nb::Result<(), Self::Error> { Err(::nb::Error::WouldBlock) }
+//! #   fn flush(&mut self) -> nb::Result<(), Self::Error> { Err(::nb::Error::WouldBlock) }
 //! # }
 //! # struct CircularBuffer;
 //! # impl CircularBuffer {
 //! #   pub fn peek(&mut self) -> Option<&u8> { None }
 //! #   pub fn pop(&mut self) -> Option<u8> { None }
 //! #   pub fn push(&mut self, _: u8) -> Result<(), ()> { Ok(()) }
 //! # }
+//! # #[derive(Debug)]
+//! # pub struct SerialError;
+//! # impl hal::nb::serial::Error for SerialError {
+//! #     fn kind(&self) -> hal::nb::serial::ErrorKind {
+//! #         unreachable!()
+//! #     }
+//! # }
 //!
 //! # fn main() {}
 //! ```
@@ -415,6 +421,7 @@
 #![no_std]
 
 pub mod blocking;
+mod errors;
 pub mod fmt;
 pub mod nb;
 

src/nb/serial.rs

@@ -1,12 +1,14 @@
 //! Serial interface
 
+pub use crate::errors::serial::{Error, ErrorKind};
+
 /// Read half of a serial interface
 ///
 /// Some serial interfaces support different data sizes (8 bits, 9 bits, etc.);
 /// This can be encoded in this trait via the `Word` type parameter.
 pub trait Read<Word> {
     /// Read error
-    type Error;
+    type Error: Error;
 
     /// Reads a single word from the serial interface
     fn read(&mut self) -> nb::Result<Word, Self::Error>;
@@ -15,7 +17,7 @@ pub trait Read<Word> {
 /// Write half of a serial interface
 pub trait Write<Word> {
     /// Write error
-    type Error;
+    type Error: Error;
 
     /// Writes a single word to the serial interface
     fn write(&mut self, word: Word) -> nb::Result<(), Self::Error>;