sdmmc-protocol

sdmmc-protocol provides no_std SD/MMC protocol building blocks for embedded systems and kernel drivers.

The crate owns protocol-level command construction, response parsing, card initialization flow, and block I/O sequencing. It does not own board setup, MMIO mapping, IRQ routing, DMA allocation, or controller clock-tree setup; keep those in the host-controller crate or OS/platform glue.

It provides:

• SD/MMC command definitions and SPI command packet encoding
• Response types and parsers for common SD, MMC, and SDIO responses
• EXT_CSD helpers for eMMC capacity, bus-width, and timing capability fields
• A SPI-mode SD card driver over a small transport trait
• A SDIO/native-mode host-controller abstraction and driver skeleton
• An optional RDIF block-device bridge for SDIO-backed host crates
• One shared Error type with command/phase context for protocol and host errors

The SPI path has protocol-level unit tests and basic block read/write support. The SDIO path is the integration boundary used by the host crates in this workspace and has been validated end-to-end on the controller / SoC combinations listed under Validated host backends.

Features

[features]
default = ["spi"]
spi = []
sdio = []
rdif = ["sdio", "dep:rdif-block"]

• spi: enables the SPI transport and SpiSdmmc driver.
• sdio: enables the SDIO host abstraction and SdioSdmmc driver.
• rdif: enables the RDIF block-device adapter for SDIO-backed host crates.

Diagnostics use the log crate. Configure a logger in the caller if runtime messages are needed.

SPI Mode

The SPI path is built around SpiTransport plus an embedded_hal::delay::DelayNs implementation that the driver uses for wall-clock timeouts:

use embedded_hal::delay::DelayNs;
use sdmmc_protocol::Error;
use sdmmc_protocol::spi::{SpiSdmmc, SpiTransport};

struct MySpi;

impl SpiTransport for MySpi {
    fn transfer_byte(&mut self, byte: u8) -> Result<u8, Error> {
        // Send one byte on your platform SPI peripheral and return the byte read.
        // Chip-select handling depends on your board/HAL design.
        let _ = byte;
        todo!()
    }
}

fn example<D: DelayNs>(spi: MySpi, delay: D) -> Result<(), Error> {
    let mut card = SpiSdmmc::new(spi, delay);
    let info = card.init()?;

    let mut block = [0u8; 512];
    card.read_block(0, &mut block)?;

    let _is_sdhc_or_sdxc = info.high_capacity;
    let _capacity_blocks = info.capacity_blocks; // Some(blocks) for known CSD versions
    Ok(())
}

If your platform already exposes an embedded-hal 1.0 SpiDevice<u8>, wrap it with SpiDeviceWrapper:

use embedded_hal::delay::DelayNs;
use sdmmc_protocol::spi::{SpiDeviceWrapper, SpiSdmmc};

fn create_driver<SPI, D>(spi: SPI, delay: D) -> SpiSdmmc<SpiDeviceWrapper<SPI>, D>
where
    SPI: embedded_hal::spi::SpiDevice<u8>,
    D: DelayNs,
{
    SpiSdmmc::new(SpiDeviceWrapper::new(spi), delay)
}

SPI Operations

SpiSdmmc currently exposes:

• init()
• read_block(addr, &mut [u8; 512])
• write_block(addr, &[u8; 512])
• read_blocks(addr, count, handler)
• write_blocks(addr, blocks)
• switch_function(cmd)
• switch_to_high_speed()

For SDHC/SDXC cards, block addresses are passed through directly. For SDSC cards, block addresses are converted to byte addresses internally. CRC16 verification for read data is enabled by default and can be changed with set_verify_data_crc.

SDIO Mode

The SDIO path expects the platform to implement SdioHost. The driver tracks the published RCA itself, so hosts no longer need to snoop R6 responses:

use sdmmc_protocol::{Command, CommandResponsePoll, DataCommandPoll, Error, OperationPoll, Response};
use core::task::Waker;
use sdmmc_protocol::sdio::{
    card::SdioSdmmc,
    host::{BusWidth, ClockSpeed, SdioHost},
    init::SdioInitScratch,
};

struct MySdioHost;
struct MyDataRequest<'a>(&'a mut [u8]);

impl SdioHost for MySdioHost {
    type Event = ();
    type DataRequest<'a> = MyDataRequest<'a>;

    fn submit_command(&mut self, cmd: &Command) -> Result<(), Error> {
        let _ = cmd;
        todo!()
    }

    fn poll_command_response(&mut self) -> Result<CommandResponsePoll, Error> {
        todo!()
    }

    fn submit_read_data<'a>(
        &mut self,
        cmd: &Command,
        buf: &'a mut [u8],
        block_size: u32,
        block_count: u32,
    ) -> Result<Self::DataRequest<'a>, Error> {
        let _ = (cmd, block_size, block_count);
        Ok(MyDataRequest(buf))
    }

    fn submit_write_data<'a>(
        &mut self,
        cmd: &Command,
        buf: &'a [u8],
        block_size: u32,
        block_count: u32,
    ) -> Result<Self::DataRequest<'a>, Error> {
        let _ = (cmd, buf, block_size, block_count);
        todo!()
    }

    fn poll_data_request<'a>(
        &mut self,
        request: &mut Self::DataRequest<'a>,
    ) -> Result<DataCommandPoll, Error> {
        let _ = request;
        todo!()
    }

    fn set_bus_width(&mut self, width: BusWidth) -> Result<(), Error> {
        let _ = width;
        todo!()
    }

    fn set_clock(&mut self, speed: ClockSpeed) -> Result<(), Error> {
        let _ = speed;
        todo!()
    }

    fn register_waker(&mut self, waker: &Waker) {
        let _ = waker;
        // Optional: IRQ-driven hosts store this waker and wake it from
        // their OS glue after handle_irq() reports command/data progress.
    }
}

