Merge #223

223: Add transactional I2C interface r=therealprof a=eldruin

An example where a transactional I2C interface would be an improvement is when facing the problem of sending an array of data where the first item is the destination address.
At the moment this requires copying the data into a bigger array and assigning the first item to the address. With a transactional I2C two `write` operations could be chained into one transaction so that it is possible to send the address and data without an extra copy.
This is specially problematic if the data length is unknown e.g. because it comes from the user.

You can see the problem [here in the eeprom24x driver](https://github.com/eldruin/eeprom24x-rs/blob/f75770c6fc6dd8d591e3695908d5ef4ce8642566/src/eeprom24x.rs#L220). In this case I am lucky enough to have the page upper limit so that the copy workaround is possible.

With this PR a bunch of code and macros could be replaced by doing something similar to this:
```rust
let user_data = [0x12, 0x34, ...]; // defined somewhere else. length may be unknown.
let target_address = 0xAB;
let mut ops = [
  Operation::Write(&[target_address]),
  Operation::Write(&user_data),
];
i2cdev.try_exec(DEV_ADDR, &ops)
```

I added a PoC [here in linux-embedded-hal](https://github.com/eldruin/linux-embedded-hal/blob/7512dbcc09faa58344a5058baab8826a0e0d0160/src/lib.rs#L211) including [an example](https://github.com/eldruin/linux-embedded-hal/blob/transactional-i2c/examples/transactional-i2c.rs) of a driver where a classical combined write/read is performed through the transactional interface.

Note: A default implementation of the `Transactional` trait like in #191 is not possible because STOPs would always be sent after each operation. What is possible is to do is the other way around. This includes an implementation of the `Write`, `Read` and `WriteRead` traits for `Transactional` implementers.

This is based on previous work from #178 by @ryankurte and it is similar to #191 

TODO:
- [x] Add changelog entry

Co-authored-by: Diego Barrios Romero <[email protected]>

Author: bors[bot]

CHANGELOG.md

@@ -8,7 +8,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ## [Unreleased]
 
 ### Added
-- `Transactional` SPI interface for executing groups of SPI transactions
+- `Transactional` SPI interface for executing groups of SPI transactions.
+- `Transactional` I2C interface for executing groups of I2C transactions.
 
 ### Changed
 
@@ -20,7 +21,6 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - 10-bit addressing mode for I2C traits.
 - `try_set_state` method for `OutputPin` using an input `PinState` value.
-- `Transactional` interface for grouping SPI transactions
 
 ### Changed
 

src/blocking/i2c.rs

@@ -232,3 +232,117 @@ pub trait WriteIterRead<A: AddressMode = SevenBitAddress> {
     where
         B: IntoIterator<Item = u8>;
 }
+
+/// Transactional I2C operation.
+///
+/// Several operations can be combined as part of a transaction.
+#[derive(Debug, PartialEq)]
+pub enum Operation<'a> {
+    /// Read data into the provided buffer
+    Read(&'a mut [u8]),
+    /// Write data from the provided buffer
+    Write(&'a [u8]),
+}
+
+/// Transactional I2C interface.
+///
+/// This allows combining operations within an I2C transaction.
+pub trait Transactional {
+    /// Error type
+    type Error;
+
+    /// Execute the provided operations on the I2C bus.
+    ///
+    /// Transaction contract:
+    /// - Before executing the first operation an ST is sent automatically. This is followed by SAD+R/W as appropriate.
+    /// - Data from adjacent operations of the same type are sent after each other without an SP or SR.
+    /// - Between adjacent operations of a different type an SR and SAD+R/W is sent.
+    /// - After executing the last operation an SP is sent automatically.
+    /// - If the last operation is a `Read` the master does not send an acknowledge for the last byte.
+    ///
+    /// - `ST` = start condition
+    /// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
+    /// - `SR` = repeated start condition
+    /// - `SP` = stop condition
+    fn try_exec<'a>(
+        &mut self,
+        address: u8,
+        operations: &mut [Operation<'a>],
+    ) -> Result<(), Self::Error>;
+}
+
+/// Transactional I2C interface (iterator version).
+///
+/// This allows combining operation within an I2C transaction.
+pub trait TransactionalIter {
+    /// Error type
+    type Error;
+
+    /// Execute the provided operations on the I2C bus (iterator version).
+    ///
+    /// Transaction contract:
+    /// - Before executing the first operation an ST is sent automatically. This is followed by SAD+R/W as appropriate.
+    /// - Data from adjacent operations of the same type are sent after each other without an SP or SR.
+    /// - Between adjacent operations of a different type an SR and SAD+R/W is sent.
+    /// - After executing the last operation an SP is sent automatically.
+    /// - If the last operation is a `Read` the master does not send an acknowledge for the last byte.
+    ///
+    /// - `ST` = start condition
+    /// - `SAD+R/W` = slave address followed by bit 1 to indicate reading or 0 to indicate writing
+    /// - `SR` = repeated start condition
+    /// - `SP` = stop condition
+    fn try_exec_iter<'a, O>(&mut self, address: u8, operations: O) -> Result<(), Self::Error>
+    where
+        O: IntoIterator<Item = Operation<'a>>;
+}
+
+/// Default implementation of `blocking::i2c::Write`, `blocking::i2c::Read` and
+/// `blocking::i2c::WriteRead` traits for `blocking::i2c::Transactional` implementers.
+pub mod transactional {
+    use super::{Operation, Read, Transactional, Write, WriteRead};
+
+    /// Default implementation of `blocking::i2c::Write`, `blocking::i2c::Read` and
+    /// `blocking::i2c::WriteRead` traits for `blocking::i2c::Transactional` implementers.
+    pub trait Default<E> {}
+
+    impl<E, S> Write for S
+    where
+        S: self::Default<E> + Transactional<Error = E>,
+    {
+        type Error = E;
+
+        fn try_write(&mut self, address: u8, bytes: &[u8]) -> Result<(), Self::Error> {
+            self.try_exec(address, &mut [Operation::Write(bytes)])
+        }
+    }
+
+    impl<E, S> Read for S
+    where
+        S: self::Default<E> + Transactional<Error = E>,
+    {
+        type Error = E;
+
+        fn try_read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Self::Error> {
+            self.try_exec(address, &mut [Operation::Read(buffer)])
+        }
+    }
+
+    impl<E, S> WriteRead for S
+    where
+        S: self::Default<E> + Transactional<Error = E>,
+    {
+        type Error = E;
+
+        fn try_write_read(
+            &mut self,
+            address: u8,
+            bytes: &[u8],
+            buffer: &mut [u8],
+        ) -> Result<(), Self::Error> {
+            self.try_exec(
+                address,
+                &mut [Operation::Write(bytes), Operation::Read(buffer)],
+            )
+        }
+    }
+}

src/prelude.rs

@@ -8,8 +8,9 @@ pub use crate::adc::OneShot as _embedded_hal_adc_OneShot;
 pub use crate::blocking::delay::DelayMs as _embedded_hal_blocking_delay_DelayMs;
 pub use crate::blocking::delay::DelayUs as _embedded_hal_blocking_delay_DelayUs;
 pub use crate::blocking::i2c::{
-    Read as _embedded_hal_blocking_i2c_Read, Write as _embedded_hal_blocking_i2c_Write,
-    WriteIter as _embedded_hal_blocking_i2c_WriteIter,
+    Read as _embedded_hal_blocking_i2c_Read,
+    Transactional as _embedded_hal_blocking_i2c_Transactional,
+    Write as _embedded_hal_blocking_i2c_Write, WriteIter as _embedded_hal_blocking_i2c_WriteIter,
     WriteIterRead as _embedded_hal_blocking_i2c_WriteIterRead,
     WriteRead as _embedded_hal_blocking_i2c_WriteRead,
 };