diff --git a/embedded-hal-async/src/spi.rs b/embedded-hal-async/src/spi.rs index a1cd90df1..c6f4c13a1 100644 --- a/embedded-hal-async/src/spi.rs +++ b/embedded-hal-async/src/spi.rs @@ -9,8 +9,8 @@ use embedded_hal::{digital::blocking::OutputPin, spi::blocking}; /// SPI device trait /// -/// SpiDevice represents ownership over a single SPI device on a (possibly shared) bus, selected -/// with a CS pin. +/// `SpiDevice` represents ownership over a single SPI device on a (possibly shared) bus, selected +/// with a CS (Chip Select) pin. /// /// See (the docs on embedded-hal)[embedded_hal::spi::blocking] for important information on SPI Bus vs Device traits. pub trait SpiDevice: ErrorType { @@ -30,17 +30,18 @@ pub trait SpiDevice: ErrorType { ), > + 'a; - /// Start a transaction against the device. + /// Perform 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. + /// - [Flushes](SpiBusFlush::flush) the bus. /// - Deasserts the CS pin. - /// - Unlocks the bus, + /// - Unlocks the bus. /// - /// The lock mechanism is implementation-defined. The only requirement is it must prevent two + /// The locking 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. + /// critical sections, blocking mutexes, async mutexes, 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: FnOnce(&'a mut Self::Bus) -> Fut + 'a, @@ -74,14 +75,16 @@ impl SpiDevice for &mut T { } } -/// Flush for SPI bus +/// Flush support for SPI bus pub trait SpiBusFlush: ErrorType { /// Future returned by the `flush` method. type FlushFuture<'a>: Future> + 'a where Self: 'a; - /// Flush + /// Wait until all operations have completed and the bus is idle. + /// + /// See (the docs on embedded-hal)[embedded_hal::spi::blocking] for information on flushing. fn flush<'a>(&'a mut self) -> Self::FlushFuture<'a>; } @@ -104,6 +107,9 @@ pub trait SpiBusRead: SpiBusFlush { /// /// The word value sent on MOSI during reading is implementation-defined, /// typically `0x00`, `0xFF`, or configurable. + /// + /// Implementations are allowed to return before the operation is + /// complete. See (the docs on embedded-hal)[embedded_hal::spi::blocking] for details on flushing. fn read<'a>(&'a mut self, words: &'a mut [Word]) -> Self::ReadFuture<'a>; } @@ -123,6 +129,9 @@ pub trait SpiBusWrite: SpiBusFlush { Self: 'a; /// Write `words` to the slave, ignoring all the incoming words + /// + /// Implementations are allowed to return before the operation is + /// complete. See (the docs on embedded-hal)[embedded_hal::spi::blocking] for details on flushing. fn write<'a>(&'a mut self, words: &'a [Word]) -> Self::WriteFuture<'a>; } @@ -136,7 +145,7 @@ impl, Word: 'static + Copy> SpiBusWrite for &mut T { /// Read-write SPI bus /// -/// SpiBus represents **exclusive ownership** over the whole SPI bus, with SCK, MOSI and MISO pins. +/// `SpiBus` represents **exclusive ownership** over the whole SPI bus, with SCK, MOSI and MISO pins. /// /// See (the docs on embedded-hal)[embedded_hal::spi::blocking] for important information on SPI Bus vs Device traits. pub trait SpiBus: SpiBusRead + SpiBusWrite { @@ -153,6 +162,9 @@ pub trait SpiBus: SpiBusRead + SpiBusWrite( &'a mut self, read: &'a mut [Word], @@ -167,6 +179,9 @@ pub trait SpiBus: SpiBusRead + SpiBusWrite( &'a mut self, words: &'a mut [Word], diff --git a/src/spi/blocking.rs b/src/spi/blocking.rs index 4d16cbe1c..80d611e4f 100644 --- a/src/spi/blocking.rs +++ b/src/spi/blocking.rs @@ -175,8 +175,8 @@ use super::{Error, ErrorKind}; /// SPI device trait /// -/// SpiDevice represents ownership over a single SPI device on a (possibly shared) bus, selected -/// with a CS pin. +/// `SpiDevice` represents ownership over a single SPI device on a (possibly shared) bus, selected +/// with a CS (Chip Select) pin. /// /// See the [module-level documentation](self) for important usage information. pub trait SpiDevice: ErrorType { @@ -192,9 +192,9 @@ pub trait SpiDevice: ErrorType { /// - Deasserts the CS pin. /// - Unlocks the bus. /// - /// The lock mechanism is implementation-defined. The only requirement is it must prevent two + /// The locking 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, or returning an error or panicking if the bus is already busy. + /// critical sections, blocking mutexes, returning an error or panicking if the bus is already busy. fn transaction( &mut self, f: impl FnOnce(&mut Self::Bus) -> Result::Error>, @@ -265,7 +265,7 @@ impl SpiDevice for &mut T { /// Flush support for SPI bus pub trait SpiBusFlush: ErrorType { - /// Blocks until all operations have completed and the bus is idle. + /// Wait until all operations have completed and the bus is idle. /// /// See the [module-level documentation](self) for important usage information. fn flush(&mut self) -> Result<(), Self::Error>; @@ -279,7 +279,7 @@ impl SpiBusFlush for &mut T { /// Read-only SPI bus pub trait SpiBusRead: SpiBusFlush { - /// Reads `words` from the slave. + /// Read `words` from the slave. /// /// The word value sent on MOSI during reading is implementation-defined, /// typically `0x00`, `0xFF`, or configurable. @@ -297,7 +297,7 @@ impl, Word: Copy> SpiBusRead for &mut T { /// Write-only SPI bus pub trait SpiBusWrite: SpiBusFlush { - /// Writes `words` to the slave, ignoring all the incoming words + /// Write `words` to the slave, ignoring all the incoming words /// /// Implementations are allowed to return before the operation is /// complete. See the [module-level documentation](self) for details. @@ -312,11 +312,11 @@ impl, Word: Copy> SpiBusWrite for &mut T { /// Read-write SPI bus /// -/// SpiBus represents **exclusive ownership** over the whole SPI bus, with SCK, MOSI and MISO pins. +/// `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: SpiBusRead + SpiBusWrite { - /// Writes and reads simultaneously. `write` is written to the slave on MOSI and + /// 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. @@ -329,7 +329,7 @@ pub trait SpiBus: SpiBusRead + SpiBusWrite { /// complete. See the [module-level documentation](self) for details. fn transfer(&mut self, read: &mut [Word], write: &[Word]) -> Result<(), Self::Error>; - /// Writes and reads simultaneously. The contents of `words` are + /// 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. /// @@ -388,7 +388,7 @@ impl ExclusiveDevice { impl ErrorType for ExclusiveDevice where - BUS: SpiBusFlush, + BUS: ErrorType, CS: OutputPin, { type Error = ExclusiveDeviceError;