Added ManagedCS marker trait, SpiWithCs wrapper, per #180

Co-authored-by: Diego Barrios Romero <[email protected]>

Author: ryankurte

src/blocking/spi.rs

@@ -1,6 +1,9 @@
 //! Blocking SPI API
 
 /// Blocking transfer
+///
+/// This API provides no ordering guarantees as operations can be interleaved on the bus.
+/// If you need to compose operations use the [Transactional] trait
 pub trait Transfer<W> {
     /// Error type
     type Error;
@@ -10,6 +13,9 @@ pub trait Transfer<W> {
 }
 
 /// Blocking write
+///
+/// This API provides no ordering guarantees as operations can be interleaved on the bus.
+/// If you need to compose operations use the [Transactional] trait
 pub trait Write<W> {
     /// Error type
     type Error;
@@ -19,6 +25,9 @@ pub trait Write<W> {
 }
 
 /// Blocking write (iterator version)
+///
+/// This API provides no ordering guarantees as operations can be interleaved on the bus.
+/// If you need to compose operations use the [Transactional] trait
 pub trait WriteIter<W> {
     /// Error type
     type Error;
@@ -29,6 +38,20 @@ pub trait WriteIter<W> {
         WI: IntoIterator<Item = W>;
 }
 
+/// ManagedCS marker trait indicates the CS pin is managed by the underlying driver.
+///
+/// This specifies that all `spi` operations will be preceded by asserting the CS pin,
+/// and followed by de-asserting the CS pin, prior to returning from the method.
+///
+/// This is important for shared bus access to ensure that only one CS can be asserted
+/// at a given time. Drivers should require this (and not manage their own CS pins)
+/// in order to support shared use.
+///
+/// To chain operations within one transaction see [Transactional].
+/// For or a convenience wrapper defining this type for non-shared / exclusive use
+/// see [`SpiWithCs`](spi_with_cs::SpiWithCs).
+pub trait ManagedCs {}
+
 /// Operation for transactional SPI trait
 ///
 /// This allows composition of SPI operations into a single bus transaction
@@ -41,11 +64,154 @@ pub enum Operation<'a, W: 'static> {
 }
 
 /// Transactional trait allows multiple actions to be executed
-/// as part of a single SPI transaction
+/// as part of a single SPI transaction.
+///
+/// This API guarantees ordering, ensuring operations from
+/// different sources will not be interleaved on a shared bus.
+/// [ManagedCs]
 pub trait Transactional<W: 'static> {
     /// Associated error type
     type Error;
 
     /// Execute the provided transactions
     fn exec<'a>(&mut self, operations: &mut [Operation<'a, W>]) -> Result<(), Self::Error>;
 }
