bus/spi: 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
+- spi: 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/lib.rs

@@ -12,6 +12,6 @@
 //! 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 spi;

embedded-hal-bus/src/spi.rs

@@ -0,0 +1,133 @@
+use core::cell::RefCell;
+use critical_section::Mutex;
+use embedded_hal::digital::OutputPin;
+use embedded_hal::spi::{
+    ErrorType, Operation, SpiBus, SpiBusRead, SpiBusWrite, SpiDevice, SpiDeviceRead, SpiDeviceWrite,
+};
+
+use super::DeviceError;
+
+/// `critical-section`-based shared bus [`SpiDevice`] implementation.
+///
+/// This allows for sharing an [`SpiBus`](embedded_hal::spi::blocking::SpiBus), obtaining multiple [`SpiDevice`] instances,
+/// each with its own `CS` pin.
+///
+/// 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, BUS, CS> {
+    bus: &'a Mutex<RefCell<BUS>>,
+    cs: CS,
+}
+
+impl<'a, BUS, CS> CriticalSectionDevice<'a, BUS, CS> {
+    /// Create a new ExclusiveDevice
+    pub fn new(bus: &'a Mutex<RefCell<BUS>>, cs: CS) -> Self {
+        Self { bus, cs }
+    }
+}
+
+impl<'a, BUS, CS> ErrorType for CriticalSectionDevice<'a, BUS, CS>
+where
+    BUS: ErrorType,
+    CS: OutputPin,
+{
+    type Error = DeviceError<BUS::Error, CS::Error>;
+}
+
+impl<'a, Word: Copy + 'static, BUS, CS> SpiDeviceRead<Word> for CriticalSectionDevice<'a, BUS, CS>
+where
+    BUS: SpiBusRead<Word>,
+    CS: OutputPin,
+{
+    fn read_transaction(&mut self, operations: &mut [&mut [Word]]) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+
+            self.cs.set_low().map_err(DeviceError::Cs)?;
+
+            let mut op_res = Ok(());
+            for buf in operations {
+                if let Err(e) = bus.read(buf) {
+                    op_res = Err(e);
+                    break;
+                }
+            }
+
+            // On failure, it's important to still flush and deassert CS.
+            let flush_res = bus.flush();
+            let cs_res = self.cs.set_high();
+
+            op_res.map_err(DeviceError::Spi)?;
+            flush_res.map_err(DeviceError::Spi)?;
+            cs_res.map_err(DeviceError::Cs)?;
+
+            Ok(())
+        })
+    }
+}
+
+impl<'a, Word: Copy + 'static, BUS, CS> SpiDeviceWrite<Word> for CriticalSectionDevice<'a, BUS, CS>
+where
+    BUS: SpiBusWrite<Word>,
+    CS: OutputPin,
+{
+    fn write_transaction(&mut self, operations: &[&[Word]]) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+
+            self.cs.set_low().map_err(DeviceError::Cs)?;
+
+            let mut op_res = Ok(());
+            for buf in operations {
+                if let Err(e) = bus.write(buf) {
+                    op_res = Err(e);
+                    break;
+                }
+            }
+
+            // On failure, it's important to still flush and deassert CS.
+            let flush_res = bus.flush();
+            let cs_res = self.cs.set_high();
+
+            op_res.map_err(DeviceError::Spi)?;
+            flush_res.map_err(DeviceError::Spi)?;
+            cs_res.map_err(DeviceError::Cs)?;
+
+            Ok(())
+        })
+    }
+}
+
+impl<'a, Word: Copy + 'static, BUS, CS> SpiDevice<Word> for CriticalSectionDevice<'a, BUS, CS>
+where
+    BUS: SpiBus<Word>,
+    CS: OutputPin,
+{
+    fn transaction(&mut self, operations: &mut [Operation<'_, Word>]) -> Result<(), Self::Error> {
+        critical_section::with(|cs| {
+            let bus = &mut *self.bus.borrow_ref_mut(cs);
+
+            self.cs.set_low().map_err(DeviceError::Cs)?;
+
+            let op_res = operations.iter_mut().try_for_each(|op| match op {
+                Operation::Read(buf) => bus.read(buf),
+                Operation::Write(buf) => bus.write(buf),
+                Operation::Transfer(read, write) => bus.transfer(read, write),
+                Operation::TransferInPlace(buf) => bus.transfer_in_place(buf),
+            });
+
+            // On failure, it's important to still flush and deassert CS.
+            let flush_res = bus.flush();
+            let cs_res = self.cs.set_high();
+
+            op_res.map_err(DeviceError::Spi)?;
+            flush_res.map_err(DeviceError::Spi)?;
+            cs_res.map_err(DeviceError::Cs)?;
+
+            Ok(())
+        })
+    }
+}