Merge pull request #488 from luojia65/luojia65/1.0.0-fixes

lib: amend documents to add periods (.), add inline hints when necessary
rust-embedded · Aug 23, 2023 · 35e6012 · 35e6012
2 parents 9228fb2 + d2f099e
commit 35e6012
Show file tree

Hide file tree

Showing 23 changed files with 235 additions and 104 deletions.
diff --git a/embedded-hal-async/CHANGELOG.md b/embedded-hal-async/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+- Minor document fixes.
+- Add #[inline] hints to most of `embedded-hal-async` functions.
+
 ## [v1.0.0-rc.1] - 2023-08-15
 
 - Updated `embedded-hal` to version `1.0.0-rc.1`.

diff --git a/embedded-hal-async/src/delay.rs b/embedded-hal-async/src/delay.rs
@@ -1,6 +1,6 @@
-//! Delays
+//! Delays.
 
-/// Microsecond delay
+/// Microsecond delay.
 pub trait DelayUs {
     /// Pauses execution for at minimum `us` microseconds. Pause can be longer
     /// if the implementation requires it due to precision/timing issues.
@@ -15,10 +15,12 @@ impl<T> DelayUs for &mut T
 where
     T: DelayUs + ?Sized,
 {
+    #[inline]
     async fn delay_us(&mut self, us: u32) {
         T::delay_us(self, us).await
     }
 
+    #[inline]
     async fn delay_ms(&mut self, ms: u32) {
         T::delay_ms(self, ms).await
     }

diff --git a/embedded-hal-async/src/digital.rs b/embedded-hal-async/src/digital.rs
@@ -1,4 +1,4 @@
-//! Asynchronous digital I/O
+//! Asynchronous digital I/O.
 //!
 //! # Example
 //!
@@ -49,22 +49,27 @@ pub trait Wait: embedded_hal::digital::ErrorType {
 }
 
 impl<T: Wait + ?Sized> Wait for &mut T {
+    #[inline]
     async fn wait_for_high(&mut self) -> Result<(), Self::Error> {
         T::wait_for_high(self).await
     }
 
+    #[inline]
     async fn wait_for_low(&mut self) -> Result<(), Self::Error> {
         T::wait_for_low(self).await
     }
 
+    #[inline]
     async fn wait_for_rising_edge(&mut self) -> Result<(), Self::Error> {
         T::wait_for_rising_edge(self).await
     }
 
+    #[inline]
     async fn wait_for_falling_edge(&mut self) -> Result<(), Self::Error> {
         T::wait_for_falling_edge(self).await
     }
 
+    #[inline]
     async fn wait_for_any_edge(&mut self) -> Result<(), Self::Error> {
         T::wait_for_any_edge(self).await
     }

diff --git a/embedded-hal-async/src/i2c.rs b/embedded-hal-async/src/i2c.rs
@@ -1,4 +1,4 @@
-//! Async I2C API
+//! Async I2C API.
 //!
 //! This API supports 7-bit and 10-bit addresses. Traits feature an `AddressMode`
 //! marker type parameter. Two implementation of the `AddressMode` exist:
@@ -21,9 +21,9 @@ pub use embedded_hal::i2c::{
     AddressMode, Error, ErrorKind, ErrorType, NoAcknowledgeSource, SevenBitAddress, TenBitAddress,
 };
 
-/// Async i2c
+/// Async I2c.
 pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
-    /// Reads enough bytes from slave with `address` to fill `buffer`
+    /// Reads enough bytes from slave with `address` to fill `buffer`.
     ///
     /// # I2C Events (contract)
     ///
@@ -41,12 +41,13 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master 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 slave with address `address`.
     ///
     /// # I2C Events (contract)
     ///
@@ -62,6 +63,7 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `SAK` = slave acknowledge
     /// - `Bi` = ith byte of data
     /// - `SP` = stop condition
+    #[inline]
     async fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
         self.transaction(address, &mut [Operation::Write(write)])
             .await
@@ -89,6 +91,7 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
     /// - `MAK` = master acknowledge
     /// - `NMAK` = master no acknowledge
     /// - `SP` = stop condition
+    #[inline]
     async fn write_read(
         &mut self,
         address: A,
@@ -123,14 +126,17 @@ pub trait I2c<A: AddressMode = SevenBitAddress>: ErrorType {
 }
 
 impl<A: AddressMode, T: I2c<A> + ?Sized> I2c<A> for &mut T {
+    #[inline]
     async fn read(&mut self, address: A, read: &mut [u8]) -> Result<(), Self::Error> {
         T::read(self, address, read).await
     }
 
+    #[inline]
     async fn write(&mut self, address: A, write: &[u8]) -> Result<(), Self::Error> {
         T::write(self, address, write).await
     }
 
+    #[inline]
     async fn write_read(
         &mut self,
         address: A,
@@ -140,6 +146,7 @@ impl<A: AddressMode, T: I2c<A> + ?Sized> I2c<A> for &mut T {
         T::write_read(self, address, write, read).await
     }
 
+    #[inline]
     async fn transaction(
         &mut self,
         address: A,

diff --git a/embedded-hal-async/src/spi.rs b/embedded-hal-async/src/spi.rs
@@ -4,7 +4,7 @@ pub use embedded_hal::spi::{
     Error, ErrorKind, ErrorType, Mode, Operation, Phase, Polarity, MODE_0, MODE_1, MODE_2, MODE_3,
 };
 
-/// SPI device trait
+/// SPI device trait.
 ///
 /// `SpiDevice` represents ownership over a single SPI device on a (possibly shared) bus, selected
 /// with a CS (Chip Select) pin.
@@ -36,6 +36,7 @@ pub trait SpiDevice<Word: Copy + 'static = u8>: ErrorType {
     /// This is a convenience method equivalent to `device.read_transaction(&mut [buf])`.
     ///
     /// See also: [`SpiDevice::transaction`], [`SpiDevice::read`]
+    #[inline]
     async fn read(&mut self, buf: &mut [Word]) -> Result<(), Self::Error> {
         self.transaction(&mut [Operation::Read(buf)]).await
     }
@@ -45,6 +46,7 @@ pub trait SpiDevice<Word: Copy + 'static = u8>: ErrorType {
     /// This is a convenience method equivalent to `device.write_transaction(&mut [buf])`.
     ///
     /// See also: [`SpiDevice::transaction`], [`SpiDevice::write`]
+    #[inline]
     async fn write(&mut self, buf: &[Word]) -> Result<(), Self::Error> {
         self.transaction(&mut [Operation::Write(buf)]).await
     }
@@ -54,6 +56,7 @@ pub trait SpiDevice<Word: Copy + 'static = u8>: ErrorType {
     /// This is a convenience method equivalent to `device.transaction(|bus| bus.transfer(read, write))`.
     ///
     /// See also: [`SpiDevice::transaction`], [`SpiBus::transfer`]
+    #[inline]
     async fn transfer(&mut self, read: &mut [Word], write: &[Word]) -> Result<(), Self::Error> {
         self.transaction(&mut [Operation::Transfer(read, write)])
             .await
@@ -64,38 +67,44 @@ pub trait SpiDevice<Word: Copy + 'static = u8>: ErrorType {
     /// This is a convenience method equivalent to `device.transaction(|bus| bus.transfer_in_place(buf))`.
     ///
     /// See also: [`SpiDevice::transaction`], [`SpiBus::transfer_in_place`]
+    #[inline]
     async fn transfer_in_place(&mut self, buf: &mut [Word]) -> Result<(), Self::Error> {
         self.transaction(&mut [Operation::TransferInPlace(buf)])
             .await
     }
 }
 
 impl<Word: Copy + 'static, T: SpiDevice<Word> + ?Sized> SpiDevice<Word> for &mut T {
+    #[inline]
     async fn transaction(
         &mut self,
         operations: &mut [Operation<'_, Word>],
     ) -> Result<(), Self::Error> {
         T::transaction(self, operations).await
     }
 
+    #[inline]
     async fn read(&mut self, buf: &mut [Word]) -> Result<(), Self::Error> {
         T::read(self, buf).await
     }
 
+    #[inline]
     async fn write(&mut self, buf: &[Word]) -> Result<(), Self::Error> {
         T::write(self, buf).await
     }
 
+    #[inline]
     async fn transfer(&mut self, read: &mut [Word], write: &[Word]) -> Result<(), Self::Error> {
         T::transfer(self, read, write).await
     }
 
+    #[inline]
     async fn transfer_in_place(&mut self, buf: &mut [Word]) -> Result<(), Self::Error> {
         T::transfer_in_place(self, buf).await
     }
 }
 
-/// SPI bus
+/// SPI bus.
 ///
 /// `SpiBus` represents **exclusive ownership** over the whole SPI bus, with SCK, MOSI and MISO pins.
 ///
@@ -110,7 +119,7 @@ pub trait SpiBus<Word: 'static + Copy = u8>: ErrorType {
     /// complete. See (the docs on embedded-hal)[embedded_hal::spi] for details on flushing.
     async fn read(&mut self, words: &mut [Word]) -> Result<(), Self::Error>;
 
-    /// Write `words` to the slave, ignoring all the incoming words
+    /// Write `words` to the slave, ignoring all the incoming words.
     ///
     /// Implementations are allowed to return before the operation is
     /// complete. See (the docs on embedded-hal)[embedded_hal::spi] for details on flushing.
@@ -144,22 +153,27 @@ pub trait SpiBus<Word: 'static + Copy = u8>: ErrorType {
 }
 
 impl<T: SpiBus<Word> + ?Sized, Word: 'static + Copy> SpiBus<Word> for &mut T {
+    #[inline]
     async fn read(&mut self, words: &mut [Word]) -> Result<(), Self::Error> {
         T::read(self, words).await
     }
 
+    #[inline]
     async fn write(&mut self, words: &[Word]) -> Result<(), Self::Error> {
         T::write(self, words).await
     }
 
+    #[inline]
     async fn transfer(&mut self, read: &mut [Word], write: &[Word]) -> Result<(), Self::Error> {
         T::transfer(self, read, write).await
     }
 
+    #[inline]
     async fn transfer_in_place(&mut self, words: &mut [Word]) -> Result<(), Self::Error> {
         T::transfer_in_place(self, words).await
     }
 
+    #[inline]
     async fn flush(&mut self) -> Result<(), Self::Error> {
         T::flush(self).await
     }

diff --git a/embedded-hal-bus/CHANGELOG.md b/embedded-hal-bus/CHANGELOG.md
@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+- Minor document fixes.
+- Add #[inline] hints to most of `embedded-hal-bus` functions.
+
 ## [v0.1.0-rc.1] - 2023-08-15
 
 - Updated `embedded-hal`, `embedded-hal-async` to version `1.0.0-rc.1`.

diff --git a/embedded-hal-bus/src/i2c/critical_section.rs b/embedded-hal-bus/src/i2c/critical_section.rs
@@ -14,7 +14,8 @@ pub struct CriticalSectionDevice<'a, T> {
 }
 
 impl<'a, T> CriticalSectionDevice<'a, T> {
-    /// Create a new `CriticalSectionDevice`
+    /// Create a new `CriticalSectionDevice`.
+    #[inline]
     pub fn new(bus: &'a Mutex<RefCell<T>>) -> Self {
         Self { bus }
     }
@@ -31,20 +32,23 @@ impl<'a, T> I2c for CriticalSectionDevice<'a, T>
 where
     T: I2c,
 {
+    #[inline]
     fn read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Self::Error> {
         critical_section::with(|cs| {
             let bus = &mut *self.bus.borrow_ref_mut(cs);
             bus.read(address, read)
         })
     }
 
+    #[inline]
     fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::Error> {
         critical_section::with(|cs| {
             let bus = &mut *self.bus.borrow_ref_mut(cs);
             bus.write(address, write)
         })
     }
 
+    #[inline]
     fn write_read(
         &mut self,
         address: u8,
@@ -57,6 +61,7 @@ where
         })
     }
 
+    #[inline]
     fn transaction(
         &mut self,
         address: u8,

diff --git a/embedded-hal-bus/src/i2c/mutex.rs b/embedded-hal-bus/src/i2c/mutex.rs
@@ -12,7 +12,8 @@ pub struct MutexDevice<'a, T> {
 }
 
 impl<'a, T> MutexDevice<'a, T> {
-    /// Create a new `MutexDevice`
+    /// Create a new `MutexDevice`.
+    #[inline]
     pub fn new(bus: &'a Mutex<T>) -> Self {
         Self { bus }
     }
@@ -29,16 +30,19 @@ impl<'a, T> I2c for MutexDevice<'a, T>
 where
     T: I2c,
 {
+    #[inline]
     fn read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Self::Error> {
         let bus = &mut *self.bus.lock().unwrap();
         bus.read(address, read)
     }
 
+    #[inline]
     fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::Error> {
         let bus = &mut *self.bus.lock().unwrap();
         bus.write(address, write)
     }
 
+    #[inline]
     fn write_read(
         &mut self,
         address: u8,
@@ -49,6 +53,7 @@ where
         bus.write_read(address, write, read)
     }
 
+    #[inline]
     fn transaction(
         &mut self,
         address: u8,

diff --git a/embedded-hal-bus/src/i2c/refcell.rs b/embedded-hal-bus/src/i2c/refcell.rs
@@ -68,7 +68,8 @@ pub struct RefCellDevice<'a, T> {
 }
 
 impl<'a, T> RefCellDevice<'a, T> {
-    /// Create a new `RefCellDevice`
+    /// Create a new `RefCellDevice`.
+    #[inline]
     pub fn new(bus: &'a RefCell<T>) -> Self {
         Self { bus }
     }
@@ -85,16 +86,19 @@ impl<'a, T> I2c for RefCellDevice<'a, T>
 where
     T: I2c,
 {
+    #[inline]
     fn read(&mut self, address: u8, read: &mut [u8]) -> Result<(), Self::Error> {
         let bus = &mut *self.bus.borrow_mut();
         bus.read(address, read)
     }
 
+    #[inline]
     fn write(&mut self, address: u8, write: &[u8]) -> Result<(), Self::Error> {
         let bus = &mut *self.bus.borrow_mut();
         bus.write(address, write)
     }
 
+    #[inline]
     fn write_read(
         &mut self,
         address: u8,
@@ -105,6 +109,7 @@ where
         bus.write_read(address, write, read)
     }
 
+    #[inline]
     fn transaction(
         &mut self,
         address: u8,