Merge #396

396: spi: clarify traits are for master mode. r=eldruin a=Dirbaio

All dirvers out there assume the traitsare for master mode. However, there are some HALs
out there that impl the traits for SPI in slave mode, which will break when used with drivers.
(stm32f1xx-hal, stm32f4xx-hal, stm32l4xx-hal, probably more).

If we add SPI slave traits in the future, they should be a separate set of traits because the
API would look quite different:

- you'd want the API to give extra extra info about the transaction lengths: if you start a transfer with 256-byte buffer but the master only sends 10 bytes (sets CS low, sends 10 bytes, sets CS high),
you'd want `transfer` to return, saying "I got only 10 bytes", instead of hanging waiting for the other 246 bytes.
- The bus/device split doesn't make sense in slave mode.

Also IMO the `spi, spi_slave` naming is fine even if inconsistent, since the vast majority
of uses are master mode. I wouldn't name the `spi` module `spi_master`.

Co-authored-by: Dario Nieuwenhuis <[email protected]>

Author: bors[bot]

embedded-hal-async/src/spi.rs

@@ -1,4 +1,4 @@
-//! Serial Peripheral Interface
+//! SPI master mode traits.
 
 use core::{fmt::Debug, future::Future};
 

src/spi/blocking.rs

@@ -1,4 +1,4 @@
-//! Blocking SPI API
+//! Blocking SPI master mode traits.
 //!
 //! # Bus vs Device
 //!

src/spi/mod.rs

@@ -1,4 +1,4 @@
-//! SPI traits
+//! SPI master mode traits.
 
 pub mod blocking;
 pub mod nb;

src/spi/nb.rs

@@ -1,4 +1,4 @@
-//! Serial Peripheral Interface
+//! SPI master mode traits using `nb`.
 
 use super::ErrorType;