async: add SPI.

Author: Dirbaio

embedded-hal-async/src/lib.rs

@@ -14,3 +14,4 @@
 pub mod delay;
 pub mod digital;
 pub mod i2c;
+pub mod spi;

embedded-hal-async/src/spi.rs

@@ -0,0 +1,175 @@
+//! Serial Peripheral Interface
+
+use core::future::Future;
+
+pub use embedded_hal::spi::{
+    Error, ErrorKind, ErrorType, Mode, Phase, Polarity, MODE_0, MODE_1, MODE_2, MODE_3,
+};
+
+/// SPI device trait
+///
+/// SpiDevice represents ownership over a single SPI device on a (possibly shared) bus, selected
+/// with a CS pin.
+///
+/// See (the docs on embedded-hal)[embedded_hal::spi::blocking] for important information on SPI Bus vs Device traits.
+pub trait SpiDevice: ErrorType {
+    /// SPI Bus type for this device.
+    type Bus: ErrorType;
+
+    /// Future returned by the `transaction` method.
+    type TransactionFuture<'a, R, F, Fut>: Future<Output = Result<R, Self::Error>> + 'a
+    where
+        Self: 'a,
+        R: 'a,
+        F: FnMut(&'a mut Self::Bus) -> Fut + 'a,
+        Fut: Future<Output = R> + 'a;
+
+    /// Start a transaction against the device.
+    ///
+    /// - Locks the bus
+    /// - Asserts the CS (Chip Select) pin.
+    /// - Calls `f` with an exclusive reference to the bus, which can then be used to do transfers against the device.
+    /// - Deasserts the CS pin.
+    /// - Unlocks the bus,
+    ///
+    /// The lock mechanism is implementation-defined. The only requirement is it must prevent two
+    /// transactions from executing concurrently against the same bus. Examples of implementations are:
+    /// critical sections, blocking mutexes, async mutexes, or returning an error or panicking if the bus is already busy.
+    fn transaction<'a, R, F, Fut>(&'a mut self, f: F) -> Self::TransactionFuture<'a, R, F, Fut>
+    where
+        F: FnMut(&'a mut Self::Bus) -> Fut + 'a,
+        Fut: Future<Output = R> + 'a;
+}
+
+impl<T: SpiDevice> SpiDevice for &mut T {
+    type Bus = T::Bus;
+
+    type TransactionFuture<'a, R, F, Fut>
+    where
+        Self: 'a,
+        R: 'a,
+        F: FnMut(&'a mut Self::Bus) -> Fut + 'a,
+        Fut: Future<Output = R> + 'a,
+    = T::TransactionFuture<'a, R, F, Fut>;
+
+    fn transaction<'a, R, F, Fut>(&'a mut self, f: F) -> Self::TransactionFuture<'a, R, F, Fut>
+    where
+        F: FnMut(&'a mut Self::Bus) -> Fut + 'a,
+        Fut: Future<Output = R> + 'a,
+    {
+        T::transaction(self, f)
+    }
+}
+
+/// Read-only SPI bus
+pub trait SpiBusRead<Word: 'static + Copy = u8>: ErrorType {
+    /// Future returned by the `read` method.
+    type ReadFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Read `words` from the slave.
+    ///
+    /// The word value sent on MOSI during reading is implementation-defined,
+    /// typically `0x00`, `0xFF`, or configurable.
+    fn read<'a>(&'a mut self, words: &'a mut [Word]) -> Self::ReadFuture<'a>;
+}
+
+impl<T: SpiBusRead<Word>, Word: 'static + Copy> SpiBusRead<Word> for &mut T {
+    type ReadFuture<'a>
+    where
+        Self: 'a,
+    = T::ReadFuture<'a>;
+
+    fn read<'a>(&'a mut self, words: &'a mut [Word]) -> Self::ReadFuture<'a> {
+        T::read(self, words)
+    }
+}
+
+/// Write-only SPI
+pub trait SpiBusWrite<Word: 'static + Copy = u8>: ErrorType {
+    /// Future returned by the `write` method.
+    type WriteFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Write `words` to the slave, ignoring all the incoming words
+    fn write<'a>(&'a mut self, words: &'a [Word]) -> Self::WriteFuture<'a>;
+}
+
+impl<T: SpiBusWrite<Word>, Word: 'static + Copy> SpiBusWrite<Word> for &mut T {
+    type WriteFuture<'a>
+    where
+        Self: 'a,
+    = T::WriteFuture<'a>;
+
+    fn write<'a>(&'a mut self, words: &'a [Word]) -> Self::WriteFuture<'a> {
+        T::write(self, words)
+    }
+}
+
+/// Read-write SPI bus
+///
+/// SpiBus represents **exclusive ownership** over the whole SPI bus, with SCK, MOSI and MISO pins.
+///
+/// See the [module-level documentation](self) for important information on SPI Bus vs Device traits.
+pub trait SpiBus<Word: 'static + Copy = u8>: SpiBusRead<Word> + SpiBusWrite<Word> {
+    /// Future returned by the `transfer` method.
+    type TransferFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Write and read 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 transfer<'a>(
+        &'a mut self,
+        read: &'a mut [Word],
+        write: &'a [Word],
+    ) -> Self::TransferFuture<'a>;
+
+    /// Future returned by the `transfer_in_place` method.
+    type TransferInPlaceFuture<'a>: Future<Output = Result<(), Self::Error>> + 'a
+    where
+        Self: 'a;
+
+    /// Write and read 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_in_place<'a>(
+        &'a mut self,
+        words: &'a mut [Word],
+    ) -> Self::TransferInPlaceFuture<'a>;
+}
+
+impl<T: SpiBus<Word>, Word: 'static + Copy> SpiBus<Word> for &mut T {
+    type TransferFuture<'a>
+    where
+        Self: 'a,
+    = T::TransferFuture<'a>;
+
+    fn transfer<'a>(
+        &'a mut self,
+        read: &'a mut [Word],
+        write: &'a [Word],
+    ) -> Self::TransferFuture<'a> {
+        T::transfer(self, read, write)
+    }
+
+    type TransferInPlaceFuture<'a>
+    where
+        Self: 'a,
+    = T::TransferInPlaceFuture<'a>;
+
+    fn transfer_in_place<'a>(
+        &'a mut self,
+        words: &'a mut [Word],
+    ) -> Self::TransferInPlaceFuture<'a> {
+        T::transfer_in_place(self, words)
+    }
+}