bus/i2c: add RefCell, CriticalSection and Mutex shared bus implementations.

Author: Dirbaio

.github/workflows/clippy.yml

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

.github/workflows/test.yml

@@ -13,17 +13,17 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        # All generated code should be running on stable now
         rust:
           - stable
           - 1.59.0  # MSRV
           - nightly
-
-        # The default target we're compiling on and for
         target:
           - x86_64-unknown-linux-gnu
           - thumbv6m-none-eabi
           - thumbv7m-none-eabi
+        include:
+          - target: x86_64-unknown-linux-gnu
+            features: embedded-hal-bus/std
 
     steps:
       - uses: actions/checkout@v3
@@ -35,7 +35,7 @@ jobs:
       - run: sed -i '/nightly-only/d' Cargo.toml 
         if: matrix.rust != 'nightly'
 
-      - run: cargo check --target=${{ matrix.target }}
+      - run: cargo check --target=${{ matrix.target }} --features=${{ matrix.features }}
 
-      - run: cargo test --target=${{ matrix.target }}
+      - run: cargo test --target=${{ matrix.target }} --features=${{ matrix.features }}
         if: contains(matrix.target, 'linux')

embedded-hal-bus/CHANGELOG.md

@@ -7,7 +7,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-...
+### Added
+- i2c: add bus sharing implementations.
 
 ## [v0.1.0-alpha.1] - 2022-09-28
 

embedded-hal-bus/Cargo.toml

@@ -13,5 +13,9 @@ readme = "README.md"
 repository = "https://github.com/rust-embedded/embedded-hal"
 version = "0.1.0-alpha.1"
 
+[features]
+std = []
+
 [dependencies]
 embedded-hal = { version = "=1.0.0-alpha.9", path = "../embedded-hal" }
+critical-section = { version = "1.0" }

embedded-hal-bus/src/i2c/critical_section.rs

@@ -0,0 +1,70 @@
+use core::cell::RefCell;
+use critical_section::Mutex;
+use embedded_hal::i2c::{ErrorType, I2c};
+
+/// `critical-section`-based shared bus [`I2c`] implementation.
+///
+/// Sharing is implemented with a `critical-section` [`Mutex`](critical_section::Mutex). A critical section is taken for
+/// the entire duration of a transaction. This allows sharing a single bus across multiple threads (interrupt priority levels).
+/// The downside is critical sections typically require globally disabling interrupts, so `CriticalSectionDevice` will likely
+/// negatively impact real-time properties, such as interrupt latency. If you can, prefer using
+/// [`RefCellDevice`](super::RefCellDevice) instead, which does not require taking critical sections.
+pub struct CriticalSectionDevice<'a, T> {
+    bus: &'a Mutex<RefCell<T>>,
+}
+
+impl<'a, T> CriticalSectionDevice<'a, T> {
+    /// Create a new Mutexdevice
+    pub fn new(bus: &'a Mutex<RefCell<T>>) -> Self {
+        Self { bus }
+    }
+}
+
+impl<'a, T> ErrorType for CriticalSectionDevice<'a, T>
+where
+    T: I2c,
+{
+    type Error = T::Error;
+}
+
+impl<'a, T> I2c for CriticalSectionDevice<'a, T>
+where
+    T: I2c,
+{
+    fn read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+            bus.read(address, read)
+        })
+    }
+
+    fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+            bus.write(address, write)
+        })
+    }
+
+    fn write_read(
+        &mut self,
+        address: u8,
+        write: &[u8],
+        read: &mut [u8],
+    ) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+            bus.write_read(address, write, read)
+        })
+    }
+
+    fn transaction(
+        &mut self,
+        address: u8,
+        operations: &mut [embedded_hal::i2c::Operation<'_>],
+    ) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+            bus.transaction(address, operations)
+        })
+    }
+}

embedded-hal-bus/src/i2c/mod.rs

@@ -0,0 +1,10 @@
+//! `I2c` shared bus implementations.
+
+mod refcell;
+pub use refcell::*;
+#[cfg(feature = "std")]
+mod mutex;
+#[cfg(feature = "std")]
+pub use mutex::*;
+mod critical_section;
+pub use self::critical_section::*;

