Introduce a generic Transport trait to support multiple SD card protocols

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog] and this project adheres to [Semantic
 - __Breaking Change__: The `VolumeManager::device` method now takes a callback rather than giving you a reference to the underlying `BlockDevice`
 - __Breaking Change__: `Error:LockError` variant added.
 - __Breaking Change__: `SearchId` was renamed to `Handle`
+- __Breaking Change__: sdcard!: add `Transport` trait, make `SdCard` an abstract of `Transport` other than `SpiDevice<u8>`, refactor internal implementation, add `new_spi` and `new_spi_with_options` functions.
 
 ### Added
 

README.md

@@ -12,7 +12,7 @@ You will need something that implements the `BlockDevice` trait, which can read
 
 ```rust
 // 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::SdCard::new_spi(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.
@@ -46,17 +46,25 @@ By default the `VolumeManager` will initialize with a maximum number of `4` open
 let cont: VolumeManager<_, _, 6, 12, 4> = VolumeManager::new_with_limits(block, time_source);
 ```
 
+### Accessing SD Cards using an SD Host Controller
+
+The `SdCard` type requires something that implements `Transport` in order to speak to the SD Card. We supply a generic `SpiTransport` that implements `Transport` using some underlying user-supplied implementation of `embedded_hal::spi::SpiDevice<u8>`. That will work for most applications.
+
+However, if your MCU has a full SD Host Controller peripheral, and if you need high-performance access to your SD Card, you may wish to instead implement `Transport` in a way that uses that peripheral. SD Host Controllers, for example, often support a 4-bit wide interface instead of the 1-bit wide SPI interface, and run at higher clock rates.
+
 ## Supported features
 
-* Open files in all supported methods from an open directory
-* Open an arbitrary number of directories and files
-* Read data from open files
-* Write data to open files
-* Close files
-* Delete files
-* Iterate root directory
-* Iterate sub-directories
-* Log over defmt or the common log interface (feature flags).
+* Talking to SD Cards over SPI (using the `embedded-hal::spi::SpiDevice` trait)
+* Talking to SD Cards over a custom transport (using our `Transport` trait)
+* Opening files in all supported modes from an open directory
+* Opening an arbitrary number of directories and files
+* Reading data from open files
+* Writing data to open files
+* Closing files
+* Deleting files
+* Iterating the root directory
+* Iterating sub-directories
+* Logging over defmt or the common log interface (see feature flags).
 
 ## No-std usage
 

examples/readme_test.rs

@@ -120,7 +120,7 @@ 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::SdCard::new_spi(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.

src/lib.rs

@@ -25,7 +25,7 @@
 //!     D: embedded_hal::delay::DelayNs,
 //!     T: TimeSource,
 //! {
-//!     let sdcard = SdCard::new(spi, delay);
+//!     let sdcard = SdCard::new_spi(spi, delay);
 //!     println!("Card size is {} bytes", sdcard.num_bytes()?);
 //!     let volume_mgr = VolumeManager::new(sdcard, ts);
 //!     let volume0 = volume_mgr.open_volume(VolumeIdx(0))?;
@@ -92,10 +92,7 @@ pub use crate::filesystem::{
 use filesystem::DirectoryInfo;
 
 #[doc(inline)]
-pub use crate::sdcard::Error as SdCardError;
-
-#[doc(inline)]
-pub use crate::sdcard::SdCard;
+pub use crate::sdcard::{Error as SdCardError, SdCard, SpiTransport, Transport};
 
 mod volume_mgr;
 #[doc(inline)]