add petalinux qspi transition workflow

2026-09-15 03:17:59 +08:00
parent 170f4eb53f
commit 188d067d31
7 changed files with 594 additions and 0 deletions
@@ -0,0 +1,53 @@
+# Build reuse and delivery contract
+
+## Input fingerprint
+
+Fingerprint every item that can change generated boot behavior:
+
+- selected board profile file;
+- HDF/XSA and optional bitstream;
+- project config, rootfs config, kernel config fragments, device-tree overlays, U-Boot overlays/BIF, recipes and custom files;
+- PetaLinux, Vivado and SDK versions;
+- BOOT.BIN composition;
+- QSPI geometry/layout and boot parameters that are not machine-local.
+
+Do not fingerprint credentials, transient logs, IP addresses discovered only for deployment, or build timestamps. Store the generated file as `build_inputs.json` in the delivery.
+
+Example:
+
+```powershell
+python <skill>\scripts\qspi_cache.py capture `
+  --board-profile <skill>\references\hjx9009.md `
+  --input HDF=<path-to-system.hdf> `
+  --input SYSTEM_USER_DTSI=<path-to-system-user.dtsi> `
+  --input ROOTFS_CONFIG=<path-to-rootfs-config> `
+  --value PETALINUX_VERSION=2018.1 `
+  --value VIVADO_VERSION=2018.1 `
+  --value BOOT_COMPOSITION=FSBL+U-Boot `
+  --output <work>\build_inputs.json
+```
+
+After building, copy that exact `build_inputs.json` into the delivery and generate `SHA256SUMS` for the delivery artifacts. Do not include `SHA256SUMS` itself in that file.
+
+## Reuse check
+
+```powershell
+python <skill>\scripts\qspi_cache.py check `
+  --current <work>\build_inputs.json `
+  --delivery <delivery-directory>
+```
+
+Exit 0 and `reusable: true` allow skipping G1-G3. Any other result requires rebuild or repair. Reuse never skips target-board programming/readback/cold-boot gates.
+
+## Required delivery files
+
+- `BOOT.BIN`
+- `image.ub.qspi`
+- `flash_layout.json`
+- `summary.json`
+- `build_inputs.json`
+- `SHA256SUMS`
+- human-readable manifest containing versions, composition, hashes, layout, bootcmd, gate states, known limitations and evidence paths
+
+`flash_layout.json` must describe total/erase/page bytes, non-overlapping partitions, and the image file, offset, byte count, erase length and RAM load address. Image size must fit the named partition; offsets and erase lengths must align to the actual erase size.
+