ZynqMP ZCU102 SD-card boot fixes

Author: dgarske

config/examples/zynqmp_sdcard.config

@@ -23,6 +23,9 @@ DEBUG_SYMBOLS=1
 DEBUG_UART=1
 CFLAGS_EXTRA+=-DDEBUG_ZYNQ=1
 
+# Display boot timing data
+#BOOT_BENCHMARK?=1
+
 # SD card support - use SDHCI driver
 DISK_SDCARD?=1
 DISK_EMMC?=0
@@ -38,6 +41,7 @@ NO_XIP=1
 
 # ELF loading support
 ELF?=1
+#DEBUG_ELF?=1
 
 # Boot Exception Level: leave wolfBoot at EL2 for handoff to Linux (matches
 # the standard PetaLinux U-Boot flow and preserves KVM/hypervisor use of
@@ -79,7 +83,9 @@ WOLFBOOT_NO_PARTITIONS=1
 CFLAGS_EXTRA+=-DBOOT_PART_A=1
 CFLAGS_EXTRA+=-DBOOT_PART_B=2
 
-# Disk read chunk size (512KB)
+# Disk read chunk size for firmware loading (update_disk.c). 512KB gives the
+# best throughput (~1.4s for 32MB). The SDMA engine handles boundary crossings
+# every 4KB (SDHCI_DMA_THRESHOLD default) within each 512KB chunk.
 CFLAGS_EXTRA+=-DDISK_BLOCK_SIZE=0x80000
 
 # Linux rootfs is on partition 4. Device naming depends on whether both

docs/Targets.md

@@ -2689,6 +2689,25 @@ Set the ZCU102 boot mode switches (SW6) for SD card boot:
 | QSPI32    | 0 0 1 0       | on, on, off, on |
 | SD1       | 1 1 1 0       | off, off, off, on |
 
+**SDHCI Notes (Arasan controller)**
+
+The ZynqMP uses an Arasan SDHCI v3.0 controller. Key considerations:
+
+- **SDMA vs PIO**: The PIO (Programmed I/O) multi-block read path has a race condition on
+  this controller under compiler optimization (`-Os`/`-O2`). The BRR (Buffer Read Ready)
+  flag is re-polled too quickly between blocks, causing stale data reads that corrupt
+  firmware images. The default `SDHCI_DMA_THRESHOLD=4096` forces all multi-block reads
+  through the SDMA path, which avoids this issue entirely.
+- **HV4E redirect**: The Arasan controller does not support Host Version 4 Enable (HV4E).
+  The platform HAL in `hal/zynq.c` transparently redirects SRS22/SRS23 writes to the
+  legacy SRS00 register for 32-bit SDMA addressing.
+- **Card detect**: The Arasan controller does not support CDSS/CDTL card detect test
+  level. `SDHCI_FORCE_CARD_DETECT` is set in the config since FSBL already booted from
+  the same SD card.
+- **`DISK_BLOCK_SIZE`**: Controls the firmware read chunk size in `update_disk.c` (default
+  64KB). This determines the per-read size passed to the SDHCI driver. Must be less than
+  the SDMA buffer boundary (4KB with the default threshold).
+
 **Debug**
 
 Enable SDHCI debug output by uncommenting in the config:

include/sdhci.h

@@ -40,9 +40,16 @@
 #define SDHCI_BLOCK_SIZE        512
 #endif
 
-/* DMA threshold - minimum transfer size to use DMA mode (default: 512KB) */
+/* DMA threshold - minimum transfer size (bytes) to use SDMA instead of PIO.
+ * Default 4KB: forces SDMA for virtually all multi-block CMD18 reads.
+ * The PIO multi-block read path has a known race condition on Arasan SDHCI
+ * controllers (ZynqMP, Versal) where BRR (Buffer Read Ready) is re-checked
+ * too quickly between blocks under compiler optimization (-Os/-O2), causing
+ * stale data reads and firmware integrity failures. Using SDMA avoids the
+ * BRR polling loop entirely.
+ * Override in target .config if a larger PIO window is acceptable. */
 #ifndef SDHCI_DMA_THRESHOLD
-#define SDHCI_DMA_THRESHOLD     (512U * 1024U)
+#define SDHCI_DMA_THRESHOLD     (4U * 1024U)
 #endif
 
 /* Disk test block address (platform should override) */

src/sdhci.c

@@ -1289,7 +1289,22 @@ static int sdhci_transfer(int dir, uint32_t cmd_index, uint32_t block_addr,
     #endif /* !SDHCI_SDMA_DISABLED */
     }
     else {
-        /* Blocking mode - buffer ready flag differs for read vs write */
+        /* PIO (Programmed I/O) mode — reads/writes data word-by-word via
+         * the SRS08 data port register.
+         *
+         * CAUTION: On Arasan SDHCI v3.0 (ZynqMP, Versal), multi-block PIO
+         * reads (CMD18) have a known race condition under compiler
+         * optimization (-Os/-O2). After reading one block, the BRR (Buffer
+         * Read Ready) flag in SRS12 may still be set from the previous
+         * block when the outer loop re-checks it. The optimized code
+         * re-polls so quickly that BRR has not yet auto-cleared, causing
+         * the next 512-byte read from SRS08 to return stale/partial data.
+         * This corrupts the loaded firmware image.
+         *
+         * Workaround: Set SDHCI_DMA_THRESHOLD low (default 4KB) so that
+         * multi-block reads use SDMA instead of this PIO path. The eMMC
+         * path manually clears BRR between blocks (W1C write below),
+         * which also avoids the race. */
         uint32_t buf_ready_flag = (dir == SDHCI_DIR_READ) ?
             SDHCI_SRS12_BRR : SDHCI_SRS12_BWR;
 
@@ -1531,15 +1546,21 @@ int sdhci_init(void)
     }
 
 #ifdef DEBUG_SDHCI
-    {
-        const char *card_type;
-#ifdef DISK_EMMC
-        card_type = "eMMC";
-#else
-        card_type = "SD";
-#endif
-        wolfBoot_printf("sdhci_init: %s status: %d\n", card_type, status);
+    if (status == 0) {
+        wolfBoot_printf("SDHCI: DMA (threshold: %dKB, buf boundary: %dKB)\n",
+            SDHCI_DMA_THRESHOLD / 1024,
+            (4 << ((SDHCI_DMA_BUFF_BOUNDARY >> 12) & 0x7))
+        );
     }
+
+    wolfBoot_printf("SDHCI: %s init, status %d\n",
+    #ifdef DISK_EMMC
+        "eMMC"
+    #else
+        "SD"
+    #endif
+        , status
+    );
 #endif
 
     return status;

src/update_disk.c

@@ -353,6 +353,7 @@ void RAMFUNCTION wolfBoot_start(void)
         pB_ver_u = (uint32_t)pB_ver;
 
     wolfBoot_printf("Versions, A:%u B:%u\r\n", pA_ver_u, pB_ver_u);
+    wolfBoot_printf("Load block size: %dKB\r\n", DISK_BLOCK_SIZE / 1024);
     max_ver = (pB_ver_u > pA_ver_u) ? pB_ver_u : pA_ver_u;
 
     /* Choose partition with higher version */