You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@nuttx.apache.org by ac...@apache.org on 2026/03/17 21:14:16 UTC
(nuttx) branch master updated (55e752ada8c -> 3d14873faab)
This is an automated email from the ASF dual-hosted git repository.
acassis pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
from 55e752ada8c Documentation/debugging: add stackusage tool documentation
new 10c75d27224 docs/sdio: clarify 136-bit R2 format
new 0acaf4abf60 docs/sdio: add implementation details for SDIO lower-half
new 5a798be3bac docs/mmcsd: update documentation for SDIO lower-half driver implementation
new dacdb77010e docs/sdio: enhance call-flow documentation for SDIO lower-half
new 3d14873faab docs/sdio: add reference to card initialization flowchart
The 5 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
Documentation/components/drivers/special/mmcsd.rst | 4 +++
Documentation/components/drivers/special/sdio.rst | 42 ++++++++++++++++++++++
include/nuttx/sdio.h | 14 ++++++++
3 files changed, 60 insertions(+)
(nuttx) 01/05: docs/sdio: clarify 136-bit R2 format
Posted by ac...@apache.org.
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 10c75d27224cb9725f5910323a4d6e2da234eb92
Author: Arjav Patel <ar...@gmail.com>
AuthorDate: Mon Mar 16 12:30:46 2026 +0530
docs/sdio: clarify 136-bit R2 format
This update adds comprehensive documentation regarding the 136-bit response format for SDIO, including the structure of the response, CRC handling, and necessary byte-shifting for alignment. This information is crucial for developers implementing or maintaining SDIO drivers.
Signed-off-by: Arjav Patel <ar...@gmail.com>
---
include/nuttx/sdio.h | 14 ++++++++++++++
1 file changed, 14 insertions(+)
diff --git a/include/nuttx/sdio.h b/include/nuttx/sdio.h
index 23a2550ef0b..48b5ff66e52 100644
--- a/include/nuttx/sdio.h
+++ b/include/nuttx/sdio.h
@@ -693,6 +693,20 @@
* status. The driver implementation should verify the correctness of
* the remaining, non-returned bits (CRCs, CMD index, etc.).
*
+ * SDIO_RECVR2 (136-bit response): The 136-bit response has format: start
+ * bit (1), transmission bit (0), 6 reserved bits (all 1), 128 bits of
+ * CID/CSD data, 7-bit CRC, and end bit (1). The upper-half expects the
+ * buffer to contain exactly 128 bits of payload in the standard layout
+ * (e.g., r2[0] contains bits 127-96, r2[1] bits 95-64, etc.).
+ *
+ * The upper-half does not verify the CRC; that is the responsibility of
+ * the lower-half. If the SDMMC controller hardware removes the trailing
+ * CRC byte before storing the response, the resulting 128 bits will be
+ * misaligned (often shifted right by 8 bits with leading zeros). In this
+ * case, the lower-half implementation MUST shift the four 32-bit words
+ * left by one byte to restore the expected 128-bit payload alignment.
+ * See bcm2711_sdio.c or imx9_usdhc.c for examples of this byte-shifting.
+ *
* Input Parameters:
* dev - An instance of the SDIO device interface
* Rx - Buffer in which to receive the response
(nuttx) 02/05: docs/sdio: add implementation details for SDIO lower-half
Posted by ac...@apache.org.
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 <ar...@gmail.com>
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 <ar...@gmail.com>
---
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.
(nuttx) 05/05: docs/sdio: add reference to card initialization flowchart
Posted by ac...@apache.org.
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 3d14873faabd0c7ba2325cdbfe4b2391360cc425
Author: Arjav Patel <ar...@gmail.com>
AuthorDate: Tue Mar 17 21:42:43 2026 +0530
docs/sdio: add reference to card initialization flowchart
This update enhances the SDIO documentation by including a reference to the card initialization flowchart in the MMC/SD physical layer specification. This addition aims to provide implementers with a clearer understanding of the complete card initialization and command sequence.
Signed-off-by: Arjav Patel <ar...@gmail.com>
---
Documentation/components/drivers/special/sdio.rst | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/components/drivers/special/sdio.rst b/Documentation/components/drivers/special/sdio.rst
index 876b6fea2a0..6822b82d388 100644
--- a/Documentation/components/drivers/special/sdio.rst
+++ b/Documentation/components/drivers/special/sdio.rst
@@ -53,6 +53,10 @@ lower-half, a simplified interaction around CMD9 looks like this:
3. ``SDIO_RECVR2``: Retrieve the 136-bit response and provide the
decoded 128-bit CID/CSD payload to the MMCSD upper-half.
+For the complete card initialization and command sequence, refer to the
+card initialization flowchart in the MMC/SD physical layer
+specification.
+
R2 (136-bit) response and CSD/CID
---------------------------------
(nuttx) 04/05: docs/sdio: enhance call-flow documentation for SDIO lower-half
Posted by ac...@apache.org.
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 dacdb77010e4cb7acadb2ba1c012500eea36bf4b
Author: Arjav Patel <ar...@gmail.com>
AuthorDate: Tue Mar 17 15:15:25 2026 +0530
docs/sdio: enhance call-flow documentation for SDIO lower-half
This update clarifies the call-flow for the SDIO lower-half driver implementation by providing a simplified example of the interaction between the MMCSD upper-half and the lower-half. It details the command sequence for handling R2 responses, improving the understanding of the expected behavior during card identification and initialization.
Signed-off-by: Arjav Patel <ar...@gmail.com>
---
Documentation/components/drivers/special/sdio.rst | 17 +++++++++++------
1 file changed, 11 insertions(+), 6 deletions(-)
diff --git a/Documentation/components/drivers/special/sdio.rst b/Documentation/components/drivers/special/sdio.rst
index 6e137f11632..876b6fea2a0 100644
--- a/Documentation/components/drivers/special/sdio.rst
+++ b/Documentation/components/drivers/special/sdio.rst
@@ -38,15 +38,20 @@ 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
----------
+Call-flow (simplified example)
+------------------------------
-The MMCSD upper-half (``drivers/mmcsd/mmcsd_sdio.c``) interacts with the
-lower-half by sending commands and receiving responses:
+The full SDIO/MMCSD call-flow for card identification and initialization
+is more complex and includes additional commands (e.g., CMD0, CMD8,
+ACMD41 / CMD1, CMD2, CMD3, error handling, retries, etc.). For the
+purposes of documenting the R2/CID/CSD handling expected from the
+lower-half, a simplified interaction around CMD9 looks like this:
-1. ``SDIO_SENDCMD``: Send the command (e.g., CMD2, CMD9).
+1. ``SDIO_SENDCMD``: Send the command that yields an R2 response
+ (e.g., CMD2 for CID, CMD9 for CSD).
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).
+3. ``SDIO_RECVR2``: Retrieve the 136-bit response and provide the
+ decoded 128-bit CID/CSD payload to the MMCSD upper-half.
R2 (136-bit) response and CSD/CID
---------------------------------
(nuttx) 03/05: docs/mmcsd: update documentation for SDIO lower-half driver implementation
Posted by ac...@apache.org.
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 5a798be3baca330b32a31ab94359603c163ebe4f
Author: Arjav Patel <ar...@gmail.com>
AuthorDate: Tue Mar 17 15:15:17 2026 +0530
docs/mmcsd: update documentation for SDIO lower-half driver implementation
This update adds a reference to the SDIO Driver Documentation for implementers of SDIO lower-half drivers, emphasizing the importance of understanding R2/CSD response handling and the correct implementation of the lower-half interface.
Signed-off-by: Arjav Patel <ar...@gmail.com>
---
Documentation/components/drivers/special/mmcsd.rst | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/Documentation/components/drivers/special/mmcsd.rst b/Documentation/components/drivers/special/mmcsd.rst
index 5ba08b325b5..2cd2b5d9d0e 100644
--- a/Documentation/components/drivers/special/mmcsd.rst
+++ b/Documentation/components/drivers/special/mmcsd.rst
@@ -4,3 +4,7 @@ MMCSD Device Drivers
- ``include/nuttx/mmcsd.h``. All structures and APIs needed to
work with MMCSD drivers are provided in this header file.
+
+Implementers of SDIO lower-half drivers should refer to the
+:doc:`SDIO Driver Documentation <sdio>` for details on R2/CSD response
+handling and correctly implementing the lower-half interface.