Merge pull request #466 from rust-embedded/io

Add embedded-io, embedded-io-async, remove serial traits.

Author: eldruin

.github/workflows/clippy.yml

@@ -15,6 +15,6 @@ jobs:
         with:
           # embedded-hal-async needs nightly.
           # Use a pinned version to avoid spontaneous breakages (new clippy lints are added often)
-          toolchain: nightly-2022-11-22
+          toolchain: nightly-2023-07-03
           components: clippy
-      - run: cargo clippy  --features=embedded-hal-bus/std -- --deny=warnings
+      - run: cargo clippy  --features=std -- --deny=warnings

.github/workflows/test.yml

@@ -25,7 +25,9 @@ jobs:
           - thumbv7m-none-eabi
         include:
           - target: x86_64-unknown-linux-gnu
-            features: embedded-hal-bus/std
+            features: std
+          - target: x86_64-unknown-linux-gnu
+            features: alloc
 
     steps:
       - uses: actions/checkout@v3

Cargo.toml

@@ -7,4 +7,6 @@ members = [
     "embedded-hal-nb",
     "embedded-hal-bus",
     "embedded-can",
+    "embedded-io",
+    "embedded-io-async",  # nightly-only
 ]

embedded-hal-async/src/lib.rs

@@ -1,11 +1,9 @@
 #![doc = include_str!("../README.md")]
 #![warn(missing_docs)]
 #![no_std]
-#![allow(incomplete_features)]
 #![feature(async_fn_in_trait, impl_trait_projections)]
 
 pub mod delay;
 pub mod digital;
 pub mod i2c;
-pub mod serial;
 pub mod spi;

embedded-hal-async/src/serial.rs

@@ -1,6 +1,77 @@
 //! Serial interface
 
-pub use embedded_hal::serial::{Error, ErrorKind, ErrorType};
+/// 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;
+}
+
+impl Error for core::convert::Infallible {
+    fn kind(&self) -> ErrorKind {
+        match *self {}
+    }
+}
+
+/// 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
+    }
+}
+
+impl core::fmt::Display for ErrorKind {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        match self {
+            Self::Overrun => write!(f, "The peripheral receive buffer was overrun"),
+            Self::Parity => write!(f, "Parity check failed"),
+            Self::Noise => write!(f, "Serial line is too noisy to read valid data"),
+            Self::FrameFormat => write!(
+                f,
+                "Received data does not conform to the peripheral configuration"
+            ),
+            Self::Other => write!(
+                f,
+                "A different error occurred. The original error may contain more information"
+            ),
+        }
+    }
+}
+
+/// Serial error type trait
+///
+/// This just defines the error type, to be used by the other traits.
+pub trait ErrorType {
+    /// Error type
+    type Error: Error;
+}
+
+impl<T: ErrorType> ErrorType for &mut T {
+    type Error = T::Error;
+}
 
 /// Read half of a serial interface
 ///
@@ -40,8 +111,7 @@ impl<T: Write<Word>, Word: Copy> Write<Word> for &mut T {
 ///
 /// TODO write example of usage
 
-impl<Word, Error: embedded_hal::serial::Error> core::fmt::Write
-    for dyn Write<Word, Error = Error> + '_
+impl<Word, Error: self::Error> core::fmt::Write for dyn Write<Word, Error = Error> + '_
 where
     Word: Copy + From<u8>,
 {

embedded-hal-nb/src/serial.rs

@@ -81,7 +81,6 @@ pub mod delay;
 pub mod digital;
 pub mod i2c;
 pub mod pwm;
-pub mod serial;
 pub mod spi;
 
 mod private {

embedded-hal/src/lib.rs

@@ -0,0 +1,23 @@
+[package]
+name = "embedded-io-async"
+version = "0.5.0"
+edition = "2021"
+description = "Async embedded IO traits"
+repository = "https://github.com/rust-embedded/embedded-hal"
+readme = "README.md"
+license = "MIT OR Apache-2.0"
+categories = [
+    "embedded",
+    "no-std",
+]
+
+[features]
+std = ["alloc", "embedded-io/std"]
+alloc = ["embedded-io/alloc"]
+
+[dependencies]
+embedded-io = { version = "0.5", path = "../embedded-io" }
+
+[package.metadata.docs.rs]
+features = ["std"]
+rustdoc-args = ["--cfg", "docsrs"]

embedded-hal/src/serial.rs

@@ -0,0 +1,35 @@
+[![crates.io](https://img.shields.io/crates/d/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async)
+[![crates.io](https://img.shields.io/crates/v/embedded-io-async.svg)](https://crates.io/crates/embedded-io-async)
+[![Documentation](https://docs.rs/embedded-io-async/badge.svg)](https://docs.rs/embedded-io-async)
+
+# `embedded-io-async`
+
+Async IO traits for embedded systems.
+
+This crate contains asynchronous versions of the [`embedded-io`](https://crates.io/crates/embedded-io) traits and shares its scope and design goals.
+
+This project is developed and maintained by the [HAL team](https://github.com/rust-embedded/wg#the-hal-team).
+
+## Minimum Supported Rust Version (MSRV)
+
+This crate requires Rust nightly newer than `nightly-2022-11-22`, due to requiring support for
+`async fn` in traits (AFIT), which is not stable yet. 
+
+Keep in mind Rust nightlies can make backwards-incompatible changes to unstable features
+at any time.
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
+  <http://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+
+at your option.
+
+### Contribution
+
+Unless you explicitly state otherwise, any contribution intentionally submitted
+for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
+dual licensed as above, without any additional terms or conditions.

embedded-io-async/Cargo.toml

@@ -0,0 +1,44 @@
+use crate::{BufRead, Read, Seek, SeekFrom, Write};
+use alloc::boxed::Box;
+
+#[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
+impl<T: ?Sized + Read> Read for Box<T> {
+    #[inline]
+    async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error> {
+        T::read(self, buf).await
+    }
+}
+
+#[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
+impl<T: ?Sized + BufRead> BufRead for Box<T> {
+    #[inline]
+    async fn fill_buf(&mut self) -> Result<&[u8], Self::Error> {
+        T::fill_buf(self).await
+    }
+
+    #[inline]
+    fn consume(&mut self, amt: usize) {
+        T::consume(self, amt)
+    }
+}
+
+#[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
+impl<T: ?Sized + Write> Write for Box<T> {
+    #[inline]
+    async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error> {
+        T::write(self, buf).await
+    }
+
+    #[inline]
+    async fn flush(&mut self) -> Result<(), Self::Error> {
+        T::flush(self).await
+    }
+}
+
+#[cfg_attr(docsrs, doc(cfg(any(feature = "std", feature = "alloc"))))]
+impl<T: ?Sized + Seek> Seek for Box<T> {
+    #[inline]
+    async fn seek(&mut self, pos: SeekFrom) -> Result<u64, Self::Error> {
+        T::seek(self, pos).await
+    }
+}

embedded-io-async/README.md

@@ -0,0 +1,7 @@
+mod slice_mut;
+mod slice_ref;
+
+#[cfg(feature = "alloc")]
+mod boxx;
+#[cfg(feature = "alloc")]
+mod vec;