skills-win/petalinux-qspi/SKILL.md

name, description

name

description

petalinux-qspi

Build, reuse, deploy, recover, and hardware-validate a PetaLinux QSPI transition system from a user-supplied Vivado HDF/XSA and board information. Use when the user asks to create or install a QSPI rescue/transition Linux, update BOOT.BIN or image.ub in QSPI, prepare removable storage from that Linux, or determine whether an existing QSPI delivery is current. Supports a validated HJX9009 profile and intake routes for emv9.3, ipots, and other boards.

PetaLinux QSPI transition system

Create a small, recoverable Linux in QSPI that can bring up networking, diagnose storage, and prepare the later production system. Reuse a delivery only when its inputs and artifacts are provably identical; deployment and hardware acceptance are always repeated for the target board.

1. Select the board first

If the user has not already named the board, ask exactly this choice before inspecting or changing a project:

1. HJX9009
2. emv9.3
3. ipots
4. others

• For HJX9009, read references/hjx9009.md before planning or editing.
• For emv9.3 or ipots, the electrical/deployment profile is not implemented yet. Read references/board-intake.md, collect and verify its inputs, then create a board reference before any QSPI write. Never borrow HJX9009 constants.
• For others, require the hardware details in board-intake.md. A schematic, Vivado configuration report, or vendor board file is required; stop before build/deployment if boot straps, flash topology, or storage wiring remains unknown.

2. Establish inputs and authority

Read the applicable project AGENTS.md/CLAUDE.md and bmem project/machine memory before substantive work. Machine paths, IP addresses, serial ports, relay mappings, tool locations, usernames, and credentials come from live discovery, bmem pointers, or ~\skills_env.md; never put them in this skill or copy values from an old note.

Require or locate:

• user-supplied Vivado hardware handoff (.hdf for PetaLinux 2018.1-era flows, .xsa for newer flows), plus bitstream only when the requested BOOT composition needs it;
• matching Vivado/SDK/PetaLinux versions; do not silently upgrade a hardware handoff;
• board schematic/configuration evidence and the exact target board identity;
• accessible serial console, power control, JTAG, and a proven recovery image/path before erasing QSPI;
• current host, VM, TFTP, and board network facts verified on the live interfaces.

Ask for the exact destructive target and show the selected board, image hashes, flash ranges, and recovery path immediately before the first QSPI erase/program operation if they were not already explicit in the user's deployment request.

3. Decide whether to rebuild

Read references/cache-and-delivery.md. Use scripts/qspi_cache.py capture to fingerprint all build-defining inputs and scripts/qspi_cache.py check to evaluate an existing delivery.

Skip the build only when all are true:

• board profile and its revision match;
• HDF/XSA and every included overlay/config/script hash match;
• PetaLinux, Vivado, SDK, boot composition, QSPI layout, and relevant parameters match;
• BOOT.BIN, image.ub.qspi, flash_layout.json, summary.json, and checksum manifest pass validation;
• prior build gates G0-G3 are PASS.

File existence, timestamps, an unchanged bitstream alone, or a prior successful boot are insufficient. A reusable build still goes through G4-G6 on the present hardware. If any fingerprint field is missing or differs, rebuild.

4. Execute the gated workflow

Read references/workflow.md and apply gates in order:

• G0 preflight: resolve inputs, live network, free space, serial/JTAG/power, QSPI recovery, and a no-write baseline.
• G1 hardware import: create a clean project and import the exact HDF/XSA. Archive generated configuration before overlays.
• G2 configuration: enable QSPI, initramfs, MTD, network, storage drivers, and required deployment/diagnostic tools. Audit generated device trees and bootloader configuration against the selected board reference.
• G3 build/package: build without hidden errors; package a deliberate BOOT composition; create hashes, input fingerprint, Flash layout, and manifest.
• G4 boot-region deployment: program/verify BOOT.BIN, then cold boot into the intended U-Boot. Preserve a recovery route.
• G5 image deployment: transfer, size-check, erase only the image region, write, full-readback, CRC/hash, and byte-compare image.ub.qspi. Save the exact QSPI-only bootcmd only after verification.
• G6 system acceptance: perform at least two full power-cycle boots; prove BootROM/U-Boot/FIT/Linux origin, MTD layout, networking, tools, and target storage behavior.

Never let a failed transfer fall through into erase/write commands. Use checked steps and stop on the first missing expected response or nonzero result. A successful build or sf write is not acceptance.

5. Storage initialization boundary

The transition system may contain partitioning and filesystem tools, but insertion does not authorize formatting.

1. Power off before inserting media when required by the board workflow.
2. Boot from QSPI and prove the QSPI path again.
3. Enumerate the target and read identity, CID, capacity, current mounts, partition table, and sample sectors without writing.
4. If no card is physically inserted, record WAITING_FOR_MEDIA, not a driver failure.
5. Format or deploy a production filesystem only after the target device is unambiguous and the user has requested that destructive step.

Never infer eMMC from a Linux name such as /dev/mmcblk0; it may be removable SD.

6. Evidence and handoff

• Put automatic logs/state under the project Notes/auto/, never in the Notes/ root.
• Record exact artifact sizes, SHA-256, U-Boot CRC, flash offsets/lengths, bootcmd, live IPs, gate status, and evidence paths.
• Distinguish static inspection, VM build, flash write/readback, warm boot, cold boot, and real-media results.
• Do not claim completion while a required physical medium is absent; state the precise remaining gate.
• At substantive-work completion, import changed user-facing Notes and a session summary through bmem, add durable project decisions/issues at the correct layer, and run bmem sync. Report local/central/remote sync outcomes separately.