skills-win/petalinux-qspi/references/cache-and-delivery.md

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:

python <skill>\scripts\qspi_cache.py capture `
  --board-profile <skill>\references\hjx9009-profile.json `
  --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

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.