add async support using bisync crate

This moves the existing API into a `blocking` module and duplicates
the API into a new `asynchronous` module, using `async fn` where
applicable.

Fixes rust-embedded-community#50

Author: Be-ing

CHANGELOG.md

@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 ### Changed
 
+- __Breaking Change__: Existing API moved into `blocking` module. Adjust your imports from `embedded_sdmmc` to `embedded_sdmmc::blocking` to keep old code building.
 - __Breaking Change__: `VolumeManager` now uses interior-mutability (with a `RefCell`) and so most methods are now `&self`. This also makes it easier to open multiple `File`, `Directory` or `Volume` objects at once.
 - __Breaking Change__: The `VolumeManager`, `File`, `Directory` and `Volume` no longer implement `Send` or `Sync.
 - `VolumeManager` uses an interior block cache of 512 bytes, increasing its size by about 520 bytes but hugely reducing stack space required at run-time.
@@ -17,6 +18,7 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 
 ### Added
 
+- Async API in `asynchronous` module
 - `File` now implements the `embedded-io` `Read`, `Write` and `Seek` traits.
 - New `iterate_dir_lfn` method on `VolumeManager` and `Directory` - provides decoded Long File Names as `Option<&str>`
 

Cargo.toml

@@ -14,10 +14,13 @@ version = "0.8.0"
 rust-version = "1.76"
 
 [dependencies]
+bisync = "0.3.0"
 byteorder = {version = "1", default-features = false}
 defmt = {version = "0.3", optional = true}
 embedded-hal = "1.0.0"
+embedded-hal-async = "1.0.0"
 embedded-io = "0.6.1"
+embedded-io-async = "0.6.1"
 heapless = "^0.8"
 log = {version = "0.4", default-features = false, optional = true}
 

examples/append_file.rs

@@ -19,9 +19,9 @@ use linux::*;
 
 const FILE_TO_APPEND: &str = "README.TXT";
 
-use embedded_sdmmc::{Error, Mode, VolumeIdx};
+use embedded_sdmmc::blocking::{Error, Mode, VolumeIdx};
 
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
 fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();

examples/big_dir.rs

@@ -21,9 +21,9 @@
 mod linux;
 use linux::*;
 
-use embedded_sdmmc::{Error, Mode, VolumeIdx};
+use embedded_sdmmc::blocking::{Error, Mode, VolumeIdx};
 
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
 fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();

examples/create_file.rs

@@ -19,9 +19,9 @@ use linux::*;
 
 const FILE_TO_CREATE: &str = "CREATE.TXT";
 
-use embedded_sdmmc::{Error, Mode, VolumeIdx};
+use embedded_sdmmc::blocking::{Error, Mode, VolumeIdx};
 
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
 fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();

examples/delete_file.rs

@@ -22,9 +22,9 @@ use linux::*;
 
 const FILE_TO_DELETE: &str = "README.TXT";
 
-use embedded_sdmmc::{Error, VolumeIdx};
+use embedded_sdmmc::blocking::{Error, VolumeIdx};
 
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
 fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();

examples/linux/mod.rs

@@ -1,7 +1,7 @@
 //! Helpers for using embedded-sdmmc on Linux
 
 use chrono::Timelike;
-use embedded_sdmmc::{Block, BlockCount, BlockDevice, BlockIdx, TimeSource, Timestamp};
+use embedded_sdmmc::blocking::{Block, BlockCount, BlockDevice, BlockIdx, TimeSource, Timestamp};
 use std::cell::RefCell;
 use std::fs::{File, OpenOptions};
 use std::io::prelude::*;

examples/list_dir.rs

@@ -34,12 +34,12 @@
 mod linux;
 use linux::*;
 
-use embedded_sdmmc::{ShortFileName, VolumeIdx};
+use embedded_sdmmc::blocking::{ShortFileName, VolumeIdx};
 
-type Error = embedded_sdmmc::Error<std::io::Error>;
+type Error = embedded_sdmmc::blocking::Error<std::io::Error>;
 
-type Directory<'a> = embedded_sdmmc::Directory<'a, LinuxBlockDevice, Clock, 8, 4, 4>;
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+type Directory<'a> = embedded_sdmmc::blocking::Directory<'a, LinuxBlockDevice, Clock, 8, 4, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
 fn main() -> Result<(), Error> {
     env_logger::init();

examples/read_file.rs

@@ -36,9 +36,9 @@ use linux::*;
 
 const FILE_TO_READ: &str = "README.TXT";
 
-use embedded_sdmmc::{Error, Mode, VolumeIdx};
+use embedded_sdmmc::blocking::{Error, Mode, VolumeIdx};
 
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 4, 4>;
 
 fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();

examples/readme_test.rs

@@ -7,7 +7,7 @@
 
 use core::cell::RefCell;
 
-use embedded_sdmmc::{Error, SdCardError, TimeSource, Timestamp};
+use embedded_sdmmc::blocking::{Error, SdCardError, TimeSource, Timestamp};
 
 pub struct DummyCsPin;
 
@@ -121,7 +121,7 @@ fn main() -> Result<(), MyError> {
     let time_source = FakeTimesource();
     // END Fake stuff that will be replaced with real peripherals
 
-    use embedded_sdmmc::{Mode, SdCard, VolumeIdx, VolumeManager};
+    use embedded_sdmmc::blocking::{Mode, SdCard, VolumeIdx, VolumeManager};
     // Build an SD Card interface out of an SPI device, a chip-select pin and the delay object
     let sdcard = SdCard::new(sdmmc_spi, delay);
     // Get the card size (this also triggers card initialisation because it's not been done yet)

examples/shell.rs

@@ -85,12 +85,12 @@
 
 use std::{cell::RefCell, io::prelude::*};
 
-use embedded_sdmmc::{
+use embedded_sdmmc::blocking::{
     Error as EsError, LfnBuffer, Mode, RawDirectory, RawVolume, ShortFileName, VolumeIdx,
 };
 
-type VolumeManager = embedded_sdmmc::VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4>;
-type Directory<'a> = embedded_sdmmc::Directory<'a, LinuxBlockDevice, Clock, 8, 8, 4>;
+type VolumeManager = embedded_sdmmc::blocking::VolumeManager<LinuxBlockDevice, Clock, 8, 8, 4>;
+type Directory<'a> = embedded_sdmmc::blocking::Directory<'a, LinuxBlockDevice, Clock, 8, 8, 4>;
 
 use crate::linux::{Clock, LinuxBlockDevice};
 

src/blockdevice.rs renamed to src/inner/blockdevice.rs

@@ -3,6 +3,8 @@
 //! Generic code for handling block devices, such as types for identifying
 //! a particular block on a block device by its index.
 
+use super::super::bisync;
+
 /// A standard 512 byte block (also known as a sector).
 ///
 /// IBM PC formatted 5.25" and 3.5" floppy disks, IDE/SATA Hard Drives up to
@@ -75,15 +77,16 @@ impl Default for Block {
 
 /// A block device - a device which can read and write blocks (or
 /// sectors). Only supports devices which are <= 2 TiB in size.
+#[bisync]
 pub trait BlockDevice {
     /// The errors that the `BlockDevice` can return. Must be debug formattable.
     type Error: core::fmt::Debug;
     /// Read one or more blocks, starting at the given block index.
-    fn read(&self, blocks: &mut [Block], start_block_idx: BlockIdx) -> Result<(), Self::Error>;
+    async fn read(&self, blocks: &mut [Block], start_block_idx: BlockIdx) -> Result<(), Self::Error>;
     /// Write one or more blocks, starting at the given block index.
-    fn write(&self, blocks: &[Block], start_block_idx: BlockIdx) -> Result<(), Self::Error>;
+    async fn write(&self, blocks: &[Block], start_block_idx: BlockIdx) -> Result<(), Self::Error>;
     /// Determine how many blocks this device can hold.
-    fn num_blocks(&self) -> Result<BlockCount, Self::Error>;
+    async fn num_blocks(&self) -> Result<BlockCount, Self::Error>;
 }
 
 /// A caching layer for block devices
@@ -96,6 +99,7 @@ pub struct BlockCache<D> {
     block_idx: Option<BlockIdx>,
 }
 
+#[bisync]
 impl<D> BlockCache<D>
 where
     D: BlockDevice,
@@ -110,42 +114,42 @@ where
     }
 
     /// Read a block, and return a reference to it.
-    pub fn read(&mut self, block_idx: BlockIdx) -> Result<&Block, D::Error> {
+    pub async fn read(&mut self, block_idx: BlockIdx) -> Result<&Block, D::Error> {
         if self.block_idx != Some(block_idx) {
             self.block_idx = None;
-            self.block_device.read(&mut self.block, block_idx)?;
+            self.block_device.read(&mut self.block, block_idx).await?;
             self.block_idx = Some(block_idx);
         }
         Ok(&self.block[0])
     }
 
     /// Read a block, and return a reference to it.
-    pub fn read_mut(&mut self, block_idx: BlockIdx) -> Result<&mut Block, D::Error> {
+    pub async fn read_mut(&mut self, block_idx: BlockIdx) -> Result<&mut Block, D::Error> {
         if self.block_idx != Some(block_idx) {
             self.block_idx = None;
-            self.block_device.read(&mut self.block, block_idx)?;
+            self.block_device.read(&mut self.block, block_idx).await?;
             self.block_idx = Some(block_idx);
         }
         Ok(&mut self.block[0])
     }
 
     /// Write back a block you read with [`Self::read_mut`] and then modified.
-    pub fn write_back(&mut self) -> Result<(), D::Error> {
+    pub async fn write_back(&mut self) -> Result<(), D::Error> {
         self.block_device.write(
             &self.block,
             self.block_idx.expect("write_back with no read"),
-        )
+        ).await
     }
 
     /// Write back a block you read with [`Self::read_mut`] and then modified, but to two locations.
     ///
     /// This is useful for updating two File Allocation Tables.
-    pub fn write_back_with_duplicate(&mut self, duplicate: BlockIdx) -> Result<(), D::Error> {
+    pub async fn write_back_with_duplicate(&mut self, duplicate: BlockIdx) -> Result<(), D::Error> {
         self.block_device.write(
             &self.block,
             self.block_idx.expect("write_back with no read"),
-        )?;
-        self.block_device.write(&self.block, duplicate)?;
+        ).await?;
+        self.block_device.write(&self.block, duplicate).await?;
         Ok(())
     }
 
@@ -256,7 +260,7 @@ impl BlockCount {
     /// How many blocks are required to hold this many bytes.
     ///
     /// ```
