Add Xilinx Zynq-7000 (ZC702) wolfBoot port

Author: dgarske

.github/workflows/test-configs.yml

@@ -654,11 +654,11 @@ jobs:
       arch: arm
       config-file: ./config/examples/zynq7000.config
 
-  zc702_sdcard_test:
+  zynq7000_sdcard_test:
     uses: ./.github/workflows/test-build.yml
     with:
       arch: arm
-      config-file: ./config/examples/zc702_sdcard.config
+      config-file: ./config/examples/zynq7000_sdcard.config
 
   versal_vmk180_test:
     uses: ./.github/workflows/test-build-aarch64.yml

arch.mk

@@ -316,10 +316,10 @@ ifeq ($(ARCH),ARM)
      # mapping enabled to avoid that, but we still link against the
      # aligned-safe memcpy in src/string.c so unaligned loads can never
      # surprise us regardless of MMU state.
-     # U-Boot legacy 64-byte header strip is only meaningful for the
-     # Linux/U-Boot payload variant (zynq7000_linux.config). Bare-metal
-     # payloads (zynq7000.config, zc702_sdcard.config) shouldn't risk a
-     # ~1-in-2^32 false-positive collision with UBOOT_IMG_HDR_MAGIC.
+     # The legacy 64-byte uImage header strip is only meaningful when the
+     # payload is a Linux kernel (LINUX_PAYLOAD=1). Bare-metal payloads
+     # shouldn't risk a ~1-in-2^32 false-positive collision against
+     # UBOOT_IMG_HDR_MAGIC, so the flag is gated on LINUX_PAYLOAD.
      ifeq ($(LINUX_PAYLOAD),1)
        CFLAGS+=-DWOLFBOOT_UBOOT_LEGACY
      endif

config/examples/zynq7000.config

@@ -4,32 +4,33 @@ SIGN?=ECC256
 HASH?=SHA256
 
 # Cortex-A9 (Zynq-7000) - selected automatically via TARGET=zynq7000 in arch.mk.
-# This single config supports bare-metal, U-Boot, and Linux payloads from QSPI.
+# wolfBoot replaces U-Boot in the Z7 boot flow (BootROM -> FSBL -> wolfBoot ->
+# kernel/app, no U-Boot stage). This single config supports both bare-metal
+# and Linux payloads from QSPI.
 DEBUG?=0
 DEBUG_UART?=1
 V?=0
 SPMATH?=1
 
-# Linux/U-Boot payload support (no-op for plain bare-metal payloads):
+# Linux payload support (no-op for plain bare-metal payloads):
 #   LINUX_PAYLOAD=1 -> do_boot uses ARM Linux boot ABI (r0=0, r1=~0,
 #                      r2=DTB_phys, r3=0). Bare-metal apps don't read these
 #                      registers, so the same ABI is fine for them.
 #   MMU=1           -> enables update_ram.c DTB-load codepath and pulls in
 #                      src/fdt.o. wolfBoot itself does NOT manage page
 #                      tables; it inherits FSBL's flat 1:1 DDR mapping.
-#   ELF=1           -> wolfBoot understands ELF inputs (vmlinux / u-boot.elf)
-#                      and loads only their LOAD segments. Flat binaries
-#                      (zImage, bare-metal .bin) fall through to raw-binary
-#                      boot.
+#   ELF=1           -> wolfBoot understands ELF inputs (e.g. vmlinux) and
+#                      loads only their LOAD segments. Flat binaries (zImage,
+#                      bare-metal .bin) fall through to raw-binary boot.
 # Cost vs. a strictly bare-metal-only build: ~5 KB extra wolfBoot binary
-# from the FDT/MMU/ELF support, in exchange for one config that covers all
-# three payload types.
+# from the FDT/MMU/ELF support, in exchange for one config that covers
+# both payload types.
 LINUX_PAYLOAD=1
 MMU=1
 ELF=1
 
 # wolfBoot itself is staged by FSBL to DDR at 0x04000000 (hal/zynq7000.ld);
