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

@@ -22,11 +22,11 @@ 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

@@ -3,19 +3,19 @@ extern crate embedded_sdmmc;
 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))
+        .open_volume(VolumeIdx(1))
         .unwrap();
     println!("Volume: {:?}", volume);
     let root_dir = volume.open_root_dir().unwrap();
@@ -28,7 +28,7 @@ fn main() -> Result<(), embedded_sdmmc::Error<std::io::Error>> {
         let file = root_dir
             .open_file_in_dir(
                 file_name.as_str(),
-                embedded_sdmmc::Mode::ReadWriteCreateOrTruncate,
+                Mode::ReadWriteCreateOrTruncate,
             )
             .unwrap();
         let buf = b"hello world, from rust";

examples/create_file.rs

@@ -22,11 +22,11 @@ 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

@@ -25,11 +25,11 @@ 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

@@ -35,12 +35,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

@@ -39,11 +39,11 @@ 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

@@ -80,9 +80,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 embedded_sdmmc::blocking::TimeSource for FakeTimesource {
+    fn get_timestamp(&self) -> embedded_sdmmc::blocking::Timestamp {
+        embedded_sdmmc::blocking::Timestamp {
             year_since_1970: 0,
             zero_indexed_month: 0,
             zero_indexed_day: 0,
@@ -95,18 +95,18 @@ impl embedded_sdmmc::TimeSource for FakeTimesource {
 
 #[derive(Debug, Clone)]
 enum Error {
-    Filesystem(embedded_sdmmc::Error<embedded_sdmmc::SdCardError>),
-    Disk(embedded_sdmmc::SdCardError),
+    Filesystem(embedded_sdmmc::blocking::Error<embedded_sdmmc::blocking::SdCardError>),
+    Disk(embedded_sdmmc::blocking::SdCardError),
 }
 
-impl From<embedded_sdmmc::Error<embedded_sdmmc::SdCardError>> for Error {
-    fn from(value: embedded_sdmmc::Error<embedded_sdmmc::SdCardError>) -> Error {
+impl From<embedded_sdmmc::blocking::Error<embedded_sdmmc::blocking::SdCardError>> for Error {
+    fn from(value: embedded_sdmmc::blocking::Error<embedded_sdmmc::blocking::SdCardError>) -> Error {
         Error::Filesystem(value)
     }
 }
 
-impl From<embedded_sdmmc::SdCardError> for Error {
-    fn from(value: embedded_sdmmc::SdCardError) -> Error {
+impl From<embedded_sdmmc::blocking::SdCardError> for Error {
+    fn from(value: embedded_sdmmc::blocking::SdCardError) -> Error {
         Error::Disk(value)
     }
 }
@@ -120,21 +120,21 @@ fn main() -> Result<(), Error> {
     // END Fake stuff that will be replaced with real peripherals
 
     // 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 = embedded_sdmmc::blocking::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 = embedded_sdmmc::blocking::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(embedded_sdmmc::blocking::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", embedded_sdmmc::blocking::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];