+
+/// Provides SpiWithCS wrapper around an spi::* and OutputPin impl
+pub mod spi_with_cs {
+
+    use core::fmt::Debug;
+    use core::marker::PhantomData;
+
+    use super::{ManagedCs, Transfer, Write, WriteIter};
+    use crate::blocking::digital::OutputPin;
+
+    /// SpiWithCS wraps an blocking::spi* implementation with Chip Select (CS)
+    /// pin management for exclusive (non-shared) use.
+    /// For sharing SPI between peripherals, see [shared-bus](https://crates.io/crates/shared-bus)
+    pub struct SpiWithCs<Spi, SpiError, Pin, PinError> {
+        spi: Spi,
+        cs: Pin,
+
+        _spi_err: PhantomData<SpiError>,
+        _pin_err: PhantomData<PinError>,
+    }
+
+    /// Underlying causes for errors. Either SPI communication or CS pin state setting error
+    #[derive(Clone, Debug, PartialEq)]
+    pub enum SpiWithCsError<SpiError, PinError> {
+        /// Underlying SPI communication error
+        Spi(SpiError),
+        /// Underlying chip-select pin state setting error
+        Pin(PinError),
+    }
+
+    /// ManagedCS marker trait indicates Chip Select management is automatic
+    impl<Spi, SpiError, Pin, PinError> ManagedCs for SpiWithCs<Spi, SpiError, Pin, PinError> {}
+
+    impl<Spi, SpiError, Pin, PinError> SpiWithCs<Spi, SpiError, Pin, PinError>
+    where
+        Pin: crate::blocking::digital::OutputPin<Error = PinError>,
+        SpiError: Debug,
+        PinError: Debug,
+    {
+        /// Create a new SpiWithCS wrapper with the provided Spi and Pin
+        pub fn new(spi: Spi, cs: Pin) -> Self {
+            Self {
+                spi,
+                cs,
+                _spi_err: PhantomData,
+                _pin_err: PhantomData,
+            }
+        }
+
+        /// Fetch references to the inner Spi and Pin types.
+        /// Note that using these directly will violate the `ManagedCs` constraint.
+        pub fn inner(&mut self) -> (&mut Spi, &mut Pin) {
+            (&mut self.spi, &mut self.cs)
+        }
+
+        /// Destroy the SpiWithCs wrapper, returning the bus and pin objects
+        pub fn destroy(self) -> (Spi, Pin) {
+            (self.spi, self.cs)
+        }
+    }
+
+    impl<Spi, SpiError, Pin, PinError> Transfer<u8> for SpiWithCs<Spi, SpiError, Pin, PinError>
+    where
+        Spi: Transfer<u8, Error = SpiError>,
+        Pin: OutputPin<Error = PinError>,
+        SpiError: Debug,
+        PinError: Debug,
+    {
+        type Error = SpiWithCsError<SpiError, PinError>;
+
+        /// Attempt an SPI transfer with automated CS assert/deassert
+        fn transfer<'w>(&mut self, data: &'w mut [u8]) -> Result<&'w [u8], Self::Error> {
+            // First assert CS
+            self.cs.set_low().map_err(SpiWithCsError::Pin)?;
+
+            // Attempt the transfer, storing the result for later
+            let spi_result = self.spi.transfer(data).map_err(SpiWithCsError::Spi);
+
+            // Deassert CS
+            self.cs.set_high().map_err(SpiWithCsError::Pin)?;
+
+            // Return failures
+            spi_result
+        }
+    }
+
+    impl<Spi, SpiError, Pin, PinError> Write<u8> for SpiWithCs<Spi, SpiError, Pin, PinError>
+    where
+        Spi: Write<u8, Error = SpiError>,
+        Pin: OutputPin<Error = PinError>,
+        SpiError: Debug,
+        PinError: Debug,
+    {
+        type Error = SpiWithCsError<SpiError, PinError>;
+
+        /// Attempt an SPI write with automated CS assert/deassert
+        fn write<'w>(&mut self, data: &'w [u8]) -> Result<(), Self::Error> {
+            // First assert CS
+            self.cs.set_low().map_err(SpiWithCsError::Pin)?;
+
+            // Attempt the transfer, storing the result for later
+            let spi_result = self.spi.write(data).map_err(SpiWithCsError::Spi);
+
+            // Deassert CS
+            self.cs.set_high().map_err(SpiWithCsError::Pin)?;
+
+            // Return failures
+            spi_result
+        }
+    }
+
+    impl<Spi, SpiError, Pin, PinError> WriteIter<u8> for SpiWithCs<Spi, SpiError, Pin, PinError>
+    where
+        Spi: WriteIter<u8, Error = SpiError>,
+        Pin: OutputPin<Error = PinError>,
+        SpiError: Debug,
+        PinError: Debug,
+    {
+        type Error = SpiWithCsError<SpiError, PinError>;
+
+        /// Attempt an SPI write_iter with automated CS assert/deassert
+        fn write_iter<WI>(&mut self, words: WI) -> Result<(), Self::Error>
+        where
+            WI: IntoIterator<Item = u8>,
+        {
+            // First assert CS
+            self.cs.set_low().map_err(SpiWithCsError::Pin)?;
+
+            // Attempt the transfer, storing the result for later
+            let spi_result = self.spi.write_iter(words).map_err(SpiWithCsError::Spi);
+
+            // Deassert CS
+            self.cs.set_high().map_err(SpiWithCsError::Pin)?;
+
+            // Return failures
+            spi_result
+        }
+    }
+}