-# the verified payload (kernel/U-Boot/bare-metal app) is staged at
+# the verified payload (kernel or bare-metal app) is staged at
 # WOLFBOOT_LOAD_ADDRESS, well clear of wolfBoot. 1 GB DDR3 on ZC702
 # starts at 0x00000000.
 WOLFBOOT_LOAD_ADDRESS=0x10000000

config/examples/zc702_sdcard.config config/examples/zynq7000_sdcard.configconfig/examples/zc702_sdcard.config renamed to config/examples/zynq7000_sdcard.config

@@ -3,11 +3,16 @@ TARGET?=zynq7000
 SIGN?=ECC256
 HASH?=SHA256
 
-# Cortex-A9 ZC702 SD-card boot variant. Uses the generic SDHCI driver
+# Cortex-A9 Zynq-7000 SD-card boot variant. Uses the generic SDHCI driver
 # (src/sdhci.c) with HAL hooks in hal/zynq7000.c that translate between the
 # driver's Cadence SD4HC register layout and the Arasan SDHCI v2.0 standard
 # layout used by the Zynq-7000 controller (same IP family as ZynqMP's v3.0,
 # just an older revision; the translation is reused from hal/zynq.c).
+#
+# wolfBoot replaces U-Boot in the Z7 boot flow (BootROM -> FSBL -> wolfBoot
+# -> kernel/app, no U-Boot stage). This single config supports both
+# bare-metal and Linux payloads from SD card -- see the LINUX_PAYLOAD/MMU/
+# ELF block below.
 DEBUG?=0
 DEBUG_UART?=1
 V?=0
@@ -17,17 +22,41 @@ SPMATH?=1
 DISK_SDCARD=1
 NO_XIP=1
 
+# Linux payload support (no-op for plain bare-metal payloads):
+#   LINUX_PAYLOAD=1 -> do_boot uses ARM Linux boot ABI (r0=0, r1=~0,
+#                      r2=DTB_phys, r3=0). Bare-metal apps don't read
+#                      these registers, so the same ABI is fine for them.
+#   MMU=1           -> pulls in src/fdt.o for FDT-aware paths in
+#                      update_disk.c. wolfBoot does NOT manage page
+#                      tables; it inherits FSBL's flat 1:1 DDR mapping.
+#   ELF=1           -> wolfBoot understands ELF inputs (e.g. vmlinux) and
+#                      loads only their LOAD segments. Flat binaries
+#                      (zImage, bare-metal .bin) fall through to raw-
+#                      binary boot.
+# For Linux from SD use tools/scripts/zynq7000/prepare_linux.sh APPENDED=1
+# (DTB concatenated to zImage and signed as one image). update_disk.c does
+# not read a separate PART_DTS_BOOT partition; the appended-DTB path is
+# what carries the device tree to the kernel via CONFIG_ARM_APPENDED_DTB.
+LINUX_PAYLOAD=1
+MMU=1
+ELF=1
+
 # Stage payload at low DDR (clear of wolfBoot at 0x04000000-0x040FFFFF).
 WOLFBOOT_LOAD_ADDRESS=0x10000000
 
+# DTB load address (Linux only, used by update_disk.c when a FIT image
+# carries a DTB). Ignored for bare-metal and for the appended-DTB Linux
+# flow. 16 MB clear of WOLFBOOT_LOAD_ADDRESS.
+WOLFBOOT_LOAD_DTS_ADDRESS=0x11000000
+
 # MBR partition layout on the SD card. Pure MBR (no GPT) - the Zynq-7000
 # BootROM (UG821 ch.6.3) only accepts MBR with the first partition as
 # FAT32 and the Active flag set. wolfBoot's src/disk.c falls back to MBR
 # parsing when no protective-GPT entry is present.
 #   MBR p1 (wolfBoot idx 0): FAT32-LBA Active - holds BOOT.BIN for BootROM.
 #   MBR p2 (wolfBoot idx 1): Linux raw (0x83) - signed boot image.
 #   MBR p3 (wolfBoot idx 2): Linux raw (0x83) - signed update image.
