Fixes for Xilinx ZynqMP ZCU102 SD card boot with Linux

Five targeted changes required to cleanly boot a PetaLinux 2025.2
fitImage from SD card on the Xilinx ZCU102 (Zynq UltraScale+ MPSoC):

1. hal/zynq: implement hal_dts_fixup() to patch /chosen/bootargs in the
   DTB at runtime. Previously a TODO stub; now mirrors the Versal
   implementation. Uses LINUX_BOOTARGS / LINUX_BOOTARGS_ROOT to override
   the PetaLinux-baked root= value, allowing wolfBoot's A/B partition
   layout (where rootfs is on mmcblk0p4, not p2).

2. hal/zynq: add hal_get_timer_us() using the ARMv8 generic timer
   (CNTPCT_EL0 / CNTFRQ_EL0). Required so sdhci.c udelay() works. Uses
   a __uint128_t intermediate to avoid overflow of (count * 1e6) at
   long uptimes.

3. src/sdhci: fix CMD0 cold-boot timeout on Arasan SDHCI v3.0. Add 1ms
   udelay after sdhci_platform_init(), 1ms after sdhci_set_clock(400KHz),
   1ms after successful power-on, and a 10-retry loop with 10ms udelay
   between retries around the initial CMD0. Gate the CMD0 loop on
   sdhci_set_power() success so power-set failures are not silently
   masked. Without these delays, CMD0 races the SD card power-up when
   DEBUG_SDHCI printf delays are not present.

4. src/boot_aarch64: clean D-cache to PoC and disable MMU + I/D-cache at
   EL2 before jumping to Linux. ARM64 Linux boot protocol requires MMU
   off and image cleaned to PoC; otherwise arm64_panic_block_init()
   panics with 'Non-EFI boot detected with MMU and caches enabled'. Adds
   el2_cleanup_and_jump_to_linux() asm helper (dc cisw loop + ic iallu +
   SCTLR_EL2.{M,C,I} clear + br) called from do_boot() when
   current_el() == 2. Gated on defined(MMU) && defined(LINUX_BOOTARGS_ROOT)
   so bare-metal / RTOS EL2 payloads fall through to the legacy direct
   br x4 path.

5. src/boot_aarch64: include the platform HAL header (hal/zynq.h,
   hal/nxp_ls1028a.h) alongside the existing hal/versal.h include, so
   EL2_HYPERVISOR is visible to do_boot(). Previously BOOT_EL1=1 was
   silently inert on zynq/ls1028a because the symbol was only defined
   in a header not pulled into boot_aarch64.c.

Also:
- config/examples/zynqmp_sdcard.config: default BOOT_EL1 off (EL2 handoff
  for Linux), DEBUG off, and root=/dev/mmcblk0p4 with a comment on
  mmcblk0 vs mmcblk1 enumeration depending on which SDHCI controllers
  are enabled in the XSA / device tree.
- hal/versal.c: align default LINUX_BOOTARGS_ROOT (mmcblk0p2 -> mmcblk0p4)
  with the new wolfBoot A/B partition convention.

Author: dgarske

config/examples/zynqmp_sdcard.config

@@ -18,7 +18,7 @@ HASH?=SHA3
 IMAGE_HEADER_SIZE?=1024
 
 # Debug options
-DEBUG?=1
+DEBUG?=0
 DEBUG_SYMBOLS=1
 DEBUG_UART=1
 CFLAGS_EXTRA+=-DDEBUG_ZYNQ=1
@@ -39,8 +39,12 @@ NO_XIP=1
 # ELF loading support
 ELF?=1
 
-# Boot Exception Level: transition from EL2 -> EL1 before jumping to app
-BOOT_EL1?=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
+# EL2). The EL2 Linux-cleanup path in do_boot() will clean dcache/disable
+# MMU before jumping to the kernel. To drop to EL1 via ERET instead, set
+# BOOT_EL1?=1 (requires EL2_HYPERVISOR=1, which is the hal/zynq.h default).
+#BOOT_EL1?=1
 
 # General options
 VTOR?=1
@@ -78,8 +82,13 @@ CFLAGS_EXTRA+=-DBOOT_PART_B=2
 # Disk read chunk size (512KB)
 CFLAGS_EXTRA+=-DDISK_BLOCK_SIZE=0x80000
 
