extend init example, add docs, ci

Author: robamu

Cargo.toml

@@ -1,3 +1,11 @@
 [workspace]
 resolver = "3"
 members = ["embedded-sdmmc", "embedded-sdmmc-types"]
+
+[workspace.dependencies]
+bitbybit = "2"
+arbitrary-int = "2"
+defmt = "1"
+thiserror = { version = "2", default-features = false }
+bitflags = "2"
+hex-literal = "1"

README.md

@@ -6,9 +6,12 @@ library. It is written in pure-Rust, is `#![no_std]` and does not use `alloc`
 or `collections` to keep the memory footprint low. In the first instance it is
 designed for readability and simplicity over performance.
 
-## Using the crate
+## Using the crate in an application
 
-You will need something that implements the `BlockDevice` trait, which can read and write the 512-byte blocks (or sectors) from your card. If you were to implement this over USB Mass Storage, there's no reason this crate couldn't work with a USB Thumb Drive, but we only supply a `BlockDevice` suitable for reading SD and SDHC cards over SPI.
+You will need something that implements the `BlockDevice` trait, which can read and write the
+512-byte blocks (or sectors) from your card. If you were to implement this over USB Mass Storage,
+there's no reason this crate couldn't work with a USB Thumb Drive, but we only supply a
+`BlockDevice` implementation suitable for reading SD and SDHC cards over SPI.
 
 ```rust
 use embedded_sdmmc::{SdCard, VolumeManager, Mode, VolumeIdx};
@@ -60,6 +63,20 @@ 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);
 ```
 
