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 #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.2.3"
 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

@@ -5,28 +5,25 @@
 //! $ cargo run --example append_file -- /dev/mmcblk0
 //! ```
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example append_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 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<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());

examples/big_dir.rs

@@ -1,22 +1,38 @@
-extern crate embedded_sdmmc;
+//! Big Directory Example.
+//!
+//! Attempts to create an infinite number of files in the root directory of the
+//! first volume of the given block device. This is basically to see what
+//! happens when the root directory runs out of space.
+//!
+//! ```bash
+//! $ cargo run --example big_dir -- ./disk.img
+//! $ cargo run --example big_dir -- /dev/mmcblk0
+//! ```
+//!
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
+//!
+//! ```bash
+//! zcat ./tests/disk.img.gz > ./disk.img
+//! $ cargo run --example big_dir -- ./disk.img
+//! ```
 
 mod linux;
 use linux::*;
 
-use embedded_sdmmc::Error;
+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<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());
     let print_blocks = args.find(|x| x == "-v").map(|_| true).unwrap_or(false);
     let lbd = LinuxBlockDevice::new(filename, print_blocks).map_err(Error::DeviceError)?;
     let volume_mgr: VolumeManager = VolumeManager::new_with_limits(lbd, Clock, 0xAA00_0000);
-    let volume = volume_mgr
-        .open_volume(embedded_sdmmc::VolumeIdx(1))
-        .unwrap();
+    let volume = volume_mgr.open_volume(VolumeIdx(0)).unwrap();
     println!("Volume: {:?}", volume);
     let root_dir = volume.open_root_dir().unwrap();
 
@@ -26,10 +42,7 @@ fn main() -> Result<(), embedded_sdmmc::Error<std::io::Error>> {
         let file_name = format!("{}.da", file_num);
         println!("opening file {file_name} for writing");
         let file = root_dir
-            .open_file_in_dir(
-                file_name.as_str(),
-                embedded_sdmmc::Mode::ReadWriteCreateOrTruncate,
-            )
+            .open_file_in_dir(file_name.as_str(), Mode::ReadWriteCreateOrTruncate)
             .unwrap();
         let buf = b"hello world, from rust";
         println!("writing to file");

examples/create_file.rs

@@ -5,28 +5,25 @@
 //! $ cargo run --example create_file -- /dev/mmcblk0
 //! ```
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example create_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 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<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());

examples/delete_file.rs

@@ -8,28 +8,25 @@
 //! NOTE: THIS EXAMPLE DELETES A FILE CALLED README.TXT. IF YOU DO NOT WANT THAT
 //! FILE DELETED FROM YOUR DISK IMAGE, DO NOT RUN THIS EXAMPLE.
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example delete_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 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<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());

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

@@ -22,10 +22,9 @@
 //! $
 //! ```
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
@@ -35,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

@@ -22,28 +22,25 @@
 //! 00000100 [54, 0a, 0d]                                                     |T...............|
 //! ```
 //!
-//! If you pass a block device it should be unmounted. No testing has been
-//! performed with Windows raw block devices - please report back if you try
-//! this! There is a gzipped example disk image which you can gunzip and test
-//! with if you don't have a suitable block device.
+//! If you pass a block device it should be unmounted. There is a gzipped
+//! example disk image which you can gunzip and test with if you don't have a
+//! suitable block device.
 //!
 //! ```bash
 //! zcat ./tests/disk.img.gz > ./disk.img
 //! $ cargo run --example read_file -- ./disk.img
 //! ```
 
