add petalinux qspi transition workflow
This commit is contained in:
bowei
@@ -0,0 +1,41 @@
|
||||
# Board intake for emv9.3, ipots, and other boards
|
||||
|
||||
Do not build or erase QSPI until the following facts are backed by a schematic, Vivado report, vendor board definition, or direct measurement.
|
||||
|
||||
## Required identity
|
||||
|
||||
- board name, PCB revision, serial/asset identity, SoC/FPGA exact part;
|
||||
- Vivado hardware handoff and its tool version;
|
||||
- expected PetaLinux/SDK version and whether migration is authorized;
|
||||
- intended role of the transition system and later production storage.
|
||||
|
||||
## Boot and QSPI
|
||||
|
||||
- boot-mode strap/switch mapping, active levels, currently selected setting, and when it is sampled;
|
||||
- flash manufacturer/part, single/dual, stacked/parallel/cascade topology, bus width, total bytes, page and erase sizes;
|
||||
- PS/PL controller, chip-selects, MIO/pin mapping, voltage, reset and power dependencies;
|
||||
- recovery method if the boot region becomes invalid;
|
||||
- required BOOT.BIN contents: FSBL, U-Boot, optional bitstream/PMUFW/ATF, and why.
|
||||
|
||||
## Console and networking
|
||||
|
||||
- UART instance, pin routing, baud rate and physical COM adapter;
|
||||
- Ethernet controller, PHY model/address/interface/reset/clock;
|
||||
- live host/VM/board subnet, route, firewall and TFTP binding. Discover these each run; do not copy old addresses.
|
||||
|
||||
## Later storage
|
||||
|
||||
- storage type (removable SD, soldered eMMC, NAND, USB, other), controller instance, pin/MIO mapping and bus width;
|
||||
- card-detect/write-protect/power-enable wiring and polarity;
|
||||
- voltage switching capability and maximum safe frequency;
|
||||
- expected Linux block-device evidence; never assume numbering before enumeration.
|
||||
|
||||
## Acceptance decisions
|
||||
|
||||
- exact QSPI layout with non-overlap and erase alignment;
|
||||
- maximum image sizes and RAM load addresses;
|
||||
- cold-boot count, network checks, storage checks, and whether blank-media formatting is part of this request;
|
||||
- board-specific hazards and the stop/recovery threshold.
|
||||
|
||||
Create `references/<board-name>.md` only after these facts are verified. Mark every unverified item explicitly; placeholders are not deployment permission.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# HJX9009 validated board profile
|
||||
|
||||
This profile comes from the HJX-ADRV9009-X2 schematic and a PetaLinux 2018.1 hardware run. Reconfirm the PCB revision and live probes for every target; schematic constants do not replace target identity.
|
||||
|
||||
## Boot and QSPI
|
||||
|
||||
- SoC: XC7Z100FF900.
|
||||
- Boot device straps are `MIO[5:4:3]`; `100` is QSPI and is the schematic default. The schematic implements resistor straps, not a user boot DIP. Boot mode is sampled at power-on reset.
|
||||
- `MIO2=0` selects cascaded dual-QSPI mode by default.
|
||||
- U5 and U6 are S25FL128S-family serial flashes. Validated U-Boot probe: `s25fl128s_64k`, 32 MiB total, 128 KiB erase, 512-byte reported page. Treat the live `sf probe` result as mandatory before erase.
|
||||
- A TF card does not alter the QSPI boot selection. The transition U-Boot bootcmd must contain only `sf probe`, QSPI `sf read`, documented board fixups, and `bootm`; no implicit `mmc` fallback.
|
||||
|
||||
Validated transition layout:
|
||||
|
||||
| Region | Offset | Size |
|
||||
|---|---:|---:|
|
||||
| boot | `0x00000000` | `0x00500000` |
|
||||
| bootenv | `0x00500000` | `0x00020000` |
|
||||
| kernel | `0x00520000` | `0x01800000` |
|
||||
| spare | `0x01D20000` | `0x002E0000` |
|
||||
|
||||
The transition `BOOT.BIN` contains FSBL and U-Boot only. It deliberately excludes the PL bitstream and `image.ub`. The kernel region stores a FIT `image.ub.qspi` containing kernel, DTB and initramfs rootfs. Calculate the actual image read and erase lengths for each build; never copy an old length.
|
||||
|
||||
## J1 microSD/TF interface
|
||||
|
||||
HJX9009 has no soldered eMMC. J1 is removable microSD through U12 MAX13035E:
|
||||
|
||||
- SD0 CLK/CMD/DAT0..3: MIO40..45;
|
||||
- card detect `SDIO_SDDET`: MIO13;
|
||||
- card side is 3.3 V and PS side is 1.8 V;
|
||||
- no UHS 1.8 V card-side switching and no write-protect signal;
|
||||
- MIO46..53 are occupied by Ethernet/UART/MDIO functions, so SD1 must remain disabled.
|
||||
|
||||
Required SD device-tree intent:
|
||||
|
||||
```dts
|
||||
&sdhci0 {
|
||||
status = "okay";
|
||||
u-boot,dm-pre-reloc;
|
||||
bus-width = <4>;
|
||||
max-frequency = <50000000>;
|
||||
xlnx,has-cd = <1>;
|
||||
xlnx,has-power = <0>;
|
||||
xlnx,has-wp = <0>;
|
||||
no-1-8-v;
|
||||
disable-wp;
|
||||
};
|
||||
|
||||
&sdhci1 {
|
||||
status = "disabled";
|
||||
};
|
||||
```
|
||||
|
||||
Do not add `non-removable`. On the validated Linux 4.14 native SDHCI path, card presence is read directly from the SDHCI Present State register; `cd-inverted` does not correct native detection and must not be used as a substitute for the proper CD selector.
|
||||
|
||||
## SD0 card-detect selector
|
||||
|
||||
The validated HDF enabled SD0 on MIO40..45 but left `PCW_SD0_GRP_CD_ENABLE=0`, so generated FSBL selected EMIO 56 instead of schematic MIO13. Inspect the new HDF and generated `ps7_init.c` every time:
|
||||
|
||||
- if generation selects MIO13 correctly, do not apply a workaround;
|
||||
- otherwise prefer correcting the Vivado PS7 configuration/HDF and rebuilding FSBL;
|
||||
- the validated transition-only fallback, applied immediately before `bootm`, is:
|
||||
|
||||
```text
|
||||
sd0_cd_fix=mw.l 0xF8000008 0x0000DF0D; mw.l 0xF8000830 0x000D0037; mw.l 0xF8000004 0x0000767B
|
||||
```
|
||||
|
||||
Verify `0xF8000830=0x000D0037` in Linux. With no card inserted, the validated SDHCI Present State at `0xE0100024` was `0x01FA0000` (Card Present bit clear). Absence of `/dev/mmcblk0` is expected only when the operator confirms no card is inserted.
|
||||
|
||||
## Network and boot details
|
||||
|
||||
- GEM0 uses an Atheros 8031 PHY at MDIO address 0 with `rgmii-id`.
|
||||
- Discover MAC and IP values from the target/project; do not reuse a prior board address.
|
||||
- The prior validated build needed a documented PHY register fix before networking. Re-evaluate it against the supplied HDF/U-Boot rather than applying it blindly.
|
||||
- The initramfs may need `CONFIG_SYS_BOOTM_LEN=0x0F000000`; confirm against the generated FIT and available DDR.
|
||||
|
||||
## Acceptance markers
|
||||
|
||||
Cold-boot evidence must show, in order: U-Boot banner, `SF: Detected s25fl128s_64k`, exact `device 0 offset 0x520000, size <current-size>`, FIT loading, and the transition Linux login. In Linux require rootfs type `rootfs`, the four expected MTD regions, `mmc0` on `e0100000.sdhci`, live network/TFTP, and storage tools.
|
||||
|
||||
If no TF card is present, finish at `WAITING_FOR_MEDIA` and power off. After insertion, prove QSPI boot again, then identify `/dev/mmcblk0` and do read-only media checks before any partition or format operation.
|
||||
|
||||
@@ -0,0 +1,64 @@
|
||||
# Gated build and deployment workflow
|
||||
|
||||
## G0 - preflight
|
||||
|
||||
1. Identify the project and target board; read its board reference.
|
||||
2. Hash the user-provided HDF/XSA before copying it.
|
||||
3. Verify matching tool versions and enough VM/build-disk space.
|
||||
4. Discover live Windows/VM/board addresses and the TFTP interface. Prove both ping and actual file transfer when available.
|
||||
5. Capture serial boot output, current environment, QSPI probe, boot mode evidence, MTD layout and current storage without writing.
|
||||
6. Verify JTAG/power control and a tested recovery method. Stop before erase if recovery is not credible.
|
||||
7. Capture the build input fingerprint and run the reuse check.
|
||||
|
||||
## G1-G3 - build or verified reuse
|
||||
|
||||
For a rebuild, create a clean project, import the exact handoff, archive the generated baseline, then apply only reviewed board overlays. Configure an initramfs root filesystem and include at least:
|
||||
|
||||
- QSPI/MTD and board Ethernet/PHY support;
|
||||
- selected SD/eMMC host support;
|
||||
- `fdisk` or `parted`, `blkid`, FAT formatting, ext4 formatting/checking, `mount`, `umount`, archive, checksum and TFTP tools;
|
||||
- enough `CONFIG_SYS_BOOTM_LEN` for the uncompressed initramfs.
|
||||
|
||||
Build and package with logs and exit codes. Treat warnings about a detected flash differing from the device-tree expectation as unresolved board-profile drift even if access currently works.
|
||||
|
||||
Before deployment validate:
|
||||
|
||||
- generated DT contains the intended controller nodes and no conflicting alternate controller;
|
||||
- BOOT.BIN contains exactly the declared components;
|
||||
- image size fits its partition and DDR load range;
|
||||
- `qspi_cache.py check` or equivalent delivery validation passes;
|
||||
- all artifacts have stable size and SHA-256.
|
||||
|
||||
## G4 - boot region
|
||||
|
||||
Back up the known-good boot image when possible. Prefer the vendor-supported flash programmer with verify. If it fails, use a board-proven JTAG-to-DDR recovery path only after checking its address, size and marker protocol. Never improvise a recovery write on an unverified board.
|
||||
|
||||
After programming, fully remove and restore power. Confirm the intended U-Boot banner and QSPI probe. Repeat the cold boot; do not count a warm reset.
|
||||
|
||||
## G5 - image region
|
||||
|
||||
Use separate checked operations:
|
||||
|
||||
1. download the exact image and assert transferred byte count;
|
||||
2. compute RAM CRC/hash and match the manifest;
|
||||
3. probe QSPI and assert geometry;
|
||||
4. erase `ceil(image_bytes / erase_bytes) * erase_bytes`, bounded by the image partition;
|
||||
5. write exactly `image_bytes`;
|
||||
6. read back exactly `image_bytes` to a second RAM address;
|
||||
7. compare CRC/hash and every byte;
|
||||
8. only then save the QSPI-only bootcmd.
|
||||
|
||||
The bootcmd must make the origin unambiguous: probe QSPI, read the declared offset/length, apply only documented board fixes, and boot that RAM address. Do not add silent SD/network fallback unless explicitly required.
|
||||
|
||||
## G6 - hardware acceptance
|
||||
|
||||
For at least two complete power cycles, retain console evidence of:
|
||||
|
||||
- BootROM mode/source evidence, QSPI probe, exact QSPI read offset/length and FIT load;
|
||||
- Linux release, initramfs mounted as root, expected MTD partitions;
|
||||
- board Ethernet/PHY identity, live address and real TFTP transfer;
|
||||
- required storage host registration and device-tree/register evidence;
|
||||
- required deployment tools.
|
||||
|
||||
With removable media inserted, first perform a read-only gate: device enumeration, CID, capacity, partition table, current mounts, and bounded sample reads. Formatting and production deployment are separate destructive phases.
|
||||
|
||||
Reference in New Issue
Block a user