stm32 adc: introduce blocking_read

17 files changed, 86 insertions, 38 deletions

diff --git a/embassy-stm32/src/adc/g4.rs b/embassy-stm32/src/adc/g4.rs
index 6569361fe..c1e584f59 100644
--- a/embassy-stm32/src/adc/g4.rs
+++ b/embassy-stm32/src/adc/g4.rs
@@ -258,7 +258,7 @@ impl<'d, T: Instance> Adc<'d, T> {
     }
 
     /// Read an ADC pin.
-    pub fn read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
+    pub fn blocking_read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
         channel.setup();
 
         self.read_channel(channel.channel())
diff --git a/embassy-stm32/src/adc/ringbuffered_v2.rs b/embassy-stm32/src/adc/ringbuffered_v2.rs
index 92b34c3fd..3b064044e 100644
--- a/embassy-stm32/src/adc/ringbuffered_v2.rs
+++ b/embassy-stm32/src/adc/ringbuffered_v2.rs
@@ -97,10 +97,10 @@ impl<'d, T: Instance> Adc<'d, T> {
     /// The length of the `dma_buf` should be a multiple of the ADC channel count.
     /// For example, if 3 channels are measured, its length can be 3 * 40 = 120 measurements.
     ///
-    /// `read_exact` method is used to read out measurements from the DMA ring buffer, and its buffer should be exactly half of the `dma_buf` length.
-    /// It is critical to call `read_exact` frequently to prevent DMA buffer overrun.
+    /// `read` method is used to read out measurements from the DMA ring buffer, and its buffer should be exactly half of the `dma_buf` length.
+    /// It is critical to call `read` frequently to prevent DMA buffer overrun.
     ///
-    /// [`read_exact`]: #method.read_exact
+    /// [`read`]: #method.read
     pub fn into_ring_buffered(
         self,
         dma: impl Peripheral<P = impl RxDma<T>> + 'd,
@@ -331,7 +331,7 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     ///
     /// Receive in the background is terminated if an error is returned.
     /// It must then manually be started again by calling `start()` or by re-calling `read()`.
-    pub fn read<const N: usize>(&mut self, buf: &mut [u16; N]) -> Result<usize, OverrunError> {
+    pub fn blocking_read<const N: usize>(&mut self, buf: &mut [u16; N]) -> Result<usize, OverrunError> {
         let r = T::regs();
 
         // Start background receive if it was not already started
@@ -362,14 +362,14 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     /// This method fills the provided `measurements` array with ADC readings from the DMA buffer.
     /// The length of the `measurements` array should be exactly half of the DMA buffer length. Because interrupts are only generated if half or full DMA transfer completes.
     ///
-    /// Each call to `read_exact` will populate the `measurements` array in the same order as the channels defined with `set_sample_sequence`.
+    /// Each call to `read` will populate the `measurements` array in the same order as the channels defined with `set_sample_sequence`.
     /// There will be many sequences worth of measurements in this array because it only returns if at least half of the DMA buffer is filled.
     /// For example if 3 channels are sampled `measurements` contain: `[sq0 sq1 sq3 sq0 sq1 sq3 sq0 sq1 sq3 sq0 sq1 sq3..]`.
     ///
-    /// If an error is returned, it indicates a DMA overrun, and the process must be restarted by calling `start` or `read_exact` again.
+    /// If an error is returned, it indicates a DMA overrun, and the process must be restarted by calling `start` or `read` again.
     ///
     /// By default, the ADC fills the DMA buffer as quickly as possible. To control the sample rate, call `teardown_adc` after each readout, and then start the DMA again at the desired interval.
-    /// Note that even if using `teardown_adc` to control the sample rate, with each call to `read_exact`, measurements equivalent to half the size of the DMA buffer are still collected.
+    /// Note that even if using `teardown_adc` to control the sample rate, with each call to `read`, measurements equivalent to half the size of the DMA buffer are still collected.
     ///
     /// Example:
     /// ```rust,ignore
@@ -383,7 +383,7 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     ///
     /// let mut measurements = [0u16; DMA_BUF_LEN / 2];
     /// loop {
-    ///     match adc.read_exact(&mut measurements).await {
+    ///     match adc.read(&mut measurements).await {
     ///         Ok(_) => {
     ///             defmt::info!("adc1: {}", measurements);
     ///             // Only needed to manually control sample rate.
@@ -391,7 +391,7 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     ///         }
     ///         Err(e) => {
     ///             defmt::warn!("Error: {:?}", e);
-    ///             // DMA overrun, next call to `read_exact` restart ADC.
+    ///             // DMA overrun, next call to `read` restarts ADC.
     ///         }
     ///     }
     ///
@@ -404,7 +404,7 @@ impl<'d, T: Instance> RingBufferedAdc<'d, T> {
     /// [`set_sample_sequence`]: #method.set_sample_sequence
     /// [`teardown_adc`]: #method.teardown_adc
     /// [`start`]: #method.start
-    pub async fn read_exact<const N: usize>(&mut self, measurements: &mut [u16; N]) -> Result<usize, OverrunError> {
+    pub async fn read<const N: usize>(&mut self, measurements: &mut [u16; N]) -> Result<usize, OverrunError> {
         assert_eq!(
             self.ring_buf.capacity() / 2,
             N,
diff --git a/embassy-stm32/src/adc/v2.rs b/embassy-stm32/src/adc/v2.rs
index ddeb7ea79..842a5ee6d 100644
--- a/embassy-stm32/src/adc/v2.rs
+++ b/embassy-stm32/src/adc/v2.rs
@@ -178,7 +178,7 @@ where
         T::regs().dr().read().0 as u16
     }
 
-    pub fn read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
+    pub fn blocking_read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
         channel.setup();
 
         // Configure ADC
diff --git a/embassy-stm32/src/adc/v3.rs b/embassy-stm32/src/adc/v3.rs
index c876bffea..9441e42ff 100644
--- a/embassy-stm32/src/adc/v3.rs
+++ b/embassy-stm32/src/adc/v3.rs
@@ -254,12 +254,36 @@ impl<'d, T: Instance> Adc<'d, T> {
     }
 
     /// Read an ADC channel.
-    pub fn read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
+    pub fn blocking_read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
         self.read_channel(channel)
     }
 
-    /// Asynchronously read from sequence of ADC channels.
-    pub async fn read_async(
+    /// Read one or multiple ADC channels using DMA.
+    ///
+    /// `sequence` iterator and `readings` must have the same length.
+    ///
+    /// Example
+    /// ```rust,ignore
+    /// use embassy_stm32::adc::{Adc, AdcChannel}
+    ///
+    /// let mut adc = Adc::new(p.ADC1);
+    /// let mut adc_pin0 = p.PA0.degrade_adc();
+    /// let mut adc_pin1 = p.PA1.degrade_adc();
+    /// let mut measurements = [0u16; 2];
+    ///
+    /// adc.read_async(
+    ///     p.DMA1_CH2,
+    ///     [
+    ///         (&mut *adc_pin0, SampleTime::CYCLES160_5),
+    ///         (&mut *adc_pin1, SampleTime::CYCLES160_5),
+    ///     ]
+    ///     .into_iter(),
+    ///     &mut measurements,
+    /// )
+    /// .await;
+    /// defmt::info!("measurements: {}", measurements);
+    /// ```
+    pub async fn read(
         &mut self,
         rx_dma: &mut impl RxDma<T>,
         sequence: impl ExactSizeIterator<Item = (&mut AnyAdcChannel<T>, SampleTime)>,
diff --git a/embassy-stm32/src/adc/v4.rs b/embassy-stm32/src/adc/v4.rs
index 7db6fa4a2..63b5b58ea 100644
--- a/embassy-stm32/src/adc/v4.rs
+++ b/embassy-stm32/src/adc/v4.rs
@@ -318,12 +318,36 @@ impl<'d, T: Instance> Adc<'d, T> {
     }
 
     /// Read an ADC channel.
-    pub fn read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
+    pub fn blocking_read(&mut self, channel: &mut impl AdcChannel<T>) -> u16 {
         self.read_channel(channel)
     }
 
-    /// Asynchronously read from sequence of ADC channels.
-    pub async fn read_async(
+    /// Read one or multiple ADC channels using DMA.
+    ///
+    /// `sequence` iterator and `readings` must have the same length.
+    ///
+    /// Example
+    /// ```rust,ignore
+    /// use embassy_stm32::adc::{Adc, AdcChannel}
+    ///
+    /// let mut adc = Adc::new(p.ADC1);
+    /// let mut adc_pin0 = p.PA0.degrade_adc();
+    /// let mut adc_pin2 = p.PA2.degrade_adc();
+    /// let mut measurements = [0u16; 2];
+    ///
+    /// adc.read_async(
+    ///     p.DMA2_CH0,
+    ///     [
+    ///         (&mut *adc_pin0, SampleTime::CYCLES112),
+    ///         (&mut *adc_pin2, SampleTime::CYCLES112),
+    ///     ]
+    ///     .into_iter(),
+    ///     &mut measurements,
+    /// )
+    /// .await;
+    /// defmt::info!("measurements: {}", measurements);
+    /// ```
+    pub async fn read(
         &mut self,
         rx_dma: &mut impl RxDma<T>,
         sequence: impl ExactSizeIterator<Item = (&mut AnyAdcChannel<T>, SampleTime)>,
diff --git a/examples/stm32f4/src/bin/adc.rs b/examples/stm32f4/src/bin/adc.rs
index 9473b7b7f..423d29225 100644
--- a/examples/stm32f4/src/bin/adc.rs
+++ b/examples/stm32f4/src/bin/adc.rs
@@ -23,7 +23,7 @@ async fn main(_spawner: Spawner) {
     // Startup delay can be combined to the maximum of either
     delay.delay_us(Temperature::start_time_us().max(VrefInt::start_time_us()));
 
-    let vrefint_sample = adc.read(&mut vrefint);
+    let vrefint_sample = adc.blocking_read(&mut vrefint);
 
     let convert_to_millivolts = |sample| {
         // From http://www.st.com/resource/en/datasheet/DM00071990.pdf
@@ -50,16 +50,16 @@ async fn main(_spawner: Spawner) {
 
     loop {
         // Read pin
-        let v = adc.read(&mut pin);
+        let v = adc.blocking_read(&mut pin);
         info!("PC1: {} ({} mV)", v, convert_to_millivolts(v));
 
         // Read internal temperature
-        let v = adc.read(&mut temp);
+        let v = adc.blocking_read(&mut temp);
         let celcius = convert_to_celcius(v);
         info!("Internal temp: {} ({} C)", v, celcius);
 
         // Read internal voltage reference
-        let v = adc.read(&mut vrefint);
+        let v = adc.blocking_read(&mut vrefint);
         info!("VrefInt: {}", v);
 
         Timer::after_millis(100).await;
diff --git a/examples/stm32f4/src/bin/adc_dma.rs b/examples/stm32f4/src/bin/adc_dma.rs
index 992bed573..43a761e6d 100644
--- a/examples/stm32f4/src/bin/adc_dma.rs
+++ b/examples/stm32f4/src/bin/adc_dma.rs
@@ -44,7 +44,7 @@ async fn adc_task(mut p: Peripherals) {
     let _ = adc.start();
     let _ = adc2.start();
     loop {
-        match adc.read_exact(&mut buffer1).await {
+        match adc.read(&mut buffer1).await {
             Ok(_data) => {
                 let toc = Instant::now();
                 info!(
@@ -62,7 +62,7 @@ async fn adc_task(mut p: Peripherals) {
             }
         }
 
-        match adc2.read_exact(&mut buffer2).await {
+        match adc2.read(&mut buffer2).await {
             Ok(_data) => {
                 let toc = Instant::now();
                 info!(
diff --git a/examples/stm32f7/src/bin/adc.rs b/examples/stm32f7/src/bin/adc.rs
index 641157960..6689e3b5d 100644
--- a/examples/stm32f7/src/bin/adc.rs
+++ b/examples/stm32f7/src/bin/adc.rs
@@ -16,7 +16,7 @@ async fn main(_spawner: Spawner) {
     let mut pin = p.PA3;
 
     let mut vrefint = adc.enable_vrefint();
-    let vrefint_sample = adc.read(&mut vrefint);
+    let vrefint_sample = adc.blocking_read(&mut vrefint);
     let convert_to_millivolts = |sample| {
         // From http://www.st.com/resource/en/datasheet/DM00273119.pdf
         // 6.3.27 Reference voltage
@@ -26,7 +26,7 @@ async fn main(_spawner: Spawner) {
     };
 
     loop {
-        let v = adc.read(&mut pin);
+        let v = adc.blocking_read(&mut pin);
         info!("--> {} - {} mV", v, convert_to_millivolts(v));
         Timer::after_millis(100).await;
     }
diff --git a/examples/stm32g0/src/bin/adc.rs b/examples/stm32g0/src/bin/adc.rs
index a35119e3d..6c7f3b48a 100644
--- a/examples/stm32g0/src/bin/adc.rs
+++ b/examples/stm32g0/src/bin/adc.rs
@@ -17,7 +17,7 @@ async fn main(_spawner: Spawner) {
     let mut pin = p.PA1;
 
     let mut vrefint = adc.enable_vrefint();
-    let vrefint_sample = adc.read(&mut vrefint);
+    let vrefint_sample = adc.blocking_read(&mut vrefint);
     let convert_to_millivolts = |sample| {
         // From https://www.st.com/resource/en/datasheet/stm32g031g8.pdf
         // 6.3.3 Embedded internal reference voltage
@@ -27,7 +27,7 @@ async fn main(_spawner: Spawner) {
     };
 
     loop {
-        let v = adc.read(&mut pin);
+        let v = adc.blocking_read(&mut pin);
         info!("--> {} - {} mV", v, convert_to_millivolts(v));
         Timer::after_millis(100).await;
     }
diff --git a/examples/stm32g0/src/bin/adc_dma.rs b/examples/stm32g0/src/bin/adc_dma.rs
index 42d1e729b..3713e5a21 100644
--- a/examples/stm32g0/src/bin/adc_dma.rs
+++ b/examples/stm32g0/src/bin/adc_dma.rs
@@ -24,7 +24,7 @@ async fn main(_spawner: Spawner) {
     let mut pa0 = p.PA0.degrade_adc();
 
     loop {
-        adc.read_async(
+        adc.read(
             &mut dma,
             [
                 (&mut vrefint_channel, SampleTime::CYCLES160_5),
diff --git a/examples/stm32g0/src/bin/adc_oversampling.rs b/examples/stm32g0/src/bin/adc_oversampling.rs
index 3c31eb206..9c5dd872a 100644
--- a/examples/stm32g0/src/bin/adc_oversampling.rs
+++ b/examples/stm32g0/src/bin/adc_oversampling.rs
@@ -36,7 +36,7 @@ async fn main(_spawner: Spawner) {
     adc.oversampling_enable(true);
 
     loop {
-        let v = adc.read(&mut pin);
+        let v = adc.blocking_read(&mut pin);
         info!("--> {} ", v); //max 65520 = 0xFFF0
         Timer::after_millis(100).await;
     }
diff --git a/examples/stm32g4/src/bin/adc.rs b/examples/stm32g4/src/bin/adc.rs
index 3de38cbd6..adca846d8 100644
--- a/examples/stm32g4/src/bin/adc.rs
+++ b/examples/stm32g4/src/bin/adc.rs
@@ -32,7 +32,7 @@ async fn main(_spawner: Spawner) {
     adc.set_sample_time(SampleTime::CYCLES24_5);
 
     loop {
-        let measured = adc.read(&mut p.PA7);
+        let measured = adc.blocking_read(&mut p.PA7);
         info!("measured: {}", measured);
         Timer::after_millis(500).await;
     }
diff --git a/examples/stm32h7/src/bin/adc.rs b/examples/stm32h7/src/bin/adc.rs
index e9a857a74..98504ddf6 100644
--- a/examples/stm32h7/src/bin/adc.rs
+++ b/examples/stm32h7/src/bin/adc.rs
@@ -51,9 +51,9 @@ async fn main(_spawner: Spawner) {
     let mut vrefint_channel = adc.enable_vrefint();
 
     loop {
-        let vrefint = adc.read(&mut vrefint_channel);
+        let vrefint = adc.blocking_read(&mut vrefint_channel);
         info!("vrefint: {}", vrefint);
-        let measured = adc.read(&mut p.PC0);
+        let measured = adc.blocking_read(&mut p.PC0);
         info!("measured: {}", measured);
         Timer::after_millis(500).await;
     }
diff --git a/examples/stm32h7/src/bin/adc_dma.rs b/examples/stm32h7/src/bin/adc_dma.rs
index 6c0240453..0b905d227 100644
--- a/examples/stm32h7/src/bin/adc_dma.rs
+++ b/examples/stm32h7/src/bin/adc_dma.rs
@@ -56,7 +56,7 @@ async fn main(_spawner: Spawner) {
     let mut pc0 = p.PC0.degrade_adc();
 
     loop {
-        adc.read_async(
+        adc.read(
             &mut dma,
             [
                 (&mut vrefint_channel, SampleTime::CYCLES387_5),
diff --git a/examples/stm32l4/src/bin/adc.rs b/examples/stm32l4/src/bin/adc.rs
index 7a89334e0..c557ac6d7 100644
--- a/examples/stm32l4/src/bin/adc.rs
+++ b/examples/stm32l4/src/bin/adc.rs
@@ -23,7 +23,7 @@ fn main() -> ! {
     let mut channel = p.PC0;
 
     loop {
-        let v = adc.read(&mut channel);
+        let v = adc.blocking_read(&mut channel);
         info!("--> {}", v);
     }
 }
diff --git a/examples/stm32u0/src/bin/adc.rs b/examples/stm32u0/src/bin/adc.rs
index 4410448f1..c8252e4e1 100644
--- a/examples/stm32u0/src/bin/adc.rs
+++ b/examples/stm32u0/src/bin/adc.rs
@@ -23,7 +23,7 @@ fn main() -> ! {
     let mut channel = p.PC0;
 
     loop {
-        let v = adc.read(&mut channel);
+        let v = adc.blocking_read(&mut channel);
         info!("--> {}", v);
         embassy_time::block_for(Duration::from_millis(200));
     }
diff --git a/tests/stm32/src/bin/dac.rs b/tests/stm32/src/bin/dac.rs
index 06501ab14..86a68c530 100644
--- a/tests/stm32/src/bin/dac.rs
+++ b/tests/stm32/src/bin/dac.rs
@@ -38,7 +38,7 @@ async fn main(_spawner: Spawner) {
     dac.set(Value::Bit8(0));
     // Now wait a little to obtain a stable value
     Timer::after_millis(30).await;
-    let offset = adc.read(&mut adc_pin);
+    let offset = adc.blocking_read(&mut adc_pin);
 
     for v in 0..=255 {
         // First set the DAC output value
@@ -49,7 +49,7 @@ async fn main(_spawner: Spawner) {
         Timer::after_millis(30).await;
 
         // Need to steal the peripherals here because PA4 is obviously in use already
-        let measured = adc.read(&mut unsafe { embassy_stm32::Peripherals::steal() }.PA4);
+        let measured = adc.blocking_read(&mut unsafe { embassy_stm32::Peripherals::steal() }.PA4);
         // Calibrate and normalize the measurement to get close to the dac_output_val
         let measured_normalized = ((measured as i32 - offset as i32) / normalization_factor) as i16;