-# tools/scripts/zc702/prepare_sdcard.sh lays this out; BOOT_PART_A/B tell
+# tools/scripts/zynq7000/prepare_sdcard.sh lays this out; BOOT_PART_A/B tell
 # update_disk.c which MBR entries (0-indexed) to use for boot/update.
 CFLAGS_EXTRA+=-DBOOT_PART_A=1 -DBOOT_PART_B=2
 
@@ -47,8 +76,17 @@ CFLAGS_EXTRA+=-DBOOT_PART_A=1 -DBOOT_PART_B=2
 # adds an explicit DAT-line reset between transfers.
 CFLAGS_EXTRA+=-DSDHCI_CLK_50MHZ=6000 -DSDHCI_CLK_25MHZ=6000
 
-# Uncomment to enable verbose SDHCI driver logging when bringing up
-# new boards or debugging timing issues.
+# update_disk.c reads images in DISK_BLOCK_SIZE chunks. Default 512 B = one
+# disk_read = one CMD17 per 512 B, which makes a multi-MB Linux load issue
+# thousands of CMDs and stall the card with per-CMD overhead. Bump to
+# 512 KB so each disk_read pulls 1024 blocks via one CMD18 SDMA (matches
+# ZynqMP). Verified on ZC702 with a 4.76 MB appended-DTB zImage: 9 CMD18s
+# complete in well under a second. The default 4 KB SDMA buffer boundary
+# is left in place -- overriding it to 512 KB stalled SDMA on Arasan v2.0.
+CFLAGS_EXTRA+=-DDISK_BLOCK_SIZE=0x80000
+
+# Uncomment for verbose SDHCI driver logging when bringing up new boards
+# or debugging timing issues.
 #CFLAGS_EXTRA+=-DDEBUG_SDHCI
 
 # Image-header partition addresses are unused for disk boot (kept for the
@@ -65,4 +103,11 @@ WOLFBOOT_SECTOR_SIZE=0x1000
 
 IMAGE_HEADER_SIZE=1024
 
+# Required by image.c when MMU=1 is set, even though update_disk.c never
+# opens PART_DTS_BOOT/PART_DTS_UPDATE (the disk boot path uses appended-
+# DTB or FIT, not a separate DTB partition). Set to dummy addresses to
+# satisfy the build.
+WOLFBOOT_DTS_BOOT_ADDRESS=0x0
+WOLFBOOT_DTS_UPDATE_ADDRESS=0x0
+
 CROSS_COMPILE=arm-none-eabi-

docs/Targets.md

@@ -3396,16 +3396,18 @@ Entering idle loop...
 
 AMD/Xilinx Zynq-7000 (XC7Z020) on the ZC702 Evaluation Kit - dual ARM Cortex-A9 (ARMv7-A 32-bit), 1 GB DDR3, 16 MB QSPI NOR (N25Q128A), SDIO, dual UART. Older sibling of the ZynqMP family - distinct silicon, different controllers (`XQspiPs` not `XQspiPsu`, Arasan SDHCI v2.0 not v3.0, no CSU/PMU/PUF, PL310 L2).
 
-wolfBoot is loaded by the Xilinx Zynq-7000 FSBL into DDR:
+wolfBoot replaces U-Boot in the Zynq-7000 boot flow -- there is no
+U-Boot stage. wolfBoot is loaded by the Xilinx Zynq-7000 FSBL into
+DDR:
 ```
-BootROM -> FSBL -> wolfBoot -> signed app (or U-Boot/Linux)
+BootROM -> FSBL -> wolfBoot -> signed app or Linux kernel
 ```
 
 The FSBL handles all PS init (DDR, MIO, clocks, QSPI ref clock); wolfBoot only initializes UART, the QSPI controller, runs the verify/swap logic, and chain-loads the next stage.
 
 This target supports:
