84 lines
6.3 KiB
Markdown
84 lines
6.3 KiB
Markdown
---
|
|
name: petalinux-qspi
|
|
description: 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](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](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](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](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.
|