-extern crate embedded_sdmmc;
-
 mod linux;
 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<(), embedded_sdmmc::Error<std::io::Error>> {
+fn main() -> Result<(), Error<std::io::Error>> {
     env_logger::init();
     let mut args = std::env::args().skip(1);
     let filename = args.next().unwrap_or_else(|| "/dev/mmcblk0".into());

examples/readme_test.rs

@@ -7,6 +7,8 @@
 
 use core::cell::RefCell;
 
+use embedded_sdmmc::blocking::{Error, SdCardError, TimeSource, Timestamp};
+
 pub struct DummyCsPin;
 
 impl embedded_hal::digital::ErrorType for DummyCsPin {
@@ -80,9 +82,9 @@ impl embedded_hal::delay::DelayNs for FakeDelayer {
 
 struct FakeTimesource();
 
-impl embedded_sdmmc::TimeSource for FakeTimesource {
-    fn get_timestamp(&self) -> embedded_sdmmc::Timestamp {
-        embedded_sdmmc::Timestamp {
+impl TimeSource for FakeTimesource {
+    fn get_timestamp(&self) -> Timestamp {
+        Timestamp {
             year_since_1970: 0,
             zero_indexed_month: 0,
             zero_indexed_day: 0,
@@ -94,47 +96,48 @@ impl embedded_sdmmc::TimeSource for FakeTimesource {
 }
 
 #[derive(Debug, Clone)]
-enum Error {
-    Filesystem(embedded_sdmmc::Error<embedded_sdmmc::SdCardError>),
-    Disk(embedded_sdmmc::SdCardError),
+enum MyError {
+    Filesystem(Error<SdCardError>),
+    Disk(SdCardError),
 }
 
-impl From<embedded_sdmmc::Error<embedded_sdmmc::SdCardError>> for Error {
-    fn from(value: embedded_sdmmc::Error<embedded_sdmmc::SdCardError>) -> Error {
-        Error::Filesystem(value)
+impl From<Error<SdCardError>> for MyError {
+    fn from(value: Error<SdCardError>) -> MyError {
+        MyError::Filesystem(value)
     }
 }
 
-impl From<embedded_sdmmc::SdCardError> for Error {
-    fn from(value: embedded_sdmmc::SdCardError) -> Error {
-        Error::Disk(value)
+impl From<SdCardError> for MyError {
+    fn from(value: SdCardError) -> MyError {
+        MyError::Disk(value)
     }
 }
 
-fn main() -> Result<(), Error> {
+fn main() -> Result<(), MyError> {
     // BEGIN Fake stuff that will be replaced with real peripherals
     let spi_bus = RefCell::new(FakeSpiBus());
     let delay = FakeDelayer();
     let sdmmc_spi = embedded_hal_bus::spi::RefCellDevice::new(&spi_bus, DummyCsPin, delay).unwrap();
     let time_source = FakeTimesource();
     // END Fake stuff that will be replaced with real peripherals
 
+    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 = embedded_sdmmc::SdCard::new(sdmmc_spi, delay);
+    let sdcard = SdCard::new(sdmmc_spi, delay);
     // Get the card size (this also triggers card initialisation because it's not been done yet)
     println!("Card size is {} bytes", sdcard.num_bytes()?);
     // Now let's look for volumes (also known as partitions) on our block device.
     // To do this we need a Volume Manager. It will take ownership of the block device.
-    let volume_mgr = embedded_sdmmc::VolumeManager::new(sdcard, time_source);
+    let volume_mgr = VolumeManager::new(sdcard, time_source);
     // Try and access Volume 0 (i.e. the first partition).
     // The volume object holds information about the filesystem on that volume.
-    let volume0 = volume_mgr.open_volume(embedded_sdmmc::VolumeIdx(0))?;
+    let volume0 = volume_mgr.open_volume(VolumeIdx(0))?;
     println!("Volume 0: {:?}", volume0);
     // Open the root directory (mutably borrows from the volume).
     let root_dir = volume0.open_root_dir()?;
     // Open a file called "MY_FILE.TXT" in the root directory
     // This mutably borrows the directory.
-    let my_file = root_dir.open_file_in_dir("MY_FILE.TXT", embedded_sdmmc::Mode::ReadOnly)?;
+    let my_file = root_dir.open_file_in_dir("MY_FILE.TXT", Mode::ReadOnly)?;
     // Print the contents of the file, assuming it's in ISO-8859-1 encoding
     while !my_file.is_eof() {
         let mut buffer = [0u8; 32];
@@ -143,6 +146,7 @@ fn main() -> Result<(), Error> {
             print!("{}", *b as char);
         }
     }
+
     Ok(())
 }