Refactor filesystem and volume manager to support async operations

- Updated methods in `directory.rs`, `files.rs`, `lib.rs`, `mod.rs`, and `volume_mgr.rs` to be async.
- Added `maybe_async` attributes to conditionally compile sync/async versions based on feature flags.
- Modified method implementations to await asynchronous calls where necessary.
- Ensured compatibility with both async and sync contexts throughout the filesystem and volume management code.

Author: BL-CZY

Cargo.toml

@@ -1,5 +1,8 @@
 [package]
-authors = ["Jonathan 'theJPster' Pallant <[email protected]>", "Rust Embedded Community Developers"]
+authors = [
+    "Jonathan 'theJPster' Pallant <[email protected]>",
+    "Rust Embedded Community Developers",
+]
 categories = ["embedded", "no-std"]
 description = "A basic SD/MMC driver for Embedded Rust."
 edition = "2021"
@@ -14,12 +17,14 @@ version = "0.9.0"
 rust-version = "1.86"
 
 [dependencies]
-byteorder = {version = "1", default-features = false}
-defmt = {version = "1.0.1", optional = true}
+byteorder = { version = "1", default-features = false }
+defmt = { version = "1.0.1", optional = true }
 embedded-hal = "1.0.0"
 embedded-io = "0.6.1"
+embedded-io-async = "0.6.1"
 heapless = "0.9.1"
-log = {version = "0.4", default-features = false, optional = true}
+log = { version = "0.4", default-features = false, optional = true }
+maybe-async = "0.2.10"
 
 [dev-dependencies]
 chrono = "0.4"
@@ -30,7 +35,8 @@ hex-literal = "1.0.0"
 sha2 = "0.10"
 
 [features]
-default = ["log"]
+default = ["log", "async"]
 defmt-log = ["dep:defmt"]
 log = ["dep:log"]
+async = []
 core-error = []

src/blockdevice.rs

@@ -75,6 +75,7 @@ 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.
+#[cfg(not(feature = "async"))]
 pub trait BlockDevice {
     /// The errors that the `BlockDevice` can return. Must be debug formattable.
     type Error: core::fmt::Debug;
@@ -86,6 +87,30 @@ pub trait BlockDevice {
     fn num_blocks(&self) -> Result<BlockCount, Self::Error>;
 }
 
+/// A block device - a device which can read and write blocks (or
+/// sectors). Only supports devices which are <= 2 TiB in size.
+#[cfg(feature = "async")]
+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,
+    ) -> impl core::future::Future<Output = Result<(), Self::Error>> + Send;
+    /// Write one or more blocks, starting at the given block index.
+    fn write(
+        &self,
+        blocks: &[Block],
+        start_block_idx: BlockIdx,
+    ) -> impl core::future::Future<Output = Result<(), Self::Error>> + Send;
+    /// Determine how many blocks this device can hold.
+    fn num_blocks(
+        &self,
+    ) -> impl core::future::Future<Output = Result<BlockCount, Self::Error>> + Send;
+}
+
 /// A caching layer for block devices
 ///
 /// Caches a single block.
@@ -110,42 +135,54 @@ where
     }
 
     /// Read a block, and return a reference to it.
-    pub fn read(&mut self, block_idx: BlockIdx) -> Result<&Block, D::Error> {
+    #[cfg_attr(feature = "async", maybe_async::must_be_async)]
+    #[cfg_attr(not(feature = "async"), maybe_async::must_be_sync)]
+    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> {
+    #[cfg_attr(feature = "async", maybe_async::must_be_async)]
+    #[cfg_attr(not(feature = "async"), maybe_async::must_be_sync)]
+    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> {
-        self.block_device.write(
-            &self.block,
-            self.block_idx.expect("write_back with no read"),
-        )
+    #[cfg_attr(feature = "async", maybe_async::must_be_async)]
+    #[cfg_attr(not(feature = "async"), maybe_async::must_be_sync)]
+    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> {
-        self.block_device.write(
-            &self.block,
-            self.block_idx.expect("write_back with no read"),
-        )?;
-        self.block_device.write(&self.block, duplicate)?;
+    #[cfg_attr(feature = "async", maybe_async::must_be_async)]
+    #[cfg_attr(not(feature = "async"), maybe_async::must_be_sync)]
+    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"),
+            )
+            .await?;
+        self.block_device.write(&self.block, duplicate).await?;
         Ok(())
     }