Merge #440

440: I2c: simplify, expand docs, document shared bus usage. r=eldruin a=Dirbaio

~Depends on #441 -- check that one out first.~

This does some simplifications to the trait that I think we should do:

- Implement all methods in terms of `transaction`. This way HALs have to implement just that.
- Removed byte-wise-iteration methods: `write_iter` and `write_iter_read`. The reason is that they're quite inefficient, especially with DMA implementations. We've already removed these on other traits, so I think we should do as well here.
- Removed `transaction_iter`. I don't think it's much useful in practice, because the way iterators work all the yielded `Operation`s must have the same lifetime. This means that, even if the user can generate the `Operation`s on the fly, they can't allocate buffers for these on the fly, all buffers must be pre-allocated. So it's not useful for, say, streaming a large transfer by reusing some small buffer repeatedly. See #367 
- Removed useless lifetimes
- Standardized buffer names on `read` and `write`, I think they're clearer.

It also specifies how i2c bus sharing is supposed to work. This is an alternative to #392 . After the discussions there, I don't think we should split I2C into Bus and Device anymore. For SPI it makes sense, because drivers want to enforce that there's a CS pin (`SpiDevice`) or not (`SpiBus`). This is not the case with I2C, the API is exactly the same in the shared and non-shared case. Drivers shouldn't care which case it is.

So all we have to do to "support" bus sharing is docs, This PR does:

- Document that it's allowed for implementations to be either shared or not.
- Document some guidelines for drivers and HALs on how to best use the traits, expand the examples.


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

Author: bors[bot]

embedded-hal-async/CHANGELOG.md

@@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Changed
 - delay: make infallible.
+- i2c: remove `_iter()` methods.
+- i2c: add default implementations for all methods based on `transaction()`.
 
 ## [v0.2.0-alpha.0] - 2022-11-23
 

embedded-hal-async/src/i2c.rs

@@ -41,7 +41,10 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
-    async fn read<'a>(&'a mut self, address: A, read: &'a mut [u8]) -> Result<(), Self::Error>;
+    async fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
+        self.transaction(address, &mut [Operation::Read(read)])
+            .await
+    }
 
     /// Writes bytes to slave with address `address`
     ///
@@ -59,7 +62,10 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `SAK` = slave acknowledge
     /// - `Bi` = ith byte of data
     /// - `SP` = stop condition
-    async fn write<'a>(&'a mut self, address: A, write: &'a [u8]) -> Result<(), Self::Error>;
+    async fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
+        self.transaction(address, &mut [Operation::Write(write)])
+            .await
+    }
 
     /// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
     /// single transaction*.
@@ -83,12 +89,18 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
-    async fn write_read<'a>(
-        &'a mut self,
+    async fn write_read(
+        &mut self,
         address: A,
-        write: &'a [u8],
-        read: &'a mut [u8],
-    ) -> Result<(), Self::Error>;
+        write: &[u8],
+        read: &mut [u8],
+    ) -> Result<(), Self::Error> {
+        self.transaction(
+            address,
+            &mut [Operation::Write(write), Operation::Read(read)],
+        )
+        .await
+    }
 
     /// Execute the provided operations on the I2C bus as a single transaction.
     ///
@@ -103,35 +115,35 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
     /// - `SR` = repeated start condition
     /// - `SP` = stop condition
-    async fn transaction<'a, 'b>(
-        &'a mut self,
+    async fn transaction(
+        &mut self,
         address: A,
-        operations: &'a mut [Operation<'b>],
+        operations: &mut [Operation<'_>],
     ) -> Result<(), Self::Error>;
 }
 
 impl<A: AddressMode, T: I2c<A>> I2c<A> for &mut T {
-    async fn read<'a>(&'a mut self, address: A, buffer: &'a mut [u8]) -> Result<(), Self::Error> {
-        T::read(self, address, buffer).await
+    async fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
+        T::read(self, address, read).await
     }
 
-    async fn write<'a>(&'a mut self, address: A, bytes: &'a [u8]) -> Result<(), Self::Error> {
-        T::write(self, address, bytes).await
+    async fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
+        T::write(self, address, write).await
     }
 
-    async fn write_read<'a>(
-        &'a mut self,
+    async fn write_read(
+        &mut self,
         address: A,
-        bytes: &'a [u8],
-        buffer: &'a mut [u8],
+        write: &[u8],
+        read: &mut [u8],
     ) -> Result<(), Self::Error> {
-        T::write_read(self, address, bytes, buffer).await
+        T::write_read(self, address, write, read).await
     }
 
-    async fn transaction<'a, 'b>(
-        &'a mut self,
+    async fn transaction(
+        &mut self,
         address: A,
-        operations: &'a mut [Operation<'b>],
+        operations: &mut [Operation<'_>],
     ) -> Result<(), Self::Error> {
         T::transaction(self, address, operations).await
     }

embedded-hal/CHANGELOG.md

@@ -13,6 +13,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 - gpio: add `ErrorKind` enum for consistency with other traits and for future extensibility. No kinds are defined for now.
 - delay: make infallible.
+- i2c: remove `_iter()` methods.
+- i2c: add default implementations for all methods based on `transaction()`.
+- i2c: document guidelines for shared bus usage.
 
 ## [v1.0.0-alpha.9] - 2022-09-28