Merge #399

399: SpiDevice: add guidelines for behaviour of CS pin upon bus failures r=eldruin a=newAM

Currently the `SpiDevice` trait does not define the sequence of actions that occur after a bus error.

I discussed this with `@Dirbaio` in the matrix chat and the conclusion we reached was that this should be added to the documentation as a guideline to match what already exists for `ExclusiveDevice`.  The rationale for a guideline instead of a requirement is that SPI error recovery is implementation specific.

Co-authored-by: Alex Martens <[email protected]>

Author: bors[bot]

embedded-hal-async/src/spi.rs

@@ -66,6 +66,9 @@ pub trait SpiDevice: ErrorType {
     /// transactions from executing concurrently against the same bus. Examples of implementations are:
     /// critical sections, blocking mutexes, async mutexes, returning an error or panicking if the bus is already busy.
     ///
+    /// On bus errors the implementation should try to deassert CS.
+    /// If an error occurs while deasserting CS the bus error should take priority as the return value.
+    ///
     /// The current state of the Rust typechecker doesn't allow expressing the necessary lifetime constraints, so
     /// the `f` closure receives a lifetime-less `*mut Bus` raw pointer instead. The pointer is guaranteed
     /// to be valid for the entire duration the closure is running, so dereferencing it is safe.

src/spi/blocking.rs

@@ -195,6 +195,9 @@ pub trait SpiDevice: ErrorType {
     /// 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, returning an error or panicking if the bus is already busy.
+    ///
+    /// On bus errors the implementation should try to deassert CS.
+    /// If an error occurs while deasserting CS the bus error should take priority as the return value.
     fn transaction<R>(
         &mut self,
         f: impl FnOnce(&mut Self::Bus) -> Result<R, <Self::Bus as ErrorType>::Error>,