Clean up SHA, RSA, mandate #[must_use] on Futures

documentation/API-GUIDELINES.md

@@ -15,16 +15,16 @@ The following paragraphs contain additional recommendations.
 
 ## Construction and Destruction of Drivers
 
-- Drivers take peripherals and pins via the `PeripheralRef` pattern - they don't consume peripherals/pins
-- Consider adding a `Drop` implementation resetting the peripheral to idle state
-- Consider using a builder-like pattern for configuration which must be done during initialization
+- Drivers take peripherals and pins via the `PeripheralRef` pattern - they don't consume peripherals/pins.
+- Consider adding a `Drop` implementation resetting the peripheral to idle state.
+- Consider using a builder-like pattern for configuration which must be done during initialization.
 
 ## Interoperability
 
-- `cfg` gated `defmt` derives and impls are added to new structs and enums
+- `cfg` gated `defmt` derives and impls are added to new structs and enums.
     - see [this example](https://github.com/esp-rs/esp-hal/blob/df2b7bd8472cc1d18db0d9441156575570f59bb3/esp-hal/src/spi/mod.rs#L15)
     - e.g. `#[cfg_attr(feature = "defmt", derive(defmt::Format))]`
-- Don't use `log::XXX!` macros directly - use the wrappers in `fmt.rs` (e.g. just `info!` instead of `log::info!` or importing `log::*`)
+- Don't use `log::XXX!` macros directly - use the wrappers in `fmt.rs` (e.g. just `info!` instead of `log::info!` or importing `log::*`)!
 
 ## API Surface
 
@@ -52,6 +52,7 @@ The following paragraphs contain additional recommendations.
 - If you are porting code from ESP-IDF (or anything else), please include a link WITH the commit hash in it, and please highlight the relevant line(s) of code
 - If necessary provide further context as comments (consider linking to code, PRs, TRM - make sure to use permanent links, e.g. include the hash when linking to a Git repository, include the revision, page number etc. when linking to TRMs)
 - Generally, follow common "good practices" and idiomatic Rust style
+- All `Future` objects (public or private) must be marked with ``#[must_use = "futures do nothing unless you `.await` or poll them"]``.
 
 ## Modules Documentation
 
@@ -77,7 +78,7 @@ Modules should have the following documentation format:
 //! ```
 //!
 //! ## Implementation State
-//! List unsuported features
+//! List unsupported features
 ```
 - If any of the headers is empty, remove it
 - When possible, use ESP-IDF docs and TRM as references and include links if possible.

esp-hal/src/aes/mod.rs

@@ -19,8 +19,8 @@
 //! ```rust, no_run
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::aes::{Aes, Mode};
-//! # let keytext = "SUp4SeCp@sSw0rd".as_bytes();
-//! # let plaintext = "message".as_bytes();
+//! # let keytext = b"SUp4SeCp@sSw0rd";
+//! # let plaintext = b"message";
 //! # let mut keybuf = [0_u8; 16];
 //! # keybuf[..keytext.len()].copy_from_slice(keytext);
 //! let mut block_buf = [0_u8; 16];

esp-hal/src/analog/adc/mod.rs

@@ -27,7 +27,6 @@
 //! # use esp_hal::analog::adc::Adc;
 //! # use esp_hal::delay::Delay;
 //! # use esp_hal::gpio::Io;
-//! # use core::result::Result::Err;
 //!
 //! # let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 #![cfg_attr(esp32, doc = "let analog_pin = io.pins.gpio32;")]

esp-hal/src/dma/mod.rs

@@ -2716,20 +2716,20 @@ pub(crate) mod asynch {
 
     use super::*;
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub struct DmaTxFuture<'a, TX>
     where
         TX: Tx,
     {
         pub(crate) tx: &'a mut TX,
-        _a: (),
     }
 
     impl<'a, TX> DmaTxFuture<'a, TX>
     where
         TX: Tx,
     {
         pub fn new(tx: &'a mut TX) -> Self {
-            Self { tx, _a: () }
+            Self { tx }
         }
     }
 
@@ -2768,20 +2768,20 @@ pub(crate) mod asynch {
         }
     }
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub struct DmaRxFuture<'a, RX>
     where
         RX: Rx,
     {
         pub(crate) rx: &'a mut RX,
-        _a: (),
     }
 
     impl<'a, RX> DmaRxFuture<'a, RX>
     where
         RX: Rx,
     {
         pub fn new(rx: &'a mut RX) -> Self {
-            Self { rx, _a: () }
+            Self { rx }
         }
 
         #[allow(dead_code)] // Dead on the C2

esp-hal/src/gpio/mod.rs

@@ -2865,6 +2865,7 @@ mod asynch {
         }
     }
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub struct PinFuture {
         pin_num: u8,
     }

esp-hal/src/i2c.rs

@@ -22,7 +22,6 @@
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2c::I2C;
 //! # use esp_hal::gpio::Io;
-//! # use core::option::Option::None;
 //! # use crate::esp_hal::prelude::_fugit_RateExtU32;
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! // Create a new peripheral object with the described wiring
@@ -50,7 +49,6 @@
 #![doc = crate::before_snippet!()]
 //! # use esp_hal::i2c::I2C;
 //! # use esp_hal::gpio::Io;
-//! # use core::option::Option::None;
 //! # use crate::esp_hal::prelude::_fugit_RateExtU32;
 //! let io = Io::new(peripherals.GPIO, peripherals.IO_MUX);
 //! // Create a new peripheral object with the described wiring
@@ -516,6 +514,7 @@ mod asynch {
     }
 
     #[cfg(not(esp32))]
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub(crate) struct I2cFuture<'a, T>
     where
         T: Instance,

esp-hal/src/lcd_cam/mod.rs

@@ -129,6 +129,7 @@ pub mod asynch {
 
     static TX_WAKER: AtomicWaker = AtomicWaker::new();
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub(crate) struct LcdDoneFuture {}
 
     impl LcdDoneFuture {

esp-hal/src/parl_io.rs

@@ -1675,6 +1675,7 @@ pub mod asynch {
 
     static TX_WAKER: AtomicWaker = AtomicWaker::new();
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     struct TxDoneFuture {}
 
     impl TxDoneFuture {

esp-hal/src/rmt.rs

@@ -1149,6 +1149,7 @@ pub mod asynch {
     const INIT: AtomicWaker = AtomicWaker::new();
     static WAKER: [AtomicWaker; NUM_CHANNELS] = [INIT; NUM_CHANNELS];
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub(crate) struct RmtTxFuture<T>
     where
         T: TxChannelAsync,
@@ -1212,6 +1213,7 @@ pub mod asynch {
         }
     }
 
+    #[must_use = "futures do nothing unless you `.await` or poll them"]
     pub(crate) struct RmtRxFuture<T>
     where
         T: RxChannelAsync,

esp-hal/src/rsa/esp32.rs

@@ -92,10 +92,12 @@ impl<'a, 'd, T: RsaMode, DM: crate::Mode, const N: usize> RsaModularMultiplicati
 where
     T: RsaMode<InputType = [u32; N]>,
 {
-    /// Creates an Instance of `RsaMultiplication`.  
-    /// `m_prime` could be calculated using `-(modular multiplicative inverse of
-    /// modulus) mod 2^32`, for more information check 24.3.2 in the
-    /// <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+    /// Creates an instance of `RsaMultiplication`.
+    ///
+    /// `m_prime` can be calculated using `-(modular multiplicative inverse of
+    /// modulus) mod 2^32`.
+    ///
+    /// For more information refer to 24.3.2 of <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>.
     pub fn new(rsa: &'a mut Rsa<'d, DM>, modulus: &T::InputType, m_prime: u32) -> Self {
         Self::set_mode(rsa);
         unsafe {
@@ -113,36 +115,35 @@ where
         rsa.write_multi_mode((N / 16 - 1) as u32)
     }
 
-    /// Starts the first step of modular multiplication operation. `r` could be
-    /// calculated using `2 ^ ( bitlength * 2 ) mod modulus`,
-    /// for more information check 24.3.2 in the
-    /// <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+    /// Starts the first step of modular multiplication operation.
+    ///
+    /// `r` can be calculated using `2 ^ ( bitlength * 2 ) mod modulus`.
+    ///
+    /// For more information refer to 24.3.2 of <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>.
     pub fn start_step1(&mut self, operand_a: &T::InputType, r: &T::InputType) {
         unsafe {
             self.rsa.write_operand_a(operand_a);
             self.rsa.write_r(r);
         }
-        self.set_start();
+        self.start();
     }
 
     /// Starts the second step of modular multiplication operation.
+    ///
     /// This is a non blocking function that returns without an error if
     /// operation is completed successfully. `start_step1` must be called
     /// before calling this function.
     pub fn start_step2(&mut self, operand_b: &T::InputType) {
-        loop {
-            if self.rsa.is_idle() {
-                self.rsa.clear_interrupt();
-                unsafe {
-                    self.rsa.write_operand_a(operand_b);
-                }
-                self.set_start();
-                break;
-            }
+        while !self.rsa.is_idle() {}
+
+        self.rsa.clear_interrupt();
+        unsafe {
+            self.rsa.write_operand_a(operand_b);
         }
+        self.start();
     }
 
-    fn set_start(&mut self) {
+    fn start(&mut self) {
         self.rsa.write_multi_start();
     }
 }
@@ -151,10 +152,12 @@ impl<'a, 'd, T: RsaMode, DM: crate::Mode, const N: usize> RsaModularExponentiati
 where
     T: RsaMode<InputType = [u32; N]>,
 {
-    /// Creates an Instance of `RsaModularExponentiation`.  
-    /// `m_prime` could be calculated using `-(modular multiplicative inverse of
-    /// modulus) mod 2^32`, for more information check 24.3.2 in the
-    /// <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>
+    /// Creates an instance of `RsaModularExponentiation`.
+    ///
+    /// `m_prime` can be calculated using `-(modular multiplicative inverse of
+    /// modulus) mod 2^32`.
+    ///
+    /// For more information refer to 24.3.2 of <https://www.espressif.com/sites/default/files/documentation/esp32_technical_reference_manual_en.pdf>.
     pub fn new(
         rsa: &'a mut Rsa<'d, DM>,
         exponent: &T::InputType,
@@ -179,7 +182,7 @@ where
     }
 
     /// Starts the modular exponentiation operation on the RSA hardware.
-    pub(super) fn set_start(&mut self) {
+    pub(super) fn start(&mut self) {
         self.rsa.write_modexp_start();
     }
 }
@@ -188,7 +191,7 @@ impl<'a, 'd, T: RsaMode + Multi, DM: crate::Mode, const N: usize> RsaMultiplicat
 where
     T: RsaMode<InputType = [u32; N]>,
 {
-    /// Creates an Instance of `RsaMultiplication`.
+    /// Creates an instance of `RsaMultiplication`.
     pub fn new(rsa: &'a mut Rsa<'d, DM>) -> Self {
         Self::set_mode(rsa);
         Self {
@@ -203,16 +206,16 @@ where
             self.rsa.write_multi_operand_a(operand_a);
             self.rsa.write_multi_operand_b(operand_b);
         }
-        self.set_start();
+        self.start();
     }
 
-    /// Sets the multiplication mode for the RSA hardware.    
+    /// Sets the multiplication mode for the RSA hardware.
     pub(super) fn set_mode(rsa: &mut Rsa<'d, DM>) {
         rsa.write_multi_mode(((N * 2) / 16 + 7) as u32)
     }
 
     /// Starts the multiplication operation on the RSA hardware.
-    pub(super) fn set_start(&mut self) {
+    pub(super) fn start(&mut self) {
         self.rsa.write_multi_start();
     }
 }