-    /// # use embedded_sdmmc::BlockCount;
+    /// # use embedded_sdmmc::blocking::BlockCount;
     /// assert_eq!(BlockCount::from_bytes(511), BlockCount(1));
     /// assert_eq!(BlockCount::from_bytes(512), BlockCount(1));
     /// assert_eq!(BlockCount::from_bytes(513), BlockCount(2));

src/fat/bpb.rs renamed to src/inner/fat/bpb.rs

@@ -1,6 +1,6 @@
 //! Boot Parameter Block
 
-use crate::{
+use super::super::{
     blockdevice::BlockCount,
     fat::{FatType, OnDiskDirEntry},
 };

src/fat/info.rs renamed to src/inner/fat/info.rs

@@ -1,4 +1,4 @@
-use crate::{BlockCount, BlockIdx, ClusterId};
+use super::super::{BlockCount, BlockIdx, ClusterId};
 use byteorder::{ByteOrder, LittleEndian};
 
 /// Indentifies the supported types of FAT format

src/fat/mod.rs renamed to src/inner/fat/mod.rs

@@ -33,8 +33,8 @@ pub use volume::{parse_volume, FatVolume, VolumeName};
 #[cfg(test)]
 mod test {
 
+    use super::super::{Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp};
     use super::*;
-    use crate::{Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp};
 
     fn parse(input: &str) -> Vec<u8> {
         let mut output = Vec::new();

src/fat/ondiskdirentry.rs renamed to src/inner/fat/ondiskdirentry.rs

@@ -1,6 +1,8 @@
 //! Directory Entry as stored on-disk
 
-use crate::{fat::FatType, Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp};
+use super::super::{
+    fat::FatType, Attributes, BlockIdx, ClusterId, DirEntry, ShortFileName, Timestamp,
+};
 use byteorder::{ByteOrder, LittleEndian};
 
 /// A 32-byte directory entry as stored on-disk in a directory file.