Skip to content

Commit

Permalink
Merge #230
Browse files Browse the repository at this point in the history 
230: Make I2C compatible with multiple address sizes r=ryankurte a=eldruin

This adds I2C 7-bit and 10-bit address mode compatibility as roughly described [here](#147 (comment)).
Discussion issue: #147 

I have also added the `SevenBitAddress` as the default address mode to the traits so this is not even a breaking change.

Usage broken down per use case:
* **Device driver which only supports 7-bit addressing mode:**
       The driver looks exactly the same as now since the default address mode is 7-bit.

```rust
 impl<I2C, E> MyDriver<I2C>
 where I2C: i2c::Write<Error = E> {
   pub fn do_cool_stuff(&mut self) // ...
 }
 ```

* **Device driver which only supports 10-bit addressing mode:**
       The only difference to a 7-bit-address-only driver is one additional parameter in the I2C trait bound.
```rust
 impl<I2C, E> MyDriver<I2C>
 where I2C: i2c::Write<TenBitAddress, Error = E> {
   pub fn do_cool_stuff(&mut self) // ...
 }
 ```
 
* **Driver for device supporting both addressing modes:**
       Complexity can be abstracted away into additional internal traits which can handle the addressing stuff. Driver code stays clean.
       **This is nothing new**. We already do this on drivers for devices compatible with both I2C and SPI. No need for duplicated code.
       Here a real example: [usage](https://github.com/eldruin/bmi160-rs/blob/3af5637f1df047bb811a4885525cfbe8b44d8ede/src/device_impl.rs#L43), [traits](https://github.com/eldruin/bmi160-rs/blob/master/src/interface.rs)
  
 ```rust
 impl<DI, E> MyDriver<DI>
 where DI: WriteData<Error = E> {
   pub fn do_cool_stuff(&mut self) {} // ...
 }
 
 pub trait WriteData {
 // ...
 }
 
// it is also possible to just leave the `SevenBitAddress` type out here,
// since it is the default.
 impl<I2C, E> WriteData for I2cInterface<I2C, SevenBitAddress>
 where
     I2C: i2c::Write<SevenBitAddress, Error = E>,
 {
   // ...
 }
 
 impl<I2C, E> WriteData for I2cInterface<I2C, TenBitAddress>
 where
     I2C: i2c::Write<TenBitAddress, Error = E>,
 {
   // ...
 }
 ```
 
* **Bus controller impl supporting only 7-bit addressing mode:**
       Code stays almost the same, just adding one addressing mode parameter. Additionally, _if desired_:
    * 10-bit addressing can be software-emulated:
         Emulate by extending and copying payload in separate `TenBitAddress` implementation. Total flexibility to do whatever is necessary in this case since the code is independent.
    * 10-bit addressing cannot be software-emulated:
         Implementation does not offer implementation for `TenBitAddress` variant. The user gets a compilation error and everything is clear.
 
* **Bus controller impl supporting both addressing modes:**
       No problem. Two separate implementations guarantee as much flexibility as necessary. At the same time, sharing generic code is possible.
  
 Additional benefits: 
* No runtime performance cost 
* No runtime switching, duplicated code or panics for unsupported modes. 
* Consistent with what we do for code paths that can be determined statically by the compiler.
* To my taste elegant, simple and very descriptive.

See [here](#147 (comment)) for a comparison to other alternatives.

I have also sealed the trait.

## Proof
* A HAL implementation of both modes: [bitbang-hal](https://github.com/eldruin/bitbang-hal/tree/i2c-multi-address-mode). [code changes](eldruin/bitbang-hal@embedded-hal-1.0.0-alpha.1...eldruin:i2c-multi-address-mode)
* Drivers supporting only 7-bit addresses need **no changes**.
For demonstration purposes, explicitly including the `SevenBitAddress` would look like this: [OPT300x](https://github.com/eldruin/opt300x-rs/tree/i2c-multi-address-mode). [code changes](https://github.com/eldruin/opt300x-rs/compare/i2c-multi-address-mode).
This would be similar to the case of a 10-bit-only device driver.

Co-authored-by: Diego Barrios Romero <eldruin@gmail.com>
  • Loading branch information
@bors @eldruin
bors[bot] and eldruin authored Jul 16, 2020
2 parents d983a3d + d8187c3 commit 83f5bea
Show file tree
Hide file tree
Showing 3 changed files with 135 additions and 13 deletions.
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,15 @@ and this project adheres to [Semantic Versioning](http://semver.org/).

## [Unreleased]

### Added
- 10-bit addressing mode for I2C traits.

### Changed

- I2C addressing modes are now selected via an `AddressMode` type parameter.
The trait features implementations for marker types `SevenBitAddress` and
`TenBitAddress`. `SevenBitAddress` is the default mode so this is not a
breaking change.
- The method `try_write` from the trait `blocking::i2c::WriteIter` trait
has been renamed `try_write_iter` for consistency.
- Updated `nb` dependency to version `1`.
Expand Down
133 changes: 120 additions & 13 deletions src/blocking/i2c.rs
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,119 @@
//! Blocking I2C API
//!
//! Slave addresses used by this API are 7-bit I2C addresses ranging from 0 to 127.
//! This API supports 7-bit and 10-bit addresses. Traits feature an `AddressMode`
//! marker type parameter. Two implementation of the `AddressMode` exist:
//! `SevenBitAddress` and `TenBitAddress`.
//!
//! Operations on 10-bit slave addresses are not supported by the API yet (but applications might
//! be able to emulate some operations).
//! Through this marker types it is possible to implement each address mode for
//! the traits independently in `embedded-hal` implementations and device drivers
//! can depend only on the mode that they support.
//!
//! Additionally, the I2C 10-bit address mode has been developed to be fully
//! backwards compatible with the 7-bit address mode. This allows for a
//! software-emulated 10-bit addressing implementation if the address mode
//! is not supported by the hardware.
//!
//! Since 7-bit addressing is the mode of the majority of I2C devices,
//! `SevenBitAddress` has been set as default mode and thus can be omitted if desired.
//!
//! ## Examples
//!
//! ### `embedded-hal` implementation for an MCU
//! Here is an example of an embedded-hal implementation of the `Write` trait
//! for both modes:
//! ```
//! # use embedded_hal::blocking::i2c::{SevenBitAddress, TenBitAddress, Write};
//! /// I2C0 hardware peripheral which supports both 7-bit and 10-bit addressing.
//! pub struct I2c0;
//!
//! impl Write<SevenBitAddress> for I2c0
//! {
//! # type Error = ();
//! #
//! fn try_write(&mut self, addr: u8, output: &[u8]) -> Result<(), Self::Error> {
//! // ...
//! # Ok(())
//! }
//! }
//!
//! impl Write<TenBitAddress> for I2c0
//! {
//! # type Error = ();
//! #
//! fn try_write(&mut self, addr: u16, output: &[u8]) -> Result<(), Self::Error> {
//! // ...
//! # Ok(())
//! }
//! }
//! ```
//!
//! ### Device driver compatible only with 7-bit addresses
//!
//! For demonstration purposes the address mode parameter has been omitted in this example.
//!
//! ```
//! # use embedded_hal::blocking::i2c::WriteRead;
//! const ADDR: u8 = 0x15;
//! # const TEMP_REGISTER: u8 = 0x1;
//! pub struct TemperatureSensorDriver<I2C> {
//! i2c: I2C,
//! }
//!
//! impl<I2C, E> TemperatureSensorDriver<I2C>
//! where
//! I2C: WriteRead<Error = E>,
//! {
//! pub fn read_temperature(&mut self) -> Result<u8, E> {
//! let mut temp = [0];
//! self.i2c
//! .try_write_read(ADDR, &[TEMP_REGISTER], &mut temp)
//! .and(Ok(temp[0]))
//! }
//! }
//! ```
//!
//! ### Device driver compatible only with 10-bit addresses
//!
//! ```
//! # use embedded_hal::blocking::i2c::{TenBitAddress, WriteRead};
//! const ADDR: u16 = 0x158;
//! # const TEMP_REGISTER: u8 = 0x1;
//! pub struct TemperatureSensorDriver<I2C> {
//! i2c: I2C,
//! }
//!
//! impl<I2C, E> TemperatureSensorDriver<I2C>
//! where
//! I2C: WriteRead<TenBitAddress, Error = E>,
//! {
//! pub fn read_temperature(&mut self) -> Result<u8, E> {
//! let mut temp = [0];
//! self.i2c
//! .try_write_read(ADDR, &[TEMP_REGISTER], &mut temp)
//! .and(Ok(temp[0]))
//! }
//! }
//! ```

use crate::private;

/// Address mode (7-bit / 10-bit)
///
/// Note: This trait is sealed and should not be implemented outside of this crate.
pub trait AddressMode: private::Sealed {}

/// 7-bit address mode type
pub type SevenBitAddress = u8;

/// 10-bit address mode type
pub type TenBitAddress = u16;

impl AddressMode for SevenBitAddress {}

impl AddressMode for TenBitAddress {}

/// Blocking read
pub trait Read {
pub trait Read<A: AddressMode = SevenBitAddress> {
/// Error type
type Error;

Expand All @@ -28,11 +135,11 @@ pub trait Read {
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `SP` = stop condition
fn try_read(&mut self, address: u8, buffer: &mut [u8]) -> Result<(), Self::Error>;
fn try_read(&mut self, address: A, buffer: &mut [u8]) -> Result<(), Self::Error>;
}

/// Blocking write
pub trait Write {
pub trait Write<A: AddressMode = SevenBitAddress> {
/// Error type
type Error;

Expand All @@ -52,11 +159,11 @@ pub trait Write {
/// - `SAK` = slave acknowledge
/// - `Bi` = ith byte of data
/// - `SP` = stop condition
fn try_write(&mut self, address: u8, bytes: &[u8]) -> Result<(), Self::Error>;
fn try_write(&mut self, address: A, bytes: &[u8]) -> Result<(), Self::Error>;
}

/// Blocking write (iterator version)
pub trait WriteIter {
pub trait WriteIter<A: AddressMode = SevenBitAddress> {
/// Error type
type Error;

Expand All @@ -65,13 +172,13 @@ pub trait WriteIter {
/// # I2C Events (contract)
///
/// Same as `Write`
fn try_write_iter<B>(&mut self, address: u8, bytes: B) -> Result<(), Self::Error>
fn try_write_iter<B>(&mut self, address: A, bytes: B) -> Result<(), Self::Error>
where
B: IntoIterator<Item = u8>;
}

/// Blocking write + read
pub trait WriteRead {
pub trait WriteRead<A: AddressMode = SevenBitAddress> {
/// Error type
type Error;

Expand Down Expand Up @@ -99,14 +206,14 @@ pub trait WriteRead {
/// - `SP` = stop condition
fn try_write_read(
&mut self,
address: u8,
address: A,
bytes: &[u8],
buffer: &mut [u8],
) -> Result<(), Self::Error>;
}

/// Blocking write (iterator version) + read
pub trait WriteIterRead {
pub trait WriteIterRead<A: AddressMode = SevenBitAddress> {
/// Error type
type Error;

Expand All @@ -118,7 +225,7 @@ pub trait WriteIterRead {
/// Same as the `WriteRead` trait
fn try_write_iter_read<B>(
&mut self,
address: u8,
address: A,
bytes: B,
buffer: &mut [u8],
) -> Result<(), Self::Error>
Expand Down
8 changes: 8 additions & 0 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -700,3 +700,11 @@ pub mod serial;
pub mod spi;
pub mod timer;
pub mod watchdog;

mod private {
use crate::blocking::i2c::{SevenBitAddress, TenBitAddress};
pub trait Sealed {}

impl Sealed for SevenBitAddress {}
impl Sealed for TenBitAddress {}
}

0 comments on commit 83f5bea

Please sign in to comment.