STM32: USART: Add eager_reads config option

adamgreig · adamgreig · commit 224ebefa9133 · 2025-09-16T01:47:58.000+01:00
diff --git a/embassy-hal-internal/src/atomic_ring_buffer.rs b/embassy-hal-internal/src/atomic_ring_buffer.rs
@@ -142,6 +142,19 @@ impl RingBuffer {
         self.wrap(start + len) == end
     }
 
+    /// Check if buffer is at least half full.
+    pub fn is_half_full(&self) -> bool {
+        let len = self.len.load(Ordering::Relaxed);
+        let start = self.start.load(Ordering::Relaxed);
+        let end = self.end.load(Ordering::Relaxed);
+        let n = if end >= start {
+            end - start
+        } else {
+            2 * len - start + end
+        };
+        n >= len / 2
+    }
+
     /// Check if buffer is empty.
     pub fn is_empty(&self) -> bool {
         let start = self.start.load(Ordering::Relaxed);
@@ -394,6 +407,7 @@ mod tests {
             rb.init(b.as_mut_ptr(), 4);
 
             assert_eq!(rb.is_empty(), true);
+            assert_eq!(rb.is_half_full(), false);
             assert_eq!(rb.is_full(), false);
 
             rb.writer().push(|buf| {
@@ -406,6 +420,7 @@ mod tests {
             });
 
             assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), true);
 
             rb.writer().push(|buf| {
@@ -415,6 +430,7 @@ mod tests {
             });
 
             assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), true);
 
             rb.reader().pop(|buf| {
@@ -424,6 +440,7 @@ mod tests {
             });
 
             assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), false);
 
             rb.reader().pop(|buf| {
@@ -432,6 +449,7 @@ mod tests {
             });
 
             assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), false);
 
             rb.reader().pop(|buf| {
@@ -447,6 +465,7 @@ mod tests {
             });
 
             assert_eq!(rb.is_empty(), true);
+            assert_eq!(rb.is_half_full(), false);
             assert_eq!(rb.is_full(), false);
 
             rb.reader().pop(|buf| {
@@ -460,14 +479,28 @@ mod tests {
                 1
             });
 
+            assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), false);
+            assert_eq!(rb.is_full(), false);
+
             rb.writer().push(|buf| {
                 assert_eq!(3, buf.len());
                 buf[0] = 11;
-                buf[1] = 12;
-                2
+                1
+            });
+
+            assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
+            assert_eq!(rb.is_full(), false);
+
+            rb.writer().push(|buf| {
+                assert_eq!(2, buf.len());
+                buf[0] = 12;
+                1
             });
 
             assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), false);
 
             rb.writer().push(|buf| {
@@ -477,6 +510,7 @@ mod tests {
             });
 
             assert_eq!(rb.is_empty(), false);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), true);
         }
     }
