From 64bdd6424e1a5e97cbd226c731a0fc7a29d9dd2e Mon Sep 17 00:00:00 2001 From: Em Shotton Date: Sun, 25 Aug 2024 19:55:51 -0700 Subject: [PATCH] Update the I2C documentation to use "controller/target" instead of "master/slave" to align with the I2C bus specification v.7 --- embedded-hal-async/src/i2c.rs | 48 +++++++++++++++++------------------ embedded-hal/src/i2c.rs | 48 +++++++++++++++++------------------ 2 files changed, 48 insertions(+), 48 deletions(-) diff --git a/embedded-hal-async/src/i2c.rs b/embedded-hal-async/src/i2c.rs index 86014eec..5c7a7106 100644 --- a/embedded-hal-async/src/i2c.rs +++ b/embedded-hal-async/src/i2c.rs @@ -23,23 +23,23 @@ pub use embedded_hal::i2c::{ /// Async I2c. pub trait I2c: 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> { @@ -47,20 +47,20 @@ pub trait I2c: ErrorType { .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] @@ -69,27 +69,27 @@ pub trait I2c: 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( @@ -108,14 +108,14 @@ pub trait I2c: 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( diff --git a/embedded-hal/src/i2c.rs b/embedded-hal/src/i2c.rs index 36052afa..542866a9 100644 --- a/embedded-hal/src/i2c.rs +++ b/embedded-hal/src/i2c.rs @@ -311,43 +311,43 @@ pub enum Operation<'a> { /// Blocking I2C. pub trait I2c: 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] @@ -355,27 +355,27 @@ pub trait I2c: ErrorType { 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> { @@ -388,14 +388,14 @@ pub trait I2c: 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(