Fixes for Xilinx ZynqMP ZCU102 SD card boot with Linux

Three targeted fixes 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 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.

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),
   and a 10-retry loop with 10ms udelay between retries around the initial
   CMD0. Without these, 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.

Author: dgarske

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/mmcblk0p2"
+#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,17 @@ 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;
+    return (count * 1000000ULL) / freq;
+}
+
 void* hal_get_dts_address(void)
 {
 #ifdef WOLFBOOT_DTS_BOOT_ADDRESS
@@ -1809,8 +1832,39 @@ 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));
+
+    /* Expand totalsize to allow modifying properties */
+    fdt_set_totalsize(fdt, fdt_totalsize(fdt) + 512);
+
+    /* 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) {
+        /* Set bootargs property - overrides PetaLinux default root= with
+         * the wolfBoot partition layout (root on P4, not P2) */
+        wolfBoot_printf("FDT: Setting bootargs: %s\n", LINUX_BOOTARGS);
+        fdt_fixup_str(fdt, off, "chosen", "bootargs", LINUX_BOOTARGS);
+    } else {
+        wolfBoot_printf("FDT: Failed to find/create chosen node (%d)\n", off);
+        return off;
+    }
+
     return 0;
 }
 #endif

src/boot_aarch64.c

@@ -43,6 +43,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 +172,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.
+     *
+     * If we're at EL2 we MUST clean dcache to PoC and disable MMU/I+D-cache
+     * before jumping to a Linux kernel, or Linux's arm64_panic_block_init()
+     * will panic with "Non-EFI boot detected with MMU and caches enabled".
+     * The asm helper does the dcache clean, SCTLR_EL2 fixup, and the branch
+     * to entry with x0=DTB. */
+    if (current_el() == 2) {
+    #ifdef MMU
+        uintptr_t dts = (uintptr_t)dts_offset;
+    #else
+        uintptr_t dts = 0;
+    #endif
+        wolfBoot_printf("do_boot: cleaning caches, disabling MMU, jumping to Linux\n");
+        el2_cleanup_and_jump_to_linux((uintptr_t)app_offset, dts);
+        /* unreachable */
+    }
+
+    /* Non-EL2 path (EL3, etc.): 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; 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,9 +591,18 @@ 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 */
+    /* SD spec requires >= 1ms after power stabilizes before CMD0.
+     * 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 */
+    }
+    if (retries > 0 && status == 0) {
+        wolfBoot_printf("SD: CMD0 succeeded after %d retries\n", retries);
     }
     if (status == 0) {
         /* send the operating conditions command */
@@ -1387,6 +1397,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 +1497,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();