-# Linux rootfs is on partition 4 (SD1 = mmcblk1)
-CFLAGS_EXTRA+=-DLINUX_BOOTARGS_ROOT=\"/dev/mmcblk1p4\"
+# Linux rootfs is on partition 4. Device naming depends on whether both
+# ZynqMP SDHCI controllers are enabled in the XSA / device tree:
+#   * both sdhci0 + sdhci1 enabled        -> SD1 = /dev/mmcblk1
+#   * only sdhci1 enabled (ZCU102 default -> only external SD populated)
+#     -> SD1 = /dev/mmcblk0
+# Check `ls /sys/class/mmc_host/` on your running target to confirm.
+CFLAGS_EXTRA+=-DLINUX_BOOTARGS_ROOT=\"/dev/mmcblk0p4\"
 
 # ============================================================================
 # Boot Memory Layout

hal/versal.c

@@ -66,7 +66,7 @@
 /* Linux kernel command line arguments */
 #ifndef LINUX_BOOTARGS
 #ifndef LINUX_BOOTARGS_ROOT
-#define LINUX_BOOTARGS_ROOT "/dev/mmcblk0p2"
+#define LINUX_BOOTARGS_ROOT "/dev/mmcblk0p4"
 #endif
 
 #define LINUX_BOOTARGS \

hal/zynq.c

@@ -57,6 +57,18 @@
     /* QSPI bare-metal */
 #endif
 
+/* DTB fixup for kernel command line. Override LINUX_BOOTARGS or
+ * LINUX_BOOTARGS_ROOT in your config to customize. */
+#ifdef __WOLFBOOT
+#ifndef LINUX_BOOTARGS
+#ifndef LINUX_BOOTARGS_ROOT
+#define LINUX_BOOTARGS_ROOT "/dev/mmcblk0p4"
+#endif
+#define LINUX_BOOTARGS \
+    "earlycon console=ttyPS0,115200 root=" LINUX_BOOTARGS_ROOT " rootwait"
+#endif
+#endif /* __WOLFBOOT */
+
 /* QSPI Slave Device Information */
 typedef struct QspiDev {
     uint32_t mode;   /* GQSPI_GEN_FIFO_MODE_SPI, GQSPI_GEN_FIFO_MODE_DSPI or GQSPI_GEN_FIFO_MODE_QSPI */
@@ -1796,6 +1808,19 @@ void RAMFUNCTION ext_flash_unlock(void)
 }
 
 #ifdef MMU
