blocking/spi: add Read, ReadWrite, rename Transfer to ReadWriteInplace

Author: Dirbaio

src/blocking/spi.rs

@@ -1,14 +1,30 @@
 //! Blocking SPI API
 
-/// Blocking transfer
-pub trait Transfer<W> {
+/// Blocking simultaneous read+write with separate buffers
+pub trait ReadWrite<W> {
+    /// Error type
+    type Error;
+
+    /// Writes and reads simultaneously. `write` is written to the slave on MOSI and
+    /// words received on MISO are stored in `read`.
+    ///
+    /// It is allowed for `read` and `write` to have different lengths, even zero length.
+    /// The transfer runs for `max(read.len(), write.len())` words. If `read` is shorter,
+    /// incoming words after `read` has been filled will be discarded. If `write` is shorter,
+    /// the value of words sent in MOSI after all `write` has been sent is implementation defined,
+    /// typically `0x00`, `0xFF`, or configurable.
+    fn read_write(&mut self, read: &mut [W], write: &[W]) -> Result<(), Self::Error>;
+}
+
+/// Blocking simultaneous read+write with a single buffer
+pub trait ReadWriteInplace<W> {
     /// Error type
     type Error;
 
     /// Writes and reads simultaneously. The contents of `words` are
     /// written to the slave, and the received words are stored into the same
     /// `words` buffer, overwriting it.
-    fn transfer(&mut self, words: &mut [W]) -> Result<(), Self::Error>;
+    fn read_write_inplace(&mut self, words: &mut [W]) -> Result<(), Self::Error>;
 }
 
 /// Blocking write
@@ -20,6 +36,16 @@ pub trait Write<W> {
     fn write(&mut self, words: &[W]) -> Result<(), Self::Error>;
 }
 
+/// Blocking read
+pub trait Read<W> {
+    /// Error type
+    type Error;
+
+    /// Reads `words` to the slave. The word value sent on MOSI during
+    /// reading is implementation defined, typically `0x00`, `0xFF`, or configurable.
+    fn read(&mut self, words: &mut [W]) -> Result<(), Self::Error>;
+}
+
 /// Blocking write (iterator version)
 pub trait WriteIter<W> {
     /// Error type
@@ -31,20 +57,56 @@ pub trait WriteIter<W> {
         WI: IntoIterator<Item = W>;
 }
 
-/// Blocking transfer
-pub mod transfer {
+/// Blocking simultaneous read+write with separate buffers
+pub mod read_write {
+    /// Default implementation of `blocking::spi::ReadWrite<W>` for implementers of
+    /// `nonblocking::spi::FullDuplex<W>`
+    ///
+    /// If `read` is longer than `write`, `W::default()` (which is typically 0) is sent on MOSI
+    /// to fill the remaining bytes.
+    pub trait Default<W>: crate::nb::spi::FullDuplex<W> {}
+
+    impl<W, S> crate::blocking::spi::ReadWrite<W> for S
+    where
+        S: Default<W>,
+        W: Clone + core::default::Default,
+    {
+        type Error = S::Error;
+
+        fn read_write(&mut self, read: &mut [W], write: &[W]) -> Result<(), S::Error> {
+            for i in 0..core::cmp::max(read.len(), write.len()) {
+                let word_out = if i < write.len() {
+                    write[i].clone()
+                } else {
+                    W::default()
+                };
+                nb::block!(self.write(word_out.clone()))?;
+
+                let word_in = nb::block!(self.read())?;
+                if i < read.len() {
+                    read[i] = word_in;
+                }
+            }
+
+            Ok(())
+        }
+    }
+}
+
+/// Blocking simultaneous read+write with separate buffers
+pub mod read_write_inplace {
     /// Default implementation of `blocking::spi::Transfer<W>` for implementers of
     /// `nonblocking::spi::FullDuplex<W>`
     pub trait Default<W>: crate::nb::spi::FullDuplex<W> {}
 
-    impl<W, S> crate::blocking::spi::Transfer<W> for S
+    impl<W, S> crate::blocking::spi::ReadWriteInplace<W> for S
     where
         S: Default<W>,
         W: Clone,
     {
         type Error = S::Error;
 
-        fn transfer(&mut self, words: &mut [W]) -> Result<(), S::Error> {
+        fn read_write_inplace(&mut self, words: &mut [W]) -> Result<(), S::Error> {
             for word in words.iter_mut() {
                 nb::block!(self.write(word.clone()))?;
                 *word = nb::block!(self.read())?;
@@ -78,6 +140,31 @@ pub mod write {
         }
     }
 }
+/// Blocking write
+pub mod read {
+    /// Default implementation of `blocking::spi::Read<W>` for implementers
+    /// of `nonblocking::spi::FullDuplex<W>`
+    ///
+    /// During the read, `W::default()` (which is typically 0) is sent on MOSI.
+    pub trait Default<W>: crate::nb::spi::FullDuplex<W> {}
+
+    impl<W, S> crate::blocking::spi::Read<W> for S
+    where
+        S: Default<W>,
+        W: core::default::Default,
+    {
+        type Error = S::Error;
+
+        fn read(&mut self, words: &mut [W]) -> Result<(), S::Error> {
+            for word in words.iter_mut() {
+                nb::block!(self.write(W::default()))?;
+                *word = nb::block!(self.read())?;
+            }
+
+            Ok(())
+        }
+    }
+}
 
 /// Blocking write (iterator version)
 pub mod write_iter {
@@ -129,15 +216,15 @@ pub trait Transactional<W: 'static> {
 
 /// Blocking transactional impl over spi::Write and spi::Transfer
 pub mod transactional {
-    use super::{Operation, Transfer, Write};
+    use super::{Operation, ReadWriteInplace, Write};
 
     /// Default implementation of `blocking::spi::Transactional<W>` for implementers of
     /// `spi::Write<W>` and `spi::Transfer<W>`
-    pub trait Default<W>: Write<W> + Transfer<W> {}
+    pub trait Default<W>: Write<W> + ReadWriteInplace<W> {}
 
     impl<W: 'static, E, S> super::Transactional<W> for S
     where
-        S: self::Default<W> + Write<W, Error = E> + Transfer<W, Error = E>,
+        S: self::Default<W> + Write<W, Error = E> + ReadWriteInplace<W, Error = E>,
         W: Copy + Clone,
     {
         type Error = E;
@@ -146,7 +233,7 @@ pub mod transactional {
             for op in operations {
                 match op {
                     Operation::Write(w) => self.write(w)?,
-                    Operation::Transfer(t) => self.transfer(t).map(|_| ())?,
+                    Operation::Transfer(t) => self.read_write_inplace(t).map(|_| ())?,
                 }
             }
 

src/prelude.rs

@@ -22,8 +22,9 @@ pub use crate::blocking::qei::Qei as _embedded_hal_blocking_Qei;
 pub use crate::blocking::rng::Read as _embedded_hal_blocking_rng_Read;
 pub use crate::blocking::serial::Write as _embedded_hal_blocking_serial_Write;
 pub use crate::blocking::spi::{
-    Transfer as _embedded_hal_blocking_spi_Transfer, Write as _embedded_hal_blocking_spi_Write,
-    WriteIter as _embedded_hal_blocking_spi_WriteIter,
+    ReadWrite as _embedded_hal_blocking_spi_ReadWrite,
+    ReadWriteInplace as _embedded_hal_blocking_spi_ReadWriteInplace,
+    Write as _embedded_hal_blocking_spi_Write, WriteIter as _embedded_hal_blocking_spi_WriteIter,
 };
 pub use crate::blocking::watchdog::Disable as _embedded_hal_blocking_watchdog_Disable;
 pub use crate::blocking::watchdog::Enable as _embedded_hal_blocking_watchdog_Enable;