embedded-hal-bus/src/i2c/mutex.rs

@@ -0,0 +1,59 @@
+use embedded_hal::i2c::{ErrorType, I2c};
+use std::sync::Mutex;
+
+/// `std` `Mutex`-based shared bus [`I2c`] implementation.
+///
+/// Sharing is implemented with a `std` [`Mutex`](std::sync::Mutex). It allows a single bus across multiple threads,
+/// with finer-grained locking than [`CriticalSectionDevice`](super::CriticalSectionDevice). The downside is
+/// it is only available in `std` targets.
+pub struct MutexDevice<'a, T> {
+    bus: &'a Mutex<T>,
+}
+
+impl<'a, T> MutexDevice<'a, T> {
+    /// Create a new Mutexdevice
+    pub fn new(bus: &'a Mutex<T>) -> Self {
+        Self { bus }
+    }
+}
+
+impl<'a, T> ErrorType for MutexDevice<'a, T>
+where
+    T: I2c,
+{
+    type Error = T::Error;
+}
+
+impl<'a, T> I2c for MutexDevice<'a, T>
+where
+    T: I2c,
+{
+    fn read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.lock().unwrap();
+        bus.read(address, read)
+    }
+
+    fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.lock().unwrap();
+        bus.write(address, write)
+    }
+
+    fn write_read(
+        &mut self,
+        address: u8,
+        write: &[u8],
+        read: &mut [u8],
+    ) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.lock().unwrap();
+        bus.write_read(address, write, read)
+    }
+
+    fn transaction(
+        &mut self,
+        address: u8,
+        operations: &mut [embedded_hal::i2c::Operation<'_>],
+    ) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.lock().unwrap();
+        bus.transaction(address, operations)
+    }
+}

embedded-hal-bus/src/i2c/refcell.rs

@@ -0,0 +1,59 @@
+use core::cell::RefCell;
+use embedded_hal::i2c::{ErrorType, I2c};
+
+/// `RefCell`-based shared bus [`I2c`] implementation.
+///
+/// Sharing is implemented with a `RefCell`. This means it has low overhead, but `RefCellDevice` instances are not `Send`,
+/// so it only allows sharing within a single thread (interrupt priority level). If you need to share a bus across several
+/// threads, use [`CriticalSectionDevice`](super::CriticalSectionDevice) instead.
+pub struct RefCellDevice<'a, T> {
+    bus: &'a RefCell<T>,
+}
+
+impl<'a, T> RefCellDevice<'a, T> {
+    /// Create a new RefCellDevice
+    pub fn new(bus: &'a RefCell<T>) -> Self {
+        Self { bus }
+    }
+}
+
+impl<'a, T> ErrorType for RefCellDevice<'a, T>
+where
+    T: I2c,
+{
+    type Error = T::Error;
+}
+
+impl<'a, T> I2c for RefCellDevice<'a, T>
+where
+    T: I2c,
+{
+    fn read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.borrow_mut();
+        bus.read(address, read)
+    }
+
+    fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.borrow_mut();
+        bus.write(address, write)
+    }
+
+    fn write_read(
+        &mut self,
+        address: u8,
+        write: &[u8],
+        read: &mut [u8],
+    ) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.borrow_mut();
+        bus.write_read(address, write, read)
+    }
+
+    fn transaction(
+        &mut self,
+        address: u8,
+        operations: &mut [embedded_hal::i2c::Operation<'_>],
+    ) -> Result<(), Self::Error> {
+        let bus = &mut *self.bus.borrow_mut();
+        bus.transaction(address, operations)
+    }
+}

embedded-hal-bus/src/lib.rs

@@ -12,6 +12,7 @@
 //! For further details on these traits, please consult the [`embedded-hal` documentation](https://docs.rs/embedded-hal).
 
 #![warn(missing_docs)]
-#![no_std]
+#![cfg_attr(not(feature = "std"), no_std)]
 
+pub mod i2c;
 pub mod spi;