-- **QSPI boot** (primary): `config/examples/zynq7000.config` -- one config for bare-metal, U-Boot, and Linux payloads (LINUX_PAYLOAD=1 + MMU=1 + ELF=1; bare-metal apps don't pay any runtime cost beyond ~5 KB of unused FDT/MMU code).
-- **SD card boot**: `config/examples/zc702_sdcard.config` -- bare-metal payload from MBR-partitioned SD via the generic SDHCI driver and the Arasan v2.0 translation in `hal/zynq7000.c`.
+- **QSPI boot** (primary): `config/examples/zynq7000.config` -- one config for both bare-metal and Linux payloads (LINUX_PAYLOAD=1 + MMU=1 + ELF=1; bare-metal apps don't pay any runtime cost beyond ~5 KB of unused FDT/MMU code).
+- **SD card boot**: `config/examples/zynq7000_sdcard.config` -- bare-metal **and** Linux payloads from MBR-partitioned SD via the generic SDHCI driver and the Arasan v2.0 translation in `hal/zynq7000.c`.
 - **JTAG-loaded dev** via Platform Cable II + xsdb (no flash required).
 
 ### Prerequisites
@@ -3438,7 +3440,7 @@ Key options in `config/examples/zynq7000.config`:
 - `ARCH=ARM` - 32-bit ARM
 - `TARGET=zynq7000` - selects `hal/zynq7000.{c,h,ld}` and the `CORTEX_A9` arch.mk block
 - `SIGN=ECC256` / `HASH=SHA256` - smaller and faster than RSA on Cortex-A9
-- `LINUX_PAYLOAD=1 MMU=1 ELF=1` - lets the same image boot Linux/U-Boot or bare-metal. `do_boot` switches to the ARM Linux boot ABI (`r0=0`, `r1=~0`, `r2=DTB_phys`, `r3=0`) which bare-metal apps simply ignore. `MMU=1` enables `update_ram.c`'s DTB-load codepath and pulls in `src/fdt.o`; wolfBoot does not manage page tables (it inherits FSBL's flat 1:1 DDR mapping). `ELF=1` lets wolfBoot understand `vmlinux` / `u-boot.elf` inputs and load only their LOAD segments. Cost over a strictly bare-metal-only build: ~5 KB extra wolfBoot binary (31 KB -> 36 KB).
+- `LINUX_PAYLOAD=1 MMU=1 ELF=1` - lets the same image boot Linux or bare-metal. `do_boot` switches to the ARM Linux boot ABI (`r0=0`, `r1=~0`, `r2=DTB_phys`, `r3=0`) which bare-metal apps simply ignore. `MMU=1` enables `update_ram.c`'s DTB-load codepath and pulls in `src/fdt.o`; wolfBoot does not manage page tables (it inherits FSBL's flat 1:1 DDR mapping). `ELF=1` lets wolfBoot understand ELF inputs (e.g. `vmlinux`) and load only their LOAD segments. Cost over a strictly bare-metal-only build: ~5 KB extra wolfBoot binary (31 KB -> 36 KB).
 - `EXT_FLASH=1` - QSPI as external flash via `XQspiPs`
 - `WOLFBOOT_LOAD_ADDRESS=0x10000000` - DDR offset 256 MB, where the verified app is staged before `do_boot`. Must be **above** wolfBoot's own region (`0x04000000`-`0x040FFFFF`) because `src/update_ram.c` enforces `dst > _end`.
 - `WOLFBOOT_LOAD_DTS_ADDRESS=0x11000000` - DDR offset 272 MB, where a DTB read out of `PART_DTS_BOOT` would be relocated. Ignored for bare-metal payloads and for the appended-DTB Linux flow (where the DTB lives at the end of the signed kernel image).
