Skip to content

Commit

Permalink
Update the I2C documentation to use "controller/target" instead of "m…
Browse files Browse the repository at this point in the history 
…aster/slave" to align with the I2C bus specification v.7
  • Loading branch information
Em Shotton committed Aug 26, 2024
1 parent bbd5803 commit 64bdd64
Show file tree
Hide file tree
Showing 2 changed files with 48 additions and 48 deletions.
48 changes: 24 additions & 24 deletions embedded-hal-async/src/i2c.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,44 +23,44 @@ pub use embedded_hal::i2c::{

/// Async I2c.
pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Reads enough bytes from slave with `address` to fill `buffer`.
/// Reads enough bytes from target with `address` to fill `buffer`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+R MAK MAK ... NMAK SP
/// Slave: SAK B0 B1 ... BN
/// Controller: ST TAD+R CAK CAK ... NCAK SP
/// Target: TAK B0 B1 ... BN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `SAK` = slave acknowledge
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
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`.
/// Writes bytes to target with address `address`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W B0 B1 ... BN SP
/// Slave: SAK SAK SAK ... SAK
/// Controller: ST TAD+W B0 B1 ... BN SP
/// Target: TAK TAK TAK ... TAK
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `SP` = stop condition
#[inline]
Expand All @@ -69,27 +69,27 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
.await
}

/// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
/// Writes bytes to target with address `address` and then reads enough bytes to fill `read` *in a
/// single transaction*.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W O0 O1 ... OM SR SAD+R MAK MAK ... NMAK SP
/// Slave: SAK SAK SAK ... SAK SAK I0 I1 ... IN
/// Controller: ST TAD+W O0 O1 ... OM SR TAD+R CAK CAK ... NCAK SP
/// Target: TAK TAK TAK ... TAK TAK I0 I1 ... IN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Oi` = ith outgoing byte of data
/// - `SR` = repeated start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `Ii` = ith incoming byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
async fn write_read(
Expand All @@ -108,14 +108,14 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Execute the provided operations on the I2C bus as a single transaction.
///
/// Transaction contract:
/// - Before executing the first operation an ST is sent automatically. This is followed by SAD+R/W as appropriate.
/// - Before executing the first operation an ST is sent automatically. This is followed by TAD+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.
/// - Between adjacent operations of a different type an SR and TAD+R/W is sent.
/// - After executing the last operation an SP is sent automatically.
/// - At the end of each read operation (before SP or SR), the master does not send an acknowledge for the last byte.
/// - At the end of each read operation (before SP or SR), the controller 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
/// - `TAD+R/W` = target address followed by bit 1 to indicate reading or 0 to indicate writing
/// - `SR` = repeated start condition
/// - `SP` = stop condition
async fn transaction(
Expand Down
48 changes: 24 additions & 24 deletions embedded-hal/src/i2c.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -311,71 +311,71 @@ pub enum Operation<'a> {

/// Blocking I2C.
pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// Reads enough bytes from slave with `address` to fill `read`.
/// Reads enough bytes from target with `address` to fill `read`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+R MAK MAK ... NMAK SP
/// Slave: SAK B0 B1 ... BN
/// Controller: ST TAD+R CAK CAK ... NCAK SP
/// Target: TAK B0 B1 ... BN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `SAK` = slave acknowledge
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
self.transaction(address, &mut [Operation::Read(read)])
}

/// Writes bytes to slave with address `address`.
/// Writes bytes to target with address `address`.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W B0 B1 ... BN SP
/// Slave: SAK SAK SAK ... SAK
/// Controller: ST TAD+W B0 B1 ... BN SP
/// Target: TAK TAK TAK ... TAK
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Bi` = ith byte of data
/// - `SP` = stop condition
#[inline]
fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
self.transaction(address, &mut [Operation::Write(write)])
}

/// Writes bytes to slave with address `address` and then reads enough bytes to fill `read` *in a
/// Writes bytes to target with address `address` and then reads enough bytes to fill `read` *in a
/// single transaction*.
///
/// # I2C Events (contract)
///
/// ``` text
/// Master: ST SAD+W O0 O1 ... OM SR SAD+R MAK MAK ... NMAK SP
/// Slave: SAK SAK SAK ... SAK SAK I0 I1 ... IN
/// Controller: ST TAD+W O0 O1 ... OM SR TAD+R CAK CAK ... NCAK SP
/// Target: TAK TAK TAK ... TAK TAK I0 I1 ... IN
/// ```
///
/// Where
///
/// - `ST` = start condition
/// - `SAD+W` = slave address followed by bit 0 to indicate writing
/// - `SAK` = slave acknowledge
/// - `TAD+W` = target address followed by bit 0 to indicate writing
/// - `TAK` = target acknowledge
/// - `Oi` = ith outgoing byte of data
/// - `SR` = repeated start condition
/// - `SAD+R` = slave address followed by bit 1 to indicate reading
/// - `TAD+R` = target address followed by bit 1 to indicate reading
/// - `Ii` = ith incoming byte of data
/// - `MAK` = master acknowledge
/// - `NMAK` = master no acknowledge
/// - `CAK` = controller acknowledge
/// - `NCAK` = controller no acknowledge
/// - `SP` = stop condition
#[inline]
fn write_read(&mut self, address: A, write: &[u8], read: &mut [u8]) -> Result<(), Self::Error> {
Expand All @@ -388,14 +388,14 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
/// 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.
/// - Before executing the first operation an ST is sent automatically. This is followed by TAD+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.
/// - Between adjacent operations of a different type an SR and TAD+R/W is sent.
/// - After executing the last operation an SP is sent automatically.
/// - At the end of each read operation (before SP or SR), the master does not send an acknowledge for the last byte.
/// - At the end of each read operation (before SP or SR), the controller 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
/// - `TAD+R/W` = target address followed by bit 1 to indicate reading or 0 to indicate writing
/// - `SR` = repeated start condition
/// - `SP` = stop condition
fn transaction(
Expand Down

0 comments on commit 64bdd64

Please sign in to comment.