Implement Serial DMA abstraction

The implementation follows existing DMA abstraction for I2C interface.

The implementation has been tested on STM32F407-Discovery board with the code in `examples/serial-dma.rs`.

Author: zyma98

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
  - add trait bound `RegisterBlockImpl` to type `RegisterBlock` associated with `serial::Instance` [#732]
  - remove unneeded trait bound for methods that take in a `serial::Instance` and use the associated `RegisterBlock`
  - bump `sdio-host` to 0.9.0, refactor SDIO initialization [#734]
+ - Added non-blocking serial based on DMA [#738]
  - use RTCCLK for RTC wakeup timer for short durations [#746]
  - Support 8-bit FMC data bus
 

Cargo.toml

@@ -506,6 +506,10 @@ required-features = []
 name = "serial-9bit"
 required-features = ["gpiod"] # stm32f411
 
+[[example]]
+name = "serial-dma"
+required-features = ["stm32f407"]
+
 [[example]]
 name = "spi-dma"
 required-features = ["stm32f411"]

examples/serial-dma.rs

@@ -0,0 +1,156 @@
+#![no_std]
+#![no_main]
+
+use core::{
+    cell::RefCell,
+    sync::atomic::{AtomicBool, Ordering},
+};
+use cortex_m::interrupt::Mutex;
+use cortex_m_rt::entry;
+use panic_halt as _;
+use stm32f4xx_hal::{
+    self,
+    dma::{StreamX, StreamsTuple},
+    interrupt,
+    pac::{self, DMA1, USART2},
+    prelude::*,
+    serial::{
+        self,
+        dma::{RxDMA, SerialDma, TxDMA},
+    },
+    uart::{config::StopBits, Config, Serial},
+};
+
+/// Global variable for USART2 DMA handle.
+static USART2_DMA: Mutex<
+    RefCell<
+        Option<
+            SerialDma<
+                USART2,
+                TxDMA<USART2, StreamX<DMA1, 6>, 4>,
+                RxDMA<USART2, StreamX<DMA1, 5>, 4>,
+            >,
+        >,
+    >,
+> = Mutex::new(RefCell::new(None));
+
+/// Boolean flag to wait for DMA finish.
+static DONE: AtomicBool = AtomicBool::new(false);
+
+#[entry]
+fn main() -> ! {
+    if let Some(dp) = pac::Peripherals::take() {
+        // Set up the system clock.
+        let rcc = dp.RCC.constrain();
+        let clocks = rcc.cfgr.freeze();
+
+        // Enable DMA1.
+        let dma1 = StreamsTuple::new(dp.DMA1);
+
+        // Enable GPIOA.
+        let gpioa = dp.GPIOA.split();
+
+        // Configure USART2.
+        let rx_2 = gpioa.pa3.into_alternate();
+        let tx_2 = gpioa.pa2.into_alternate();
+        let usart2 = Serial::new(
+            dp.USART2,
+            (tx_2, rx_2),
+            Config::default()
+                .baudrate(115200.bps())
+                .parity_none()
+                .stopbits(StopBits::STOP1)
+                .dma(serial::config::DmaConfig::TxRx),
+            &clocks,
+        )
+        .unwrap();
+
+        // Make USART2 use DMA.
+        let usart2_dma = usart2.use_dma(dma1.6, dma1.5);
+
+        // Put DMA handle to the global variable.
+        cortex_m::interrupt::free(|cs| {
+            USART2_DMA.borrow(cs).borrow_mut().replace(usart2_dma);
+        });
+
+        // Enable interrupt
+        unsafe {
+            cortex_m::peripheral::NVIC::unmask(pac::Interrupt::USART2);
+            cortex_m::peripheral::NVIC::unmask(pac::Interrupt::DMA1_STREAM5);
+            cortex_m::peripheral::NVIC::unmask(pac::Interrupt::DMA1_STREAM6);
+        }
+
+        /*** Test Below ***/
+
+        let mut buf = [0u8; 6];
+
+        // Read 6 bytes to the buffer using the DMA non-blocking mode.
+        cortex_m::interrupt::free(|cs| unsafe {
+            if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+                usart2_dma.read_dma(&mut buf, None).unwrap();
+            }
+        });
+
+        // Wait until DMA finishes.
+        while !DONE.load(Ordering::SeqCst) {}
+        DONE.store(false, Ordering::SeqCst);
+
+        // Write the 6 bytes back using the DMA non-blocking mode.
+        cortex_m::interrupt::free(|cs| unsafe {
+            if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+                usart2_dma.write_dma(&buf, None).unwrap();
+            }
+        });
+
+        // Wait until DMA finishes.
+        while !DONE.load(Ordering::SeqCst) {}
+
+        // Read 6 bytes to the buffer using the blocking mode.
+        cortex_m::interrupt::free(|cs| {
+            if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+                usart2_dma.read(&mut buf).unwrap();
+            }
+        });
+
+        // Write the 6 bytes back using the blocking mode.
+        cortex_m::interrupt::free(|cs| {
+            if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+                usart2_dma.write(&buf).unwrap();
+            }
+        });
+    }
+
+    loop {}
+}
+
+#[interrupt]
+#[allow(non_snake_case)]
+fn USART2() {
+    cortex_m::interrupt::free(|cs| {
+        if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+            usart2_dma.handle_error_interrupt();
+        }
+    });
+}
+
+#[interrupt]
+#[allow(non_snake_case)]
+fn DMA1_STREAM5() {
+    cortex_m::interrupt::free(|cs| {
+        if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+            usart2_dma.handle_dma_interrupt();
+            DONE.store(true, Ordering::SeqCst);
+        }
+    });
+}
+
+#[interrupt]
+#[allow(non_snake_case)]
+fn DMA1_STREAM6() {
+    cortex_m::interrupt::free(|cs| {
+        if let Some(usart2_dma) = USART2_DMA.borrow(cs).borrow_mut().as_mut() {
+            usart2_dma.handle_dma_interrupt();
+            DONE.store(true, Ordering::SeqCst);
+        }
+    });
+}

src/prelude.rs

@@ -68,6 +68,9 @@ pub use crate::qei::QeiExt as _stm32f4xx_hal_QeiExt;
 pub use crate::rcc::RccExt as _stm32f4xx_hal_rcc_RccExt;
 #[cfg(feature = "rng")]
 pub use crate::rng::RngExt as _stm32f4xx_hal_rng_RngExt;
+pub use crate::serial::dma::SerialHandleIT as _stm32f4xx_hal_serial_dma_SerialHandleIT;
+pub use crate::serial::dma::SerialReadDMA as _stm32f4xx_hal_serial_dma_SerialReadDMA;
+pub use crate::serial::dma::SerialWriteDMA as _stm32f4xx_hal_serial_dma_SerialWriteDMA;
 pub use crate::serial::RxISR as _stm32f4xx_hal_serial_RxISR;
 pub use crate::serial::RxListen as _stm32f4xx_hal_serial_RxListen;
 pub use crate::serial::SerialExt as _stm32f4xx_hal_serial_SerialExt;

src/serial.rs

@@ -30,6 +30,8 @@ use crate::pac;
 use crate::gpio::NoPin;
 use crate::rcc::Clocks;
 
+pub mod dma;
+
 /// Serial error kind
 ///
 /// This represents a common set of serial operation errors. HAL implementations are
@@ -273,6 +275,10 @@ macro_rules! halUsart {
                     })
                 });
             }
+
+            fn peri_address() -> u32 {
+                unsafe { (*(<$USART>::ptr() as *const Self::RegisterBlock)).peri_address() }
+            }
         }
     };
 }