Merge pull request #142 from bbrown1867/support-non-blocking-qspi-dma

Make `qspi.rs` DMA APIs Non-Blocking

Author: hannobraun

examples/stm32f7disco-qspi-flash/main.rs

@@ -9,6 +9,7 @@
 
 extern crate panic_semihosting;
 
+use core::pin::Pin;
 use cortex_m_rt::entry;
 use cortex_m_semihosting::hprintln;
 use stm32f7xx_hal::{
@@ -57,7 +58,7 @@ fn main() -> ! {
 }
 
 fn memory_example_polling(mt25q: &mut mt25q::Mt25q) {
-    // Create a set of buffers for a memory at address `ADDR` of size `LEN` bytes
+    // Create a set of buffers in RAM that will mirror flash memory at address `ADDR` of size `LEN`
     const ADDR: u32 = 0x7003;
     const LEN: usize = 1035;
     let mut read_buffer: [u8; LEN] = [0; LEN];
@@ -66,7 +67,10 @@ fn memory_example_polling(mt25q: &mut mt25q::Mt25q) {
         write_buffer[i] = i as u8;
     }
 
-    // Test erase + read
+    ///////////////////////
+    // Test erase + read //
+    ///////////////////////
+
     let (num_erase, addr_erase) = mt25q.erase(ADDR, LEN);
     assert!(LEN <= num_erase as usize);
     assert!(addr_erase <= ADDR);
@@ -76,7 +80,10 @@ fn memory_example_polling(mt25q: &mut mt25q::Mt25q) {
         assert!(read_buffer[i] == 0xFF);
     }
 
-    // Test write + read
+    ///////////////////////
+    // Test write + read //
+    ///////////////////////
+
     mt25q.write(ADDR, &mut write_buffer, LEN);
     mt25q.read(&mut read_buffer, ADDR, LEN);
     for i in 0..LEN {
@@ -98,36 +105,72 @@ fn memory_example_dma(
     dma: &Handle<DMA2, state::Enabled>,
     stream: Stream7<DMA2>,
 ) {
-    // Create a set of buffers for a memory at address `ADDR` of size `LEN` bytes
+    // Create a buffer in RAM that will mirror flash memory at address `ADDR` of size `LEN`
     const ADDR: u32 = 0x7000;
-    const LEN: usize = 4096;
-    let mut read_buffer: [u8; LEN] = [0; LEN];
-    let mut write_buffer: [u8; LEN] = [0; LEN];
-    for i in 0..LEN {
-        write_buffer[i] = i as u8;
+    const LEN: usize = mt25q::SUBSECTOR_SIZE as usize;
+    static mut READ_BUFFER: [u8; LEN] = [0; LEN];
+
+    // Temporary working memory
+    const PAGE_SIZE: usize = mt25q::PAGE_SIZE as usize;
+    static mut PAGE_BUFFER: [u8; PAGE_SIZE] = [0; PAGE_SIZE];
+
+    // Set the page buffer to some random data
+    unsafe {
+        for i in 0..PAGE_SIZE {
+            PAGE_BUFFER[i] = i as u8;
+        }
     }
 
-    // Test erase + read
+    // Create pinned versions for DMA transfers
+    let mut stream = stream;
+    let mut read_buffer = unsafe { Pin::new(&mut READ_BUFFER) };
+    let mut page_buffer = unsafe { Pin::new(&mut PAGE_BUFFER) };
+
+    ///////////////////////
+    // Test erase + read //
+    ///////////////////////
+
     let (num_erase, addr_erase) = mt25q.erase(ADDR, LEN);
     assert!(LEN <= num_erase as usize);
     assert!(addr_erase <= ADDR);
 
-    let stream = mt25q.read_dma(&mut read_buffer, ADDR, LEN, dma, stream);
+    let read_resources = mt25q.read_dma(read_buffer, ADDR, LEN, dma, stream);
     for i in 0..LEN {
-        assert!(read_buffer[i] == 0xFF);
+        assert!(read_resources.buffer[i] == 0xFF);
+    }
+
+    stream = read_resources.stream;
+    read_buffer = read_resources.buffer;
+
+    ///////////////////////
+    // Test write + read //
+    ///////////////////////
+
+    // For writing with DMA, caller must break the writes down into flash memory pages.
+    // Note that since ADDR is page aligned and LEN is a multiple of the page size some
+    // page boundry math is ignored here. See the polling write function in the `mt25q`
+    // driver for a more advanced example dealing with unaligned page boundries.
+    let mut curr_addr: u32 = ADDR;
+    let mut bytes_written: usize = 0;
+    while bytes_written < LEN {
+        let write_resources = mt25q.write_page_dma(curr_addr, page_buffer, PAGE_SIZE, dma, stream);
+        stream = write_resources.stream;
+        page_buffer = write_resources.buffer;
+        bytes_written += PAGE_SIZE;
+        curr_addr += PAGE_SIZE as u32;
     }
 
-    // Test write + read
-    let stream = mt25q.write_dma(ADDR, &mut write_buffer, LEN, dma, stream);
-    mt25q.read_dma(&mut read_buffer, ADDR, LEN, dma, stream);
+    mt25q.read_dma(read_buffer, ADDR, LEN, dma, stream);
     for i in 0..LEN {
-        if write_buffer[i] != read_buffer[i] {
-            panic!(
-                "Error: Mismatch at address {:X}. Expected {:X} but read {:X}",
-                ADDR + i as u32,
-                write_buffer[i],
-                read_buffer[i]
-            );
+        unsafe {
+            if PAGE_BUFFER[i % PAGE_SIZE] != READ_BUFFER[i] {
+                panic!(
+                    "Error: Mismatch at address {:X}. Expected {:X} but read {:X}",
+                    ADDR + i as u32,
+                    PAGE_BUFFER[i % PAGE_SIZE],
+                    READ_BUFFER[i]
+                );
+            }
         }
     }
 

examples/stm32f7disco-qspi-flash/mt25q.rs

@@ -1,11 +1,14 @@
-//! Basic driver for the MT25QL128ABA. Demonstrates how a flash driver can be
-//! written using the QSPI driver in the HAL.
+//! Basic driver for the MT25QL128ABA. Demonstrates how the QSPI HAL
+//! driver can be used to create a driver for a QSPI flash memory chip.
 
+use as_slice::AsSlice;
+use core::ops::Deref;
+use core::pin::Pin;
 use stm32f7xx_hal::{
-    dma::{Handle, Stream7},
+    dma::{Handle, Stream7, TransferResources},
     gpio::{GpioExt, Speed},
     pac::{DMA2, GPIOB, GPIOD, GPIOE, QUADSPI, RCC},
-    qspi::{Qspi, QspiTransaction, QspiWidth},
+    qspi::{Qspi, QspiTransaction, QspiWidth, RxTx},
     state,
 };
 
@@ -19,8 +22,8 @@ const ID_MANF: u8 = 0x20;
 const ID_MEMT: u8 = 0xBA;
 const ID_MEMC: u8 = 0x18;
 const MAX_ADDR: u32 = 0x00FF_FFFF;
-const SUBSECTOR_SIZE: u32 = 4096;
-const PAGE_SIZE: u32 = 256;
+pub const SUBSECTOR_SIZE: u32 = 4096;
+pub const PAGE_SIZE: u32 = 256;
 
 pub struct Mt25q {
     driver: Qspi,
@@ -86,22 +89,29 @@ impl Mt25q {
         };
 
         let mut id = [0, 0, 0];
-        self.driver.polling_read(&mut id, transaction).unwrap();
+        self.driver.read(&mut id, transaction).unwrap();
 
         if id[0] != ID_MANF || id[1] != ID_MEMT || id[2] != ID_MEMC {
             panic!("Error: Device ID mismatch!");
         }
     }
 
     /// Blocking DMA read.
-    pub fn read_dma(
+    ///
+    /// NOTE: This function could be easily modified for non-blocking by returning
+    /// the handle to the ongoing DMA `Transfer`.
+    pub fn read_dma<B>(
         &mut self,
-        dst: &[u8],
+        dst: Pin<B>,
         src: u32,
         len: usize,
         dma: &Handle<DMA2, state::Enabled>,
         stream: Stream7<DMA2>,
-    ) -> Stream7<DMA2> {
+    ) -> TransferResources<RxTx<QUADSPI>, B>
+    where
+        B: Deref + 'static,
+        B::Target: AsSlice<Element = u8>,
+    {
         assert!(len > 0);
         assert!(src + (len as u32) <= MAX_ADDR);
 
@@ -115,61 +125,63 @@ impl Mt25q {
             data_len: Some(len),
         };
 
-        self.driver.dma_read(dst, transaction, dma, stream).unwrap()
+        // Start the DMA read
+        let rx_transfer = self.driver.read_all(dst, transaction, dma, stream).unwrap();
+
+        // Wait for DMA read to finish
+        rx_transfer.wait(&dma).unwrap()
     }
 
-    /// Blocking DMA write.
-    pub fn write_dma(
+    /// Blocking DMA page write.
+    ///
+    /// NOTE: This function could be easily modified for non-blocking by returning
+    /// the handle to the ongoing DMA `Transfer`. However for this flash chip it
+    /// would not be very useful, since writes are limited by page size. The only
+    /// way to acheive non-blocking writes would be to use interrupts to reload DMA
+    /// for each page.
+    pub fn write_page_dma<B>(
         &mut self,
         dst: u32,
-        src: &[u8],
+        src: Pin<B>,
         len: usize,
         dma: &Handle<DMA2, state::Enabled>,
         stream: Stream7<DMA2>,
-    ) -> Stream7<DMA2> {
+    ) -> TransferResources<RxTx<QUADSPI>, B>
+    where
+        B: Deref + 'static,
+        B::Target: AsSlice<Element = u8>,
+    {
         assert!(len > 0);
         assert!(dst + (len as u32) <= MAX_ADDR);
 
-        let mut outer_idx: usize = 0;
-        let mut curr_addr: u32 = dst;
-        let mut curr_len: usize = len;
-        let mut curr_stream = stream;
-
         // Constraints for writes: (1) Must be <= 256 bytes, (2) must not cross a page boundry
-        while curr_len > 0 {
-            self.write_enable();
+        assert!(len as u32 <= PAGE_SIZE);
+        assert!(dst % PAGE_SIZE == 0);
 
-            let start_page = curr_addr - (curr_addr % PAGE_SIZE);
-            let end_page = start_page + PAGE_SIZE;
-            let size: usize = if curr_addr + (curr_len as u32) > end_page {
-                (end_page - curr_addr) as usize
-            } else {
-                curr_len
-            };
+        self.write_enable();
 
-            let transaction = QspiTransaction {
-                iwidth: QspiWidth::SING,
-                awidth: QspiWidth::SING,
-                dwidth: QspiWidth::QUAD,
-                instruction: CMD_MEM_PROGRAM,
-                address: Some(curr_addr & MAX_ADDR),
-                dummy: 0,
-                data_len: Some(size),
-            };
+        let transaction = QspiTransaction {
+            iwidth: QspiWidth::SING,
+            awidth: QspiWidth::SING,
+            dwidth: QspiWidth::QUAD,
+            instruction: CMD_MEM_PROGRAM,
+            address: Some(dst & MAX_ADDR),
+            dummy: 0,
+            data_len: Some(len),
+        };
 
-            let buf = unsafe { core::slice::from_raw_parts(&src[outer_idx] as *const u8, size) };
-            curr_stream = self
-                .driver
-                .dma_write(buf, transaction, dma, curr_stream)
-                .unwrap();
-            self.poll_status();
+        // Start the DMA write
+        let tx_transfer = self
+            .driver
+            .write_all(src, transaction, dma, stream)
+            .unwrap();
 
-            outer_idx += size;
-            curr_addr += size as u32;
-            curr_len -= size;
-        }
+        // Wait for DMA write to finish
+        let resources = tx_transfer.wait(&dma).unwrap();
+
+        self.poll_status();
 
-        curr_stream
+        resources
     }
 
     /// Blocking polling read.
@@ -187,7 +199,7 @@ impl Mt25q {
             data_len: Some(len),
         };
 
-        self.driver.polling_read(dst, transaction).unwrap();
+        self.driver.read(dst, transaction).unwrap();
     }
 
     /// Blocking polling write.
@@ -222,7 +234,7 @@ impl Mt25q {
             };
 
             let buf = unsafe { core::slice::from_raw_parts(&src[outer_idx] as *const u8, size) };
-            self.driver.polling_write(buf, transaction).unwrap();
+            self.driver.write(buf, transaction).unwrap();
             self.poll_status();
 
             outer_idx += size;
@@ -257,7 +269,7 @@ impl Mt25q {
             };
 
             let mut dummy = [0];
-            self.driver.polling_read(&mut dummy, transaction).unwrap();
+            self.driver.read(&mut dummy, transaction).unwrap();
 
             num_erased_bytes += SUBSECTOR_SIZE;
             addr += SUBSECTOR_SIZE;
@@ -282,9 +294,7 @@ impl Mt25q {
 
         let mut status = [0];
         while status[0] & 0x80 == 0 {
-            self.driver
-                .polling_read(&mut status, transaction.clone())
-                .unwrap();
+            self.driver.read(&mut status, transaction.clone()).unwrap();
         }
     }
 
@@ -301,6 +311,6 @@ impl Mt25q {
         };
 
         let mut dummy = [0];
-        self.driver.polling_read(&mut dummy, transaction).unwrap()
+        self.driver.read(&mut dummy, transaction).unwrap()
     }
 }