@@ -490,6 +524,7 @@ mod tests {
             rb.init(b.as_mut_ptr(), b.len());
 
             assert_eq!(rb.is_empty(), true);
+            assert_eq!(rb.is_half_full(), true);
             assert_eq!(rb.is_full(), true);
 
             rb.writer().push(|buf| {
diff --git a/embassy-stm32/CHANGELOG.md b/embassy-stm32/CHANGELOG.md
@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - fix: stm32/(ospi/hspi/xspi): Fix the alternate bytes register config sticking around for subsequent writes
 - feat: Configurable gpio speed for QSPI
 - feat: derive Clone, Copy and defmt::Format for all *SPI-related configs
+- feat: stm32/usart: add `eager_reads` option to control if buffered readers return as soon as possible or after more data is available ([#4668](https://github.com/embassy-rs/embassy/pull/4668))
 
 ## 0.4.0 - 2025-08-26
 
diff --git a/embassy-stm32/src/usart/buffered.rs b/embassy-stm32/src/usart/buffered.rs
@@ -68,8 +68,14 @@ unsafe fn on_interrupt(r: Regs, state: &'static State) {
             // FIXME: Should we disable any further RX interrupts when the buffer becomes full.
         }
 
-        if !state.rx_buf.is_empty() {
-            state.rx_waker.wake();
+        if state.eager_reads.load(Ordering::Relaxed) {
+            if !state.rx_buf.is_empty() {
+                state.rx_waker.wake();
+            }
+        } else {
+            if state.rx_buf.is_half_full() {
+                state.rx_waker.wake();
+            }
         }
     }
 
@@ -132,6 +138,7 @@ pub(super) struct State {
     tx_done: AtomicBool,
     tx_rx_refcount: AtomicU8,
     half_duplex_readback: AtomicBool,
+    eager_reads: AtomicBool,
 }
 
 impl State {
@@ -144,6 +151,7 @@ impl State {
             tx_done: AtomicBool::new(true),
             tx_rx_refcount: AtomicU8::new(0),
             half_duplex_readback: AtomicBool::new(false),
+            eager_reads: AtomicBool::new(false),
         }
     }
 }
@@ -419,6 +427,7 @@ impl<'d> BufferedUart<'d> {
         let state = T::buffered_state();
         let kernel_clock = T::frequency();
 
+        state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
         state.half_duplex_readback.store(
             config.duplex == Duplex::Half(HalfDuplexReadback::Readback),
             Ordering::Relaxed,
@@ -456,6 +465,7 @@ impl<'d> BufferedUart<'d> {
         let info = self.rx.info;
         let state = self.rx.state;
         state.tx_rx_refcount.store(2, Ordering::Relaxed);
+        state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
 
         info.rcc.enable_and_reset();
 
@@ -527,6 +537,8 @@ impl<'d> BufferedUart<'d> {
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure(self.rx.info, self.rx.kernel_clock, config)?;
 
+        self.rx.state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
+
         self.rx.info.regs.cr1().modify(|w| {
             w.set_rxneie(true);
             w.set_idleie(true);
@@ -633,6 +645,8 @@ impl<'d> BufferedUartRx<'d> {
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
         reconfigure(self.info, self.kernel_clock, config)?;
 
+        self.state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
+
         self.info.regs.cr1().modify(|w| {
             w.set_rxneie(true);
             w.set_idleie(true);
diff --git a/embassy-stm32/src/usart/mod.rs b/embassy-stm32/src/usart/mod.rs
@@ -4,7 +4,7 @@
 
 use core::future::poll_fn;
 use core::marker::PhantomData;
-use core::sync::atomic::{compiler_fence, AtomicU8, Ordering};
+use core::sync::atomic::{compiler_fence, AtomicBool, AtomicU8, Ordering};
 use core::task::Poll;
 
 use embassy_embedded_hal::SetConfig;
@@ -206,6 +206,18 @@ pub struct Config {
     /// If false: the error is ignored and cleared
     pub detect_previous_overrun: bool,
 
+    /// If true then read-like calls on `BufferedUartRx` and `RingBufferedUartRx`
+    /// are woken/return as soon as any data is available in the buffer.
+    ///
+    /// If false (the default) then reads started typically only wake/return after
+    /// line idle or after the buffer is at least half full (`BufferedUartRx`) or
+    /// the DMA buffer is written at the half or full positions (`RingBufferedUartRx`),
+    /// though it may also wake/return earlier in some circumstances.
+    ///
+    /// Has no effect on plain `Uart` or `UartRx` reads, which are specified to either
+    /// return a single word, a full buffer, or after line idle.
+    pub eager_reads: bool,
+
     /// Set this to true if the line is considered noise free.
     /// This will increase the receiver’s tolerance to clock deviations,
     /// but will effectively disable noise detection.
@@ -270,6 +282,7 @@ impl Default for Config {
             parity: Parity::ParityNone,
             // historical behavior
             detect_previous_overrun: false,
+            eager_reads: false,
             #[cfg(not(usart_v1))]
             assume_noise_free: false,
             #[cfg(any(usart_v3, usart_v4))]
@@ -966,6 +979,7 @@ impl<'d, M: Mode> UartRx<'d, M> {
         let info = self.info;
         let state = self.state;
         state.tx_rx_refcount.store(1, Ordering::Relaxed);
+        state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
 
         info.rcc.enable_and_reset();
 
@@ -982,6 +996,7 @@ impl<'d, M: Mode> UartRx<'d, M> {
 
     /// Reconfigure the driver
     pub fn set_config(&mut self, config: &Config) -> Result<(), ConfigError> {
+        self.state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
         reconfigure(self.info, self.kernel_clock, config)
     }
 
@@ -1462,6 +1477,7 @@ impl<'d, M: Mode> Uart<'d, M> {
         let info = self.rx.info;
         let state = self.rx.state;
         state.tx_rx_refcount.store(2, Ordering::Relaxed);
+        state.eager_reads.store(config.eager_reads, Ordering::Relaxed);
 
         info.rcc.enable_and_reset();
 
@@ -2022,6 +2038,7 @@ struct State {
     rx_waker: AtomicWaker,
     tx_waker: AtomicWaker,
     tx_rx_refcount: AtomicU8,
+    eager_reads: AtomicBool,
 }
 
 impl State {
@@ -2030,6 +2047,7 @@ impl State {
             rx_waker: AtomicWaker::new(),
             tx_waker: AtomicWaker::new(),
             tx_rx_refcount: AtomicU8::new(0),
+            eager_reads: AtomicBool::new(false),
         }
     }
 }
diff --git a/embassy-stm32/src/usart/ringbuffered.rs b/embassy-stm32/src/usart/ringbuffered.rs