+## Providing support for the library
+
+If you are a hardware abstraction library author, you might be interested in adding support for
+`embedded-sdmmc` for your SD card interface. This can be done by implementing the `BlockDevice`
+trait provided by the `embedded-sdmmc-types` crate.
+
+The [`sd_card_init` example](./embedded-sdmmc/examples/sd_card_init.rs) provides more information
+on how such an implementation could look like for SD card host controllers. If you are
+interfacing with a SD card via SPI, `embedded-sdmmc` provides an implementation which only
+requires you to provide a SPI driver implementing the
+[`SpiDevice` trait](https://docs.rs/embedded-hal/latest/embedded_hal/spi/trait.SpiDevice.html).
+
+The [`embedded-sdmmc-types` README](./embedded-sdmmc-types/README.md) provides some more information.
+
 ## Supported features
 
 * Open files in all supported methods from an open directory

embedded-sdmmc-types/Cargo.toml

@@ -4,11 +4,11 @@ version = "0.1.0"
 edition = "2024"
 
 [dependencies]
-bitbybit = "2"
-arbitrary-int = "2"
-defmt = { version = "1", optional = true }
-thiserror = { version = "2", default-features = false }
-bitflags = "2"
+bitbybit.workspace = true
+arbitrary-int.workspace = true
+defmt = { workspace = true, optional = true }
+thiserror.workspace = true
+bitflags.workspace = true
 
 [dev-dependencies]
-hex-literal = "1.0.0"
+hex-literal.workspace = true

embedded-sdmmc-types/README.md

@@ -0,0 +1,13 @@
+# Embedded SD/MMC [![crates.io](https://img.shields.io/crates/v/embedded-sdmmc-types.svg)](https://crates.io/crates/embedded-sdmmc-types) [![Documentation](https://docs.rs/embedded-sdmmc-types/badge.svg)](https://docs.rs/embedded-sdmmc-types)
+
+Embedded SD/MMC Types Library
+=======
+
+This library contains some common types and abstractions required for implementing
+support for `embedded-sdmmc` inside your hardware abstraction layer library.
+
+This also allows HAL library to only depend on this library instead of the higher-level
+`embedded-sdmmc` which might have more frequent breaking changes.
+
+Check out the [documentation](https://docs.rs/embedded-sdmmc-types) for more information on the
+available types and traits.

embedded-sdmmc-types/src/blockdevice.rs

@@ -256,7 +256,7 @@ impl BlockCount {
     /// How many blocks are required to hold this many bytes.
     ///
     /// ```
-    /// # use embedded_sdmmc::BlockCount;
+    /// # use embedded_sdmmc_types::blockdevice::BlockCount;
     /// assert_eq!(BlockCount::from_bytes(511), BlockCount(1));
     /// assert_eq!(BlockCount::from_bytes(512), BlockCount(1));
     /// assert_eq!(BlockCount::from_bytes(513), BlockCount(2));

embedded-sdmmc-types/src/lib.rs

@@ -1,6 +1,29 @@
+//! # Embedded SD/MMC Types Library
+//!
+//! This library contains some common types and abstractions required for implementing
+//! support for `embedded-sdmmc` inside your hardware abstraction layer library.
+//!
+//! This also allows HAL library to only depend on this library instead of the higher-level
+//! `embedded-sdmmc` which might have more frequent breaking changes.
+//!
+//! Adding `embedded-sdmmc` support for you SD card structure only involves implementing
+//! the [BlockDevice] trait for your SD card structure. Once you have an initialized SD card
+//! driver structure, implementing this trait is usually relatively easy.
+//!
+//! The [sdcard] module provides various data structures which are useful for implementing
+//! the SD card initialization sequence on a system with a dedicated SD card controller.
+//!
+//! The [`sd_card_init` example](https://github.com/rust-embedded-community/embedded-sdmmc-rs/blob/develop/examples/sd_card_init.rs)
+//! inside the `embedded-sdmmc` library provides an example of how the implementation of both
+//! the initialization sequence and the [BlockDevice] implementation could look like.
 #![no_std]
+#![cfg_attr(docsrs, feature(doc_cfg))]
+#![deny(missing_docs)]
+
 pub mod blockdevice;
 pub mod sdcard;
 
+pub use blockdevice::{Block, BlockCount, BlockDevice, BlockIdx};
+
 #[cfg(test)]
 mod tests {}

embedded-sdmmc-types/src/sdcard/csd.rs

@@ -556,6 +556,8 @@ impl CsdV3 {
 
 #[cfg(test)]
 mod tests {
+    use hex_literal::hex;
+
     use super::*;
 
     #[test]

embedded-sdmmc-types/src/sdcard/mock.rs

@@ -94,7 +94,8 @@ impl From<State> for super::response::State {
 
 /// SD card mock.
 ///
-/// This basically behaves like a virtual SD card. Currently, this mock simulates a Ver2.00 or later
+/// This basically behaves like a virtual SD card controller with a connected virtual SD card.s
+/// Currently, this mock simulates a Ver2.00 or later
 /// SDHC memory card. As such, it responds to the CMD8 command as well. Furthermore, while this
 /// mock is capable of performing a transition until the [super::response::State::Tran] transmission
 /// state is reached, it does not implement / mock file operations yet.
@@ -232,6 +233,35 @@ impl SdCardMock {
         }
     }
 
+    /// Current state of the SD card. A library implementation of this function would send CMD13 to
+    /// retrieve the card status, which contains the current SD card state.
+    pub fn read_current_state(&self) -> State {
+        self.state
+    }
+
+    /// Hypotehtical function to write a word of data, assuming that the controller hardware has
+    /// something like a FIFO.
+    ///
+    /// Other hardware implementations might also use DMA.
+    pub fn write_data_word(&mut self, _word: u32) {}
+
+    /// Hypotehtical function to read a word of data, assuming that the controller hardware has
+    /// something like a FIFO.
+    ///
+    /// Other hardware implementations might also use DMA.
+    pub fn read_data_word(&mut self) -> u32 {
+        0
+    }
+
+    /// Hypothetical function which  retruns whether a RX word can be read.
+    pub fn word_available(&self) -> bool {
+        true
+    }
+
+    /// Hypothetical function which waits for the SD casrd controller to complete the TX data
+    /// transfer.
+    pub fn wait_until_data_transfer_done(&self) {}
+
     /// Read [u32] reply from the SD card mock.
     pub fn read_reply_u32(&self) -> u32 {
         u32::from_be_bytes(self.reply_buf[0..4].try_into().unwrap())

embedded-sdmmc-types/src/sdcard/mod.rs

@@ -1,9 +1,9 @@
 //! SD card support module.
 pub mod argument;
-pub mod response;
 pub mod cid;
 pub mod csd;
 pub mod mock;
+pub mod response;
 
 /// The different types of card we support.
 #[cfg_attr(feature = "defmt", derive(defmt::Format))]
@@ -147,6 +147,8 @@ pub fn crc16(data: &[u8]) -> u16 {
 
 #[cfg(test)]
 mod test {
+    use hex_literal::hex;
+
     use super::*;
     use crate::sdcard::csd::*;
 

embedded-sdmmc/Cargo.toml

@@ -15,28 +15,29 @@ rust-version = "1.87"
 
 [dependencies]
 byteorder = {version = "1", default-features = false}
-defmt = {version = "1.0.1", optional = true}
+defmt = { workspace = true, optional = true }
 embedded-hal = "1.0.0"
 embedded-io = "0.7"
-bitbybit = "2"
-arbitrary-int = "2"
+bitbybit.workspace = true
+arbitrary-int.workspace = true
 bitflags = "2"
 heapless = "0.9.1"
-log = { version = "0.4", default-features = false, optional = true}
-thiserror = { version = "2", default-features = false}
+log = { version = "0.4", default-features = false, optional = true }
+thiserror.workspace = true
 embedded-sdmmc-types = { version = "0.1", path = "../embedded-sdmmc-types" }
+hex-literal = "1"
 
 [dev-dependencies]
 chrono = "0.4"
 embedded-hal-bus = "0.3.0"
 env_logger = "0.11.8"
 flate2 = "1.0"
-hex-literal = "1.0.0"
-sha2 = "0.10"
+sha2 = "0.11"
 anyhow = "1"
+hex-literal.workspace = true
 
 [features]
 default = ["log"]
-defmt-log = ["dep:defmt", "arbitrary-int/defmt"]
+defmt-log = ["dep:defmt", "arbitrary-int/defmt", "embedded-sdmmc-types/defmt"]
 log = ["dep:log"]