@@ -3478,10 +3480,10 @@ The result is a 32-bit ARM ELF with entry point `0x04000000` and `.text` start a
 
 ```sh
 cp ${PREBUILT_DIR}/zynq_fsbl.elf .
-bootgen -arch zynq -image tools/scripts/zc702/zc702_qspi.bif -w -o BOOT.BIN
+bootgen -arch zynq -image tools/scripts/zynq7000/zynq7000_qspi.bif -w -o BOOT.BIN
 ```
 
-`bootgen` ships with Vitis. The `.bif` template at `tools/scripts/zc702/zc702_qspi.bif` is the minimum bootable image; add `download.bit` and a DTB if you also need to load the PL bitstream and a Linux device tree (see Milestone 5).
+`bootgen` ships with Vitis. The `.bif` template at `tools/scripts/zynq7000/zynq7000_qspi.bif` is the minimum bootable image; add `download.bit` and a DTB if you also need to load the PL bitstream and a Linux device tree (see Milestone 5).
 
 ### Programming QSPI
 
@@ -3517,7 +3519,7 @@ For driver bring-up or quick iteration, skip bootgen and load directly via Platf
 
 ```sh
 source /opt/Xilinx/2025.2/Vitis/settings64.sh   # once per shell
-xsdb tools/scripts/zc702/jtag_load.tcl
+xsdb tools/scripts/zynq7000/jtag_load.tcl
 ```
 
 The script runs the prebuilt FSBL (PS init: DDR/MIO/clocks/UART), then loads `wolfboot.elf` over the top, sets PC to `0x04000000` and CPSR to SVC with IRQ/FIQ masked, and resumes. Override paths via `FSBL_ELF=...` or `WOLFBOOT_ELF=...` env vars.
@@ -3567,15 +3569,15 @@ program_flash -f test-app/image_v1_signed.bin \
     -flash_type qspi-x4-single -offset 0x100000
 ```
 
-`program_flash` ships with Vitis. Then run wolfBoot via `xsdb tools/scripts/zc702/jtag_load.tcl` - it should verify and chain-load the test app, producing the heartbeat output above.
+`program_flash` ships with Vitis. Then run wolfBoot via `xsdb tools/scripts/zynq7000/jtag_load.tcl` - it should verify and chain-load the test app, producing the heartbeat output above.
 
 ### QSPI driver self-test (`TEST_EXT_FLASH`)
 
 To exercise the `XQspiPs` driver in isolation - read JEDEC ID, sector erase + page program + linear-mode read-back of a 256-byte pattern at `0x200000`:
 
 ```sh
 make CFLAGS_EXTRA=-DTEST_EXT_FLASH wolfboot.elf
-xsdb tools/scripts/zc702/jtag_load.tcl
+xsdb tools/scripts/zynq7000/jtag_load.tcl
 ```
 
 Expected output:
@@ -3616,10 +3618,14 @@ For TX-only commands sent without RX capture, `qspi_xfer4` picks `TXD1`/`TXD2`/`
 
 ### SD card boot (Milestone 6)
 
-`config/examples/zc702_sdcard.config` enables SD-card boot via the generic
+`config/examples/zynq7000_sdcard.config` enables SD-card boot via the generic
 SDHCI driver (`src/sdhci.c`) with HAL hooks in `hal/zynq7000.c` that
 translate the driver's Cadence SD4HC register layout to the Arasan
-SDHCI v2.0 standard layout used by the Zynq-7000 controller.
+SDHCI v2.0 standard layout used by the Zynq-7000 controller. The config
+sets `LINUX_PAYLOAD=1 MMU=1 ELF=1` so the same SD-card image can chain-
+load either a bare-metal app or a signed appended-DTB Linux zImage --
+Linux-from-SD is verified end-to-end on ZC702 (full kernel banner +
+SMP + driver init through to rootfs panic).
 
 **Strap**: SW16-3 + SW16-4 ON (others OFF). `BOOT_MODE_REG = 0x5`.
 
