Add macro for double register read with reasoning

Author: astapleton

src/i2c.rs

@@ -459,8 +459,7 @@ impl<I2C: Instance> I2c<I2C> {
     /// Reset the peripheral
     pub fn reset(&mut self) {
         self.i2c.cr1().modify(|_, w| w.pe().disabled());
-        let _ = self.i2c.cr1().read();
-        let _ = self.i2c.cr1().read(); // Delay 2 peripheral clocks
+        interrupt_clear_clock_sync_delay!(self.i2c.cr1());
         while self.i2c.cr1().read().pe().is_enabled() {}
         self.i2c.cr1().modify(|_, w| w.pe().enabled());
     }
@@ -477,8 +476,6 @@ impl<I2C: Instance> I2c<I2C> {
             Event::NotAcknowledge => w.nackie().enabled(),
             Event::AddressMatch => w.addrie().enabled(),
         });
-        let _ = self.i2c.cr1().read();
-        let _ = self.i2c.cr1().read(); // Delay 2 peripheral clocks
     }
 
     /// Stop listening for interrupt `event`
@@ -493,8 +490,7 @@ impl<I2C: Instance> I2c<I2C> {
             Event::NotAcknowledge => w.nackie().disabled(),
             Event::AddressMatch => w.addrie().disabled(),
         });
-        let _ = self.i2c.cr1().read();
-        let _ = self.i2c.cr1().read(); // Delay 2 peripheral clocks
+        interrupt_clear_clock_sync_delay!(self.i2c.cr1());
     }
 
     /// Clears interrupt flag for `event`
@@ -506,8 +502,7 @@ impl<I2C: Instance> I2c<I2C> {
             Event::NotAcknowledge => w.nackcf().clear(),
             _ => w,
         });
-        let _ = self.i2c.isr().read();
-        let _ = self.i2c.isr().read(); // Delay 2 peripheral clocks
+        interrupt_clear_clock_sync_delay!(self.i2c.cr1());
     }
 
     /// Check if the specified `event`` occurred. If an error occurred, this

src/lib.rs

@@ -40,6 +40,10 @@ pub use crate::stm32::interrupt;
 #[cfg(feature = "device-selected")]
 pub mod prelude;
 
+#[cfg(feature = "device-selected")]
+#[macro_use]
+mod macros;
+
 #[cfg(feature = "device-selected")]
 pub mod pwr;
 

src/macros.rs

@@ -0,0 +1,18 @@
+/// This macro is used to insert a double read of a peripheral register to give the  peripheral
+/// enough time to process a write to a register to clear an interrupt. This prevents an interrupt
+/// from firing immediately a second time after an ISR exits. It's necessary due to delayed
+/// synchronization between a peripheral and the CPU due to the different clocks of the
+/// peripheral and CPU. The register that is passed in should not have produce undesireable side
+/// effects when read.
+///
+/// See ARM Application Note 321 Section 4.9
+/// Also see discussion in the stm32h7xx-hal PRs [`#191`][191] and [`#195`][195].
+///
+/// [191]: https://github.com/stm32-rs/stm32h7xx-hal/pull/191
+/// [195]: https://github.com/stm32-rs/stm32h7xx-hal/pull/195
+macro_rules! interrupt_clear_clock_sync_delay {
+    ($status_reg:expr) => {
+        let _ = $status_reg.read();
+        let _ = $status_reg.read();
+    };
+}