fn example(host: MySdioHost) -> Result<(), Error> {
    let mut card = SdioSdmmc::new(host);
    let mut scratch = SdioInitScratch::new();
    let mut request = card.submit_init(&mut scratch)?;
    let info = loop {
        match card.poll_init_request(&mut request)? {
            OperationPoll::Pending => {
                // Runtime policy belongs here: spin, yield, wait for IRQ, or
                // sleep/timer when request.take_needs_pace() is set.
            }
            OperationPoll::Complete(info) => break info,
        }
    };
    let _rca = info.rca;
    let _capacity_blocks = info.capacity_blocks;
    Ok(())
}

SdioSdmmc detects SD versus eMMC during initialization. SD cards are widened through ACMD6; eMMC cards use EXT_CSD plus CMD6 SWITCH to negotiate bus width and timing where the host supports those modes.

SdioHost follows a submit/poll model. Protocol operations such as card initialization, command status, EXT_CSD reads, MMC switches, switch-function reads, and block I/O expose request objects that callers can poll from a blocking loop, an IRQ wakeup path, a worker, or an async runtime wrapper. SdioSdmmc does not choose the waiting policy; the caller owns whether pending work spins, yields, sleeps, waits for an IRQ, or uses a timer.

Optional wall-clock timeouts

ACMD41 / CMD1 power-up and MMC CMD6 SWITCH busy-waits default to a poll counter that assumes the caller paces poll_* at ~10 ms. Hosts that can expose a monotonic clock should override SdioHost::now_ms() -> Option<u64>: the protocol layer then enforces wall-clock deadlines (1 s for power-up, 250 ms for CMD6) in addition to the poll budget, so timeouts stay accurate no matter how fast or slow the caller polls. Hosts that return None (the default) keep the pure poll-counter behavior.

SDIO module boundaries

The sdio feature is split by capability:

• sdio::host: host-controller capabilities, IRQ events, and bus operations.
• sdio::host2: compatibility adapter for sdio-host2 physical hosts, including request ownership and DMA recovery.
• sdio::card: SdioSdmmc, card information, and ordinary command/block I/O request wrappers.
• sdio::init: initialization scratch storage, probe preference, and the submit/poll initialization state machine.

The historical sdmmc_protocol::sdio::* re-exports remain available for callers that have not migrated to the capability submodules yet.

RDIF Block Bridge

The rdif feature adapts an initialized SdioSdmmc card to rdif-block without pulling OS runtime policy into the protocol crate. Its public modules match the ownership boundary:

• rdif::config: block size constants, BlockConfig, queue limits, device info, card-address translation, and error/transfer-mode helpers.
• rdif::host: the BlockHost capability boundary plus the SdioHost2Adapter request-slot adapter.
• rdif::device: BlockDevice and rdif_block::Interface integration.
• rdif::queue: BlockQueue submit/poll behavior for FIFO and owned-DMA queues.
• rdif::split: FIFO single-block split state.
• rdif::owned: owned-DMA submit, completion, cancel, and shutdown handling.
• rdif::irq: the top-half IRQ bridge, which consumes a host IRQ endpoint and never enters the shared card core.
• rdif::shared_core: the task-context borrow gate shared by device control and queues.

The historical sdmmc_protocol::rdif::* re-exports remain available for compatibility, while new code should prefer the submodule where each capability is defined.

Command Helpers

The cmd module contains helpers for common commands:

• CMD0, CMD2, CMD3_SD, CMD12, CMD38, CMD58
• cmd8(voltage, check_pattern)
• cmd17(addr), cmd18(addr)
• cmd24(addr), cmd25(addr)
• cmd55(rca), cmd41(hcs, voltage_window)
• SDIO helpers such as cmd52(...) and cmd53(...)

Commands can be encoded for SPI with:

let bytes = sdmmc_protocol::cmd::CMD0.to_spi_bytes();
assert_eq!(bytes, [0x40, 0x00, 0x00, 0x00, 0x00, 0x95]);

Testing

Run the default SPI-enabled test suite:

cargo test

Run SDIO-only compilation and tests:

cargo test --no-default-features --features sdio

Run the SDIO plus RDIF block-bridge tests:

cargo test --no-default-features --features sdio,rdif

Run all feature combinations used during development:

cargo fmt --check
cargo test
cargo test --no-default-features --features sdio
cargo test --no-default-features --features sdio,rdif
cargo test --all-features

In this workspace, prefer the project xtask flow for final validation when the crate is part of a larger change:

cargo fmt
cargo xtask clippy --package sdmmc-protocol

Current Limitations

• No real hardware examples are included yet.
• SPI mode targets SD cards; MMC-over-SPI is not a current target.
• SDIO/native mode has card init and block I/O plumbing, but advanced eMMC mode switching is still incomplete.
• UHS-I and HS200 entry depends on host support for voltage switching and tuning. Unsupported host operations return Error::UnsupportedCommand.

Validated host backends

The protocol layer has been exercised on the controller / SoC combinations below through dedicated host crates in this workspace. Modes not listed are either unimplemented in the host backend or have not yet been signed off on real hardware.

See drivers/blk/sdmmc-protocol/docs/REVIEW.md for the remaining 1.0 roadmap (non_exhaustive enums, Display impls, time-base contract, fuzz coverage, SDIO IO-card support, etc.).

License

Licensed under the Apache License, Version 2.0. See LICENSE.