@@ -3631,18 +3637,29 @@ SDHCI v2.0 standard layout used by the Zynq-7000 controller.
 | p2        | 0x83 Linux raw         | 16 MB  | Signed boot image (`BOOT_PART_A=1`) |
 | p3        | 0x83 Linux raw         | 16 MB  | Signed update image (`BOOT_PART_B=2`) |
 
-`tools/scripts/zc702/prepare_sdcard.sh` lays this out (parted msdos +
+`tools/scripts/zynq7000/prepare_sdcard.sh` lays this out (parted msdos +
 manual MBR type/active patch + dd of signed images).
 
+**Bare-metal payload** (signed test app):
+
 ```sh
-cp config/examples/zc702_sdcard.config .config
-make
-make test-app/image.bin
-IMAGE_HEADER_SIZE=1024 ./tools/keytools/sign --ecc256 --sha256 \
-    test-app/image.bin wolfboot_signing_private_key.der 1
+cp config/examples/zynq7000_sdcard.config .config
+make TARGET=zynq7000
+cp ${PREBUILT_DIR}/zynq_fsbl.elf .
+bootgen -arch zynq -image tools/scripts/zynq7000/zynq7000_qspi.bif -w -o BOOT.BIN
+sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX
+```
+
+**Linux payload** (signed appended-DTB zImage):
+
+```sh
+cp config/examples/zynq7000_sdcard.config .config
+make TARGET=zynq7000
 cp ${PREBUILT_DIR}/zynq_fsbl.elf .
-bootgen -arch zynq -image tools/scripts/zc702/zc702_qspi.bif -w -o BOOT.BIN
-sudo ./tools/scripts/zc702/prepare_sdcard.sh /dev/sdX
+bootgen -arch zynq -image tools/scripts/zynq7000/zynq7000_qspi.bif -w -o BOOT.BIN
+./tools/scripts/zynq7000/prepare_linux.sh    # appends DTB to zImage and signs as one image
+mv image_v1_signed.bin test-app/zImage_signed.bin
+sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX test-app/zImage_signed.bin
 ```
 
 **Arasan SDHCI v2.0 quirks** (handled by the HAL/config):
@@ -3661,6 +3678,12 @@ sudo ./tools/scripts/zc702/prepare_sdcard.sh /dev/sdX
   default ZC702 FSBL clock plan; `Z7_GTIMER_FREQ_HZ` in
   `hal/zynq7000.h` defaults to that and feeds `hal_get_timer_us()`
   used by the SDHCI driver's `udelay()`.
+- `DISK_BLOCK_SIZE=0x80000` (512 KB) is set so `update_disk.c` issues
+  ~10 CMD18 SDMA reads of 512 KB each instead of thousands of CMD17
+  PIO reads of 512 B each. The default 512 B causes the card to time
+  out (SRS12 bit 20 / EDT) on multi-MB Linux loads. The default 4 KB
+  SDMA buffer boundary is left in place; overriding it to 512 KB
+  stalled SDMA on Arasan v2.0 (TC never fired).
 
 ### Differences from the ZynqMP port
 

tools/scripts/zc702/jtag_load.tcl tools/scripts/zynq7000/jtag_load.tcltools/scripts/zc702/jtag_load.tcl renamed to tools/scripts/zynq7000/jtag_load.tcl

@@ -5,7 +5,7 @@
 #
 # Usage:
 #   source /opt/Xilinx/2025.2/Vitis/settings64.sh
-#   xsdb tools/scripts/zc702/jtag_load.tcl
+#   xsdb tools/scripts/zynq7000/jtag_load.tcl
 #
 # Set the JTAG boot mode straps on the ZC702 (SW16 = all OFF) before use.
 # After this script runs the board may need a power-cycle to recover the

tools/scripts/zc702/prepare_linux.sh tools/scripts/zynq7000/prepare_linux.shtools/scripts/zc702/prepare_linux.sh renamed to tools/scripts/zynq7000/prepare_linux.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Sign and stage a ZC702 Linux kernel for wolfBoot.
+# Sign and stage a Zynq-7000 Linux kernel for wolfBoot (verified on ZC702).
 #
 # Two modes (chosen by the APPENDED env var):
 #
@@ -48,6 +48,12 @@ config_get() {
 WOLFBOOT_PARTITION_BOOT_ADDRESS=$(config_get WOLFBOOT_PARTITION_BOOT_ADDRESS)
 WOLFBOOT_DTS_BOOT_ADDRESS=$(config_get WOLFBOOT_DTS_BOOT_ADDRESS)
 WOLFBOOT_PARTITION_SIZE=$(config_get WOLFBOOT_PARTITION_SIZE)
+# The sign tool reads IMAGE_HEADER_SIZE from the environment (sign.c line
+# 2824). Without this export, sign defaults to 256 bytes -- which leaves
+# wolfBoot reading the wrong fw_base offset on flash if the running config
+# uses a larger header.
+IMAGE_HEADER_SIZE=$(config_get IMAGE_HEADER_SIZE)
+[ -n "$IMAGE_HEADER_SIZE" ] && export IMAGE_HEADER_SIZE
 
 SIGN_TOOL="./tools/keytools/sign"
 KEY="wolfboot_signing_private_key.der"

tools/scripts/zc702/prepare_sdcard.sh tools/scripts/zynq7000/prepare_sdcard.shtools/scripts/zc702/prepare_sdcard.sh renamed to tools/scripts/zynq7000/prepare_sdcard.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-# Lay out a ZC702 wolfBoot SD card.
+# Lay out a Zynq-7000 wolfBoot SD card (verified on ZC702 / Arasan v2.0).
 #
 # Pure MBR layout (no GPT). The Zynq-7000 BootROM (UG821 ch.6.3) requires
 # an MBR with the first partition as FAT32, type 0x0C (FAT32-LBA), with the
@@ -19,7 +19,18 @@
 # p2=idx1, p3=idx2 - matching BOOT_PART_A=1 and BOOT_PART_B=2 in the config.
 #
 # Usage:
-#   sudo ./tools/scripts/zc702/prepare_sdcard.sh /dev/sdX [signed_image]
+#   sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX [signed_image]
+#
+# Bare-metal payload (default):
+#   sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX
+#       -> writes test-app/image_v1_signed.bin to p2 and p3.
+#
+# Linux payload (signed appended-DTB zImage produced by prepare_linux.sh):
+#   sudo ./tools/scripts/zynq7000/prepare_sdcard.sh /dev/sdX \
+#       test-app/zImage_signed.bin
+#       -> writes the signed kernel image to p2 (BOOT_A) and p3 (BOOT_B).
+# The MBR partition layout is identical for both -- the choice of payload
+# is signing-side, not partitioning-side.
 
 set -e
 RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
@@ -54,7 +65,7 @@ esac
 # Some USB SD readers expose RM=0; in that case the user can set
 # ALLOW_NON_REMOVABLE=1 after eyeballing lsblk.
 if [ "${ALLOW_NON_REMOVABLE:-0}" != "1" ]; then
-    rm_flag=$(lsblk -ndo RM "$DEV" 2>/dev/null || echo "")
+    rm_flag=$(lsblk -ndo RM "$DEV" 2>/dev/null | tr -d '[:space:]' || echo "")
     if [ -n "$rm_flag" ] && [ "$rm_flag" != "1" ]; then
         echo -e "${RED}refusing $DEV (RM=$rm_flag - not flagged as removable)." >&2
         echo -e "Re-run with ALLOW_NON_REMOVABLE=1 if this really is the" >&2