sdmmc_protocol/lib.rs
1//! `no_std` SD/MMC protocol building blocks for embedded systems.
2//!
3//! This crate provides protocol-level types and driver skeletons for SD,
4//! MMC and SDIO cards. It is transport-agnostic at the trait level and
5//! brings its own SPI-mode driver plus an SDIO host-controller abstraction.
6//!
7//! # What you get
8//!
9//! - [`cmd::Command`] / [`cmd::DataDirection`]: SD/MMC command opcodes,
10//! argument encoding and per-command data direction.
11//! - [`response::Response`] and friends ([`response::CidResponse`],
12//! [`response::CsdResponse`], [`response::SwitchStatus`], ...): typed
13//! parsers for the response formats defined in the SD spec.
14//! - [`error::Error`]: a single error enum the drivers and parsers return.
15//! - [`spi`] *(feature `spi`, on by default)*: a [`spi::SpiTransport`] trait
16//! plus the [`spi::SpiSdmmc`] driver for SPI-mode SD cards. Includes a
17//! thin [`spi::SpiDeviceWrapper`] adapter for `embedded-hal` 1.0
18//! `SpiDevice<u8>` implementations.
19//! - [`sdio`] *(feature `sdio`)*: a [`sdio::SdioHost`] trait that abstracts
20//! a host controller and the [`sdio::SdioSdmmc`] driver that drives it
21//! through card initialization, block I/O and bus-speed selection.
22//!
23//! # Cargo features
24//!
25//! | Feature | Default | Purpose |
26//! |----------|---------|-------------------------------------------------|
27//! | `spi` | yes | Enables [`spi::SpiTransport`] and [`spi::SpiSdmmc`]. |
28//! | `sdio` | no | Enables the host trait and submit/poll data-command contract. |
29//!
30//! Diagnostic output goes through the [`log`] crate; configure a logger in
31//! your application to capture it.
32//!
33//! # Example
34//!
35//! ```rust,ignore
36//! use embedded_hal::delay::DelayNs;
37//! use sdmmc_protocol::{
38//! Error,
39//! spi::{SpiSdmmc, SpiTransport},
40//! };
41//!
42//! struct MySpi;
43//!
44//! impl SpiTransport for MySpi {
45//! fn transfer_byte(&mut self, byte: u8) -> Result<u8, Error> {
46//! # let _ = byte;
47//! # Ok(0)
48//! }
49//! }
50//!
51//! fn boot<D: DelayNs>(spi: MySpi, delay: D) -> Result<(), Error> {
52//! let mut card = SpiSdmmc::new(spi, delay);
53//! let _info = card.init()?;
54//! let mut block = [0u8; 512];
55//! card.read_block(0, &mut block)?;
56//! Ok(())
57//! }
58//! ```
59//!
60//! # Maturity
61//!
62//! The SPI path has protocol-level unit tests and basic block read/write
63//! support. The SDIO path has been validated end-to-end against several host
64//! controller / SoC combinations through the dedicated host backends in this
65//! workspace:
66//!
67//! | Host crate | SoC / controller | Mode | Status |
68//! |--------------------|-------------------------|-----------------------|--------|
69//! | `sdhci-host` | RK3568 (dwcmshc) | eMMC HS@52, FIFO/DMA | OK |
70//! | `sdhci-host` | RK3588 (dwcmshc) | eMMC HS@52, FIFO/DMA | OK |
71//! | `dwmmc-host` | RK3568 SD (dw_mshc) | SD HS, DMA | OK |
72//! | `phytium-mci-host` | Phytium MCI | SD HS, DMA | OK |
73//!
74//! UHS-I / HS200 / HS400 paths exist in the state machine but have not yet
75//! been signed off on a real card + IO regulator combination. See
76//! `drivers/blk/sdmmc-protocol/docs/REVIEW.md` for the remaining roadmap.
77//!
78//! # MSRV
79//!
80//! Rust 1.85 (the first stable to ship edition 2024).
81
82#![no_std]
83
84pub mod block;
85pub mod cmd;
86mod common;
87pub mod error;
88pub mod ext_csd;
89pub mod response;
90
91#[cfg(feature = "spi")]
92pub mod spi;
93
94#[cfg(feature = "sdio")]
95pub mod sdio;
96
97pub use block::{
98 BlockBufferConfig, BlockPoll, BlockRequestId, BlockTransferDirection, BlockTransferMode,
99 BlockTransferState, CommandPoll, CommandResponsePoll, DataCommandDirection, DataCommandPoll,
100 DataCommandState, OperationPoll,
101};
102pub use cmd::{Command, DataDirection};
103pub use error::{Error, ErrorContext, Phase};
104pub use response::{CidResponse, CsdResponse, Response, SwitchStatus};