This is an automated email from the ASF dual-hosted git repository. acassis pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/nuttx.git
commit 0acaf4abf6053c9e52fc5350473aef4c05d88412 Author: Arjav Patel <[email protected]> AuthorDate: Mon Mar 16 12:31:25 2026 +0530 docs/sdio: add implementation details for SDIO lower-half This update expands the documentation for implementing an SDIO lower-half driver, detailing the required interface, call-flow, and handling of the R2 response format. It emphasizes the importance of byte-shifting when the CRC is stripped by the hardware, providing reference implementations for clarity. Signed-off-by: Arjav Patel <[email protected]> --- Documentation/components/drivers/special/sdio.rst | 33 +++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/Documentation/components/drivers/special/sdio.rst b/Documentation/components/drivers/special/sdio.rst index d03f8ecedc9..6e137f11632 100644 --- a/Documentation/components/drivers/special/sdio.rst +++ b/Documentation/components/drivers/special/sdio.rst @@ -31,3 +31,36 @@ SDIO Device Drivers - **Examples**: ``arch/arm/src/stm32/stm32_sdio.c`` and ``drivers/mmcsd/mmcsd_sdio.c`` + +Implementing an SDIO lower-half +=============================== + +When implementing a new SDMMC controller driver (SDIO lower-half), it must +provide the interface defined in ``struct sdio_dev_s``. + +Call-flow +--------- + +The MMCSD upper-half (``drivers/mmcsd/mmcsd_sdio.c``) interacts with the +lower-half by sending commands and receiving responses: + +1. ``SDIO_SENDCMD``: Send the command (e.g., CMD2, CMD9). +2. ``SDIO_WAITRESPONSE``: Poll for the hardware to complete the command. +3. ``SDIO_RECVRx``: Retrieve the response bits (e.g., ``SDIO_RECVR2`` for 136-bit). + +R2 (136-bit) response and CSD/CID +--------------------------------- + +The standard R2 response format includes a 7-bit CRC that many hardware +controllers automatically verify and strip. The MMCSD upper-half expects the +provided 128-bit buffer to contain the CID or CSD payload in its standard +layout (bits 127-0). + +If the controller strips the CRC byte, the remaining bits in the hardware +registers are often misaligned (shifted). The lower-half MUST shift the four +32-bit words left by one byte (8 bits) before returning them via ``recv_r2`` +if the CRC is not included in the registers. + +Refer to ``arch/arm64/src/bcm2711/bcm2711_sdio.c`` or +``arch/arm64/src/imx9/imx9_usdhc.c`` for reference implementations of this +shifting logic.