+/* Get current time in microseconds using ARMv8 generic timer */
+uint64_t hal_get_timer_us(void)
+{
+    uint64_t count, freq;
+    __asm__ volatile("mrs %0, CNTPCT_EL0" : "=r"(count));
+    __asm__ volatile("mrs %0, CNTFRQ_EL0" : "=r"(freq));
+    if (freq == 0)
+        return 0;
+    /* Use __uint128_t to avoid overflow of (count * 1e6) at long uptimes
+     * (would overflow uint64_t after ~51h at 100MHz). */
+    return (uint64_t)(((__uint128_t)count * 1000000ULL) / freq);
+}
+
 void* hal_get_dts_address(void)
 {
 #ifdef WOLFBOOT_DTS_BOOT_ADDRESS
@@ -1809,8 +1834,46 @@ void* hal_get_dts_address(void)
 
 int hal_dts_fixup(void* dts_addr)
 {
-    /* place FDT fixup specific to ZynqMP here */
-    //fdt_set_boot_cpuid_phys(buf, fdt_boot_cpuid_phys(fdt));
+    int off, ret;
+    struct fdt_header *fdt = (struct fdt_header *)dts_addr;
+
+    /* Verify FDT header */
+    ret = fdt_check_header(dts_addr);
+    if (ret != 0) {
+        wolfBoot_printf("FDT: Invalid header! %d\n", ret);
+        return ret;
+    }
+
+    wolfBoot_printf("FDT: Version %d, Size %d\n",
+        fdt_version(fdt), fdt_totalsize(fdt));
+
+    /* NOTE: We intentionally do not call fdt_set_totalsize() to "grow" the
+     * DTB here - that only edits the header field, not the backing buffer.
+     * Relies on the load-address layout leaving physical headroom after
+     * the DTB (WOLFBOOT_LOAD_DTS_ADDRESS with the kernel loaded much
+     * higher). If a future config shrinks that gap, mutation calls below
+     * will return -FDT_ERR_NOSPACE and we bail. */
+
+    /* Find /chosen node */
+    off = fdt_find_node_offset(fdt, -1, "chosen");
+    if (off < 0) {
+        /* Create /chosen node if it doesn't exist */
+        off = fdt_add_subnode(fdt, 0, "chosen");
+    }
+    if (off < 0) {
+        wolfBoot_printf("FDT: Failed to find/create chosen node (%d)\n", off);
+        return off;
+    }
+
+    /* Set bootargs property - overrides PetaLinux default root= with
+     * the wolfBoot partition layout. */
+    wolfBoot_printf("FDT: Setting bootargs: %s\n", LINUX_BOOTARGS);
+    ret = fdt_fixup_str(fdt, off, "chosen", "bootargs", LINUX_BOOTARGS);
+    if (ret < 0) {
+        wolfBoot_printf("FDT: Failed to set bootargs (%d)\n", ret);
+        return ret;
+    }
+
     return 0;
 }
 #endif

src/boot_aarch64.c

@@ -26,9 +26,16 @@
 #include "printf.h"
 #include "wolfboot/wolfboot.h"
 
-/* Include platform-specific header for EL configuration defines */
-#ifdef TARGET_versal
+/* Include platform-specific header for EL configuration defines
+ * (EL2_HYPERVISOR, etc.). Must be visible here so the BOOT_EL1 /
+ * EL2_HYPERVISOR guards around the EL2->EL1 ERET transition below
+ * compile in for the active target. */
+#if defined(TARGET_versal)
 #include "hal/versal.h"
+#elif defined(TARGET_zynq)
+#include "hal/zynq.h"
+#elif defined(TARGET_ls1028a)
+#include "hal/nxp_ls1028a.h"
 #endif
 
 /* Linker exported variables */
@@ -43,6 +50,15 @@ extern unsigned int _end_data;
 extern void main(void);
 extern void gicv2_init_secure(void);
 
+/* Asm helper in boot_aarch64_start.S: cleans the entire D-cache to PoC,
+ * disables MMU + I-cache + D-cache via SCTLR_EL2, and branches to a Linux
+ * kernel entry point with the DTB pointer in x0. Required because wolfBoot's
+ * EL2 startup enables MMU/caches for its own use, and the ARM64 Linux boot
+ * protocol requires them OFF at entry. Only built when EL2_HYPERVISOR == 1
+ * is visible to boot_aarch64_start.S (e.g. via hal/zynq.h on ZynqMP). */
+extern void el2_cleanup_and_jump_to_linux(uintptr_t entry, uintptr_t dtb)
+    __attribute__((noreturn));
+
 /* SKIP_GIC_INIT - Skip GIC initialization before booting app
  * This is needed for:
  * - Versal: Uses GICv3, not GICv2. BL31 handles GIC setup.
@@ -163,7 +179,25 @@ void RAMFUNCTION do_boot(const uint32_t *app_offset)
         el2_to_el1_boot((uintptr_t)app_offset, dts);
     }
 #else
-    /* Stay at current EL (EL2 or EL3) and jump directly to application */
+    /* Stay at current EL (EL2 or EL3) and jump directly to application.
+     *
+     * When booting a Linux kernel at EL2 we MUST clean dcache to PoC and
+     * disable MMU/I+D-cache before entry, or Linux's
+     * arm64_panic_block_init() panics with "Non-EFI boot detected with MMU
+     * and caches enabled". This Linux-specific path is gated on
+     * LINUX_BOOTARGS_ROOT being defined (supplied via CFLAGS by configs
+     * that boot Linux, e.g. zynqmp_sdcard.config). Bare-metal / RTOS EL2
+     * payloads fall through to the legacy direct br x4 below. */
+#if defined(MMU) && defined(LINUX_BOOTARGS_ROOT)
+    if (current_el() == 2) {
+        uintptr_t dts = (uintptr_t)dts_offset;
+        wolfBoot_printf("do_boot: cleaning caches, disabling MMU, jumping to Linux\n");
+        el2_cleanup_and_jump_to_linux((uintptr_t)app_offset, dts);
+        /* unreachable */
+    }
+#endif
+
+    /* Non-Linux EL2 and EL3 path: legacy direct br x4 */
 
     /* Set application address via x4 */
     asm volatile("mov x4, %0" : : "r"(app_offset));

src/boot_aarch64_start.S

@@ -1334,4 +1334,125 @@ el2_to_el1_boot:
     b      .
 #endif /* BOOT_EL1 && EL2_HYPERVISOR */
 
+
+/*
+ * Clean entire D-cache to the Point of Coherency (PoC), invalidate the
+ * I-cache to the Point of Unification (PoU), disable MMU + I/D-cache at
+ * EL2, then branch to a Linux kernel entry point with the DTB pointer
+ * in x0.
+ *
+ * Terminology (ARM ARM B2.8):
+ *   PoC - Point of Coherency: the point at which all observers (CPUs,
+ *         DMA masters, etc.) see the same memory. Cleaning to PoC
+ *         guarantees the image bytes we memcpy'd are visible to the
+ *         kernel's first uncached instruction fetches.
+ *   PoU - Point of Unification: the point at which instruction and data
+ *         caches converge. Invalidating I-cache to PoU ensures stale
+ *         fetches are discarded before we hand off.
+ *
+ * The ARM64 Linux boot protocol (Documentation/arch/arm64/booting.rst)
+ * REQUIRES the kernel to be entered with MMU off, D-cache off, and the
+ * loaded image cleaned to PoC. Linux's arm64_panic_block_init() panics
+ * with "Non-EFI boot detected with MMU and caches enabled" if it detects
+ * MMU/caches were on at entry.
+ *
+ * wolfBoot's startup (line ~347 above) enables MMU+I+D cache at EL2 for
+ * its own use. This helper undoes that just before handing off to Linux.
+ *
+ * Parameters:
+ *   x0 = kernel entry point
+ *   x1 = device tree blob address
+ *
+ * Clobbers x0-x11, x29, x30; never returns.
+ */
+.global el2_cleanup_and_jump_to_linux
+el2_cleanup_and_jump_to_linux:
+    /* Save entry/dtb out of the clobber range used by the dcache loop */
+    mov     x29, x0                 /* x29 = entry */
+    mov     x30, x1                 /* x30 = dtb   */
+
+    /* ---- 1. Clean & invalidate entire data cache to PoC by set/way ----
+     * Standard ARMv8 routine, adapted from arm-trusted-firmware /
+     * U-Boot / Linux. Iterates every (level, set, way) triple and
+     * issues `dc cisw` on it. Terminates at the Level of Coherency
+     * (LoC) read from CLIDR_EL1. */
+    mrs     x0, clidr_el1
+    and     x3, x0, #0x07000000     /* x3 = LoC (level of coherency) */
+    lsr     x3, x3, #23             /* x3 = LoC * 2 */
+    cbz     x3, dcache_done
+    mov     x10, #0                 /* x10 = current cache level << 1 */
+
+dcache_level_loop:
+    add     x2, x10, x10, lsr #1    /* x2 = level * 3 */
+    lsr     x1, x0, x2              /* x1 = ctype field for this level */
+    and     x1, x1, #7
+    cmp     x1, #2
+    b.lt    dcache_skip_level       /* No data cache at this level */
+    msr     csselr_el1, x10         /* Select cache level (instruction = 0) */
+    isb
+    mrs     x1, ccsidr_el1
+    and     x2, x1, #7              /* x2 = log2(line length) - 4 */
+    add     x2, x2, #4              /* x2 = log2(line length) */
+    mov     x4, #0x3ff
+    and     x4, x4, x1, lsr #3      /* x4 = max way number */
+    clz     w5, w4                  /* x5 = bit position of way size */
+    mov     x7, #0x7fff
+    and     x7, x7, x1, lsr #13     /* x7 = max set number */
+
+dcache_set_loop:
+    mov     x9, x4                  /* x9 = current way */
+dcache_way_loop:
+    lsl     x6, x9, x5
+    orr     x11, x10, x6            /* level | way */
+    lsl     x6, x7, x2
+    orr     x11, x11, x6            /* level | way | set */
+    dc      cisw, x11               /* clean & invalidate by set/way */
+    subs    x9, x9, #1
+    b.ge    dcache_way_loop
+    subs    x7, x7, #1
+    b.ge    dcache_set_loop
+
+dcache_skip_level:
+    add     x10, x10, #2
+    cmp     x3, x10
+    b.gt    dcache_level_loop
+
+dcache_done:
+    mov     x10, #0
+    msr     csselr_el1, x10
+    dsb     sy
+    isb
+
+    /* ---- 2. Invalidate entire I-cache to PoU ----
+     * `ic iallu` invalidates all instruction cache to the Point of
+     * Unification for the local PE. */
+    ic      iallu
+    dsb     ish
+    isb
+
+    /* ---- 3. Disable MMU + I-cache + D-cache at EL2 ----
+     *   SCTLR_EL2.M (bit 0)  = MMU enable
+     *   SCTLR_EL2.C (bit 2)  = D-cache enable
+     *   SCTLR_EL2.I (bit 12) = I-cache enable
+     */
+    mrs     x0, SCTLR_EL2
+    bic     x0, x0, #(1 << 0)       /* M  */
+    bic     x0, x0, #(1 << 2)       /* C  */
+    bic     x0, x0, #(1 << 12)      /* I  */
+    msr     SCTLR_EL2, x0
+    isb
+
+    /* ---- 4. Set up Linux ARM64 boot protocol registers and jump ----
+     *   x0 = DTB address
+     *   x1 = 0 (reserved)
+     *   x2 = 0 (reserved)
+     *   x3 = 0 (reserved)
+     *   PC = entry
+     */
+    mov     x0, x30                 /* x0 = DTB */
+    mov     x1, xzr
+    mov     x2, xzr
+    mov     x3, xzr
+    br      x29                     /* jump to kernel entry; never returns */
+
 .end

src/sdhci.c

@@ -581,6 +581,7 @@ static uint32_t sdhci_get_response_bits(int from, int count)
 /* voltage: 0=off or SDHCI_SRS10_BVS_[X_X]V */
 static int sdcard_power_init_seq(uint32_t voltage)
 {
+    int retries;
     /* Set power to specified voltage */
     int status = sdhci_set_power(voltage);
 #ifdef DEBUG_SDHCI
@@ -590,10 +591,24 @@ static int sdcard_power_init_seq(uint32_t voltage)
         SDHCI_REG(SDHCI_SRS09), SDHCI_REG(SDHCI_SRS10),
         SDHCI_REG(SDHCI_SRS11), SDHCI_REG(SDHCI_SRS12));
 #endif
-    if (status == 0) {
-        /* send CMD0 (go idle) to reset card */
+    if (status != 0)
+        return status;
+    /* SD spec requires >= 1ms after power stabilizes before CMD0. */
+    udelay(1000);
+    /* Some cards and the ZynqMP Arasan controller need more settling
+     * time after the slot-type change + soft reset in sdhci_platform_init().
+     * Use a retry loop: if CMD0 fails, wait and retry (self-calibrating). */
+    for (retries = 0; retries < 10; retries++) {
         status = sdhci_cmd(MMC_CMD0_GO_IDLE, 0, SDHCI_RESP_NONE);
+        if (status == 0)
+            break;
+        udelay(10000); /* 10ms between retries */
+    }
+#ifdef DEBUG_SDHCI
+    if (retries > 0 && status == 0) {
+        wolfBoot_printf("SD: CMD0 succeeded after %d retries\n", retries);
     }
+#endif
     if (status == 0) {
         /* send the operating conditions command */
         status = sdhci_cmd(SD_CMD8_SEND_IF_COND, SD_IF_COND_27V_33V,
@@ -1387,6 +1402,11 @@ int sdhci_init(void)
     /* Call platform-specific initialization (clocks, resets, pin mux) */
     sdhci_platform_init();
 
+    /* Allow controller to settle after platform init (slot type change,
+     * soft reset, clock configuration). Without this, the controller may
+     * not be ready to accept register writes on some platforms. */
+    udelay(1000); /* 1ms */
+
     /* Reset the host controller */
     sdhci_reg_or(SDHCI_HRS00, SDHCI_HRS00_SWR);
     /* Bit will clear when reset is done */
@@ -1482,6 +1502,9 @@ int sdhci_init(void)
     /* Setup 400khz starting clock */
     sdhci_set_clock(SDHCI_CLK_400KHZ);
 
+    /* Allow clock to stabilize before issuing first command */
+    udelay(1000); /* 1ms */
+
 #ifdef DISK_EMMC
     /* Run full eMMC card initialization */
     status = emmc_card_full_init();