Create and document DummyCsPin for use with e-h1.0

Author: fu5ha

Cargo.toml

@@ -23,6 +23,7 @@ hex-literal = "0.4.1"
 flate2 = "1.0"
 sha2 = "0.10"
 chrono = "0.4"
+embedded-hal-bus = "0.1.0-rc.1"
 
 [features]
 default = ["log"]

examples/readme_test.rs

@@ -3,26 +3,45 @@
 //! We add enough stuff to make it compile, but it won't run because our fake
 //! SPI doesn't do any replies.
 
-struct FakeSpi();
+use core::cell::RefCell;
 
-impl embedded_hal::spi::SpiDevice<u8> for FakeSpi {
+use embedded_sdmmc::sdcard::DummyCsPin;
+
+struct FakeSpiBus();
+
+impl embedded_hal::spi::ErrorType for FakeSpiBus {
     type Error = core::convert::Infallible;
-    fn transfer<'w>(&mut self, words: &'w mut [u8]) -> Result<&'w [u8], Self::Error> {
-        Ok(words)
-    }
 }
 
-impl embedded_hal::spi::SpiDevice<u8> for FakeSpi {
-    type Error = core::convert::Infallible;
-    fn write(&mut self, _words: &[u8]) -> Result<(), Self::Error> {
+impl embedded_hal::spi::SpiBus<u8> for FakeSpiBus {
+    fn read(&mut self, _: &mut [u8]) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    fn write(&mut self, _: &[u8]) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    fn transfer(&mut self, _: &mut [u8], _: &[u8]) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    fn transfer_in_place(&mut self, _: &mut [u8]) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    fn flush(&mut self) -> Result<(), Self::Error> {
         Ok(())
     }
 }
 
 struct FakeCs();
 
-impl embedded_hal::digital::OutputPin for FakeCs {
+impl embedded_hal::digital::ErrorType for FakeCs {
     type Error = core::convert::Infallible;
+}
+
+impl embedded_hal::digital::OutputPin for FakeCs {
     fn set_low(&mut self) -> Result<(), Self::Error> {
         Ok(())
     }
@@ -32,10 +51,11 @@ impl embedded_hal::digital::OutputPin for FakeCs {
     }
 }
 
+#[derive(Clone, Copy)]
 struct FakeDelayer();
 
 impl embedded_hal::delay::DelayUs for FakeDelayer {
-    fn delay_us(&mut self, us: u8) {
+    fn delay_us(&mut self, us: u32) {
         std::thread::sleep(std::time::Duration::from_micros(u64::from(us)));
     }
 }
@@ -74,9 +94,10 @@ impl From<embedded_sdmmc::SdCardError> for Error {
 }
 
 fn main() -> Result<(), Error> {
-    let sdmmc_spi = FakeSpi();
-    let sdmmc_cs = FakeCs();
+    let spi_bus = RefCell::new(FakeSpiBus());
     let delay = FakeDelayer();
+    let sdmmc_spi = embedded_hal_bus::spi::RefCellDevice::new(&spi_bus, DummyCsPin, delay);
+    let sdmmc_cs = FakeCs();
     let time_source = FakeTimesource();
     // 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, sdmmc_cs, delay);

src/sdcard/mod.rs

@@ -21,11 +21,50 @@ use crate::{debug, warn};
 // Types and Implementations
 // ****************************************************************************
 
+/// A dummy "CS pin" that does nothing when set high or low.
+///
+/// Should be used when constructing an [`SpiDevice`] implementation for use with [`SdCard`].
+///
+/// Let the [`SpiDevice`] use this dummy CS pin that does not actually do anything, and pass the
+/// card's real CS pin to [`SdCard`]'s constructor. This allows the driver to have more
+/// fine-grained control of how the CS pin is managed than is allowed by default using the
+/// [`SpiDevice`] trait, which is needed to implement the SD/MMC SPI communication spec correctly.
+///
+/// If you're not sure how to get a [`SpiDevice`], you may use one of the implementations
+/// in the [`embedded-hal-bus`] crate, providing a wrapped version of your platform's HAL-provided
+/// [`SpiBus`] and [`DelayUs`] as well as our [`DummyCsPin`] in the constructor.
+///
+/// [`SpiDevice`]: embedded_hal::spi::SpiDevice
+/// [`SpiBus`]: embedded_hal::spi::SpiBus
+/// [`DelayUs`]: embedded_hal::delay::DelayUs
+/// [`embedded-hal-bus`]: https://docs.rs/embedded-hal-bus
+pub struct DummyCsPin;
+
+impl embedded_hal::digital::ErrorType for DummyCsPin {
+    type Error = core::convert::Infallible;
+}
+
+impl embedded_hal::digital::OutputPin for DummyCsPin {
+    #[inline(always)]
+    fn set_low(&mut self) -> Result<(), Self::Error> {
+        Ok(())
+    }
+
+    #[inline(always)]
+    fn set_high(&mut self) -> Result<(), Self::Error> {
+        Ok(())
+    }
+}
+
 /// Represents an SD Card on an SPI bus.
 ///
-/// Built from an SPI peripheral and a Chip Select pin. We need Chip Select to
-/// be separate so we can clock out some bytes without Chip Select asserted
-/// (which "flushes the SD cards registers" according to the spec).
+/// Built from an [`SpiDevice`] implementation and a Chip Select pin.
+/// Unfortunately, We need control of the chip select pin separately from the [`SpiDevice`]
+/// implementation so we can clock out some bytes without Chip Select asserted
+/// (which is necessary to make the SD card actually release the Spi bus after performing
+/// operations on it, according to the spec). To support this, we provide [`DummyCsPin`]
+/// which should be provided to your chosen [`SpiDevice`] implementation rather than the card's
+/// actual CS pin. Then provide the actual CS pin to [`SdCard`]'s constructor.
 ///
 /// All the APIs take `&self` - mutability is handled using an inner `RefCell`.
 pub struct SdCard<SPI, CS, DELAYER>
@@ -45,6 +84,9 @@ where
 {
     /// Create a new SD/MMC Card driver using a raw SPI interface.
     ///
+    /// See the docs of the [`SdCard`] struct for more information about
+    /// how to construct the needed `SPI` and `CS` types.
+    ///
     /// The card will not be initialised at this time. Initialisation is
     /// deferred until a method is called on the object.
     ///
@@ -55,6 +97,9 @@ where
 
     /// Construct a new SD/MMC Card driver, using a raw SPI interface and the given options.
     ///
+    /// See the docs of the [`SdCard`] struct for more information about
+    /// how to construct the needed `SPI` and `CS` types.
+    ///
     /// The card will not be initialised at this time. Initialisation is
     /// deferred until a method is called on the object.
     pub fn new_with_options(
@@ -573,9 +618,9 @@ where
 
     /// Send one byte and receive one byte over the SPI bus.
     fn transfer_byte(&mut self, out: u8) -> Result<u8, Error> {
-        let mut read_buf = [0u8;1];
+        let mut read_buf = [0u8; 1];
         self.spi
-            .transfer(&mut read_buf,&[out])
+            .transfer(&mut read_buf, &[out])
             .map_err(|_| Error::Transport)?;
         Ok(read_buf[0])
     }
@@ -588,7 +633,9 @@ where
 
     /// Send multiple bytes and replace them with what comes back over the SPI bus.
     fn transfer_bytes(&mut self, in_out: &mut [u8]) -> Result<(), Error> {
-        self.spi.transfer_in_place(in_out).map_err(|_e| Error::Transport)?;
+        self.spi
+            .transfer_in_place(in_out)
+            .map_err(|_e| Error::Transport)?;
         Ok(())
     }
 
@@ -680,7 +727,7 @@ pub enum CardType {
     /// Uses byte-addressing internally, so limited to 2GiB in size.
     SD2,
     /// An high-capacity 'SDHC' Card.
-    ///  
+    ///
     /// Uses block-addressing internally to support capacities above 2GiB.
     SDHC,
 }