docs(de25): DE25-Nano recon — D0/D1 dossiers, implementation path, task status - #132
Merged
Conversation
…ability Phase D0 of the DE25-Nano readiness plan, executed as three multi-agent runs. Desk research only: no hardware, nothing built. de25-boot-chain.md (D0.1) closes §8's open questions. The SDM cannot boot from the microSD on this board [V], so the QSPI seam is permanent rather than an artifact of missing documentation. All DDR/pinmux handoff lives inside the QSPI bitstream [V]. saveenv writes back to wherever the env loaded from, so a FAT miss lands in QSPI [V]. Terasic publish the factory QSPI image, which was downloaded and hashed (golden_top_hps.jic, 16,777,447 B, sha256 e3d20c2d…b38a4). Q2/Q3/Q4 are parked with named blockers, handed to D2.2. §7's brick inventory went through a three-lens adversarial pass that amended 8 of 22 claims and added 7 new vectors; §9 records what survived and what was merely never challenged. One risk stands unmitigated: "no release writes QSPI" is enforced by prose only — git grep finds no board-identity assertion anywhere outside docs/, so ADR 0027 Decision 4 remains unimplemented. de25-fpga-reconfig.md (D0.2) confirms DP-9: fpga-region/DT-overlay is the Agilex-native idiom, so the UIO doorbell patches 0043-0045 are not ported. de25-patch-portability.md (D0.3) classifies all 40 unique patches. Run triage-first on owner direction rather than as the flat per-patch sweep the task list specified — risk-rate everything, deep-dive only the DE10/Cyclone-V set — which cut it from ~55 agents to ~20. Adds a target-series verdict per patch (shared / de10-only / de25-only) that the original task did not ask for, serving the goal of one repo building both boards off a shared base. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FYjrnzEEu4HzJSPWNAaRvm
…, channel namespace Phase D1. Docs only by design: no script, config, workflow or package file is touched, per ADR 0027 Decision 3. de25-readiness-ledger.md (D1.1) covers every de10nano / BR2_arm / zImage site outside board/mister/de10nano/ and docs/ — 54 files, 457 lines, 65 rows, 14 of them semantic blockers. Each row carries a one-sentence "when you touch this, do this instead" instruction, which is the actual product. The reconciliation command is git grep, not grep -r, and that matters: the grep wrapper in this environment honours .gitignore, so the same query returns 457 lines here and 15,796 under GNU grep, which walks work/ and .claude/. A coverage count that depends on the operator's grep is not a coverage count. Three couplings ADR 0027's "four semantic couplings" did not anticipate: lint.yml hard-codes ~20 board paths and fails silently, so a second board would go unlinted behind a green check — a live hole for the DE10 today, not only a DE25 problem; the renovate.json + renovate-hash-sync.yml bump axis, where a new defconfig added without them lands a stale kernel pin; and release.yml's 13 coupled lines. D1.2's arch-assert generalization is designed as a section of the ledger and holds fail-closed for the DE10, but the code change is still owed — both guards hard-assert ^BR2_arm, so D2.1's aarch64 defconfig cannot land until it exists. D1.3 adds forward-pointer sections reserving the DE25 channel namespace: downloader-contract.md §13 and a DE25 section in db-json-versioning.md. Both state the names are reserved, not implemented. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FYjrnzEEu4HzJSPWNAaRvm
…sk-list status Two documents the task list never anticipated, plus the status pass over it. A third-party DE25-Nano that boots Linux to the MiSTer MENU was made available as reference (kernel and U-Boot repos, read-only, nothing adopted, no code copied). de25-reference-implementation.md analyses it and root-causes the two symptoms reported second-hand. Neither is a property of Agilex 5: "only N cores in firmware" was literal — cores staged into QSPI as RSU images, whose hardcoded slot map consumes the whole 16 MiB device — and "very slow" was a staging path pushing bitstreams through the FCS mailbox in 4096-byte writes with a 0.05 s settle each, ~817 round-trips and >=41 s of sleep() for a 3.35 MB core, then a reboot. The fast path he intended is the one he never tested end to end. That document is partly salvaged. A spend limit killed 5 of 9 agents mid-run; four research legs had completed, so their output was recovered from the run journal rather than discarded. It is marked unrefuted throughout because the adversarial pass never ran, and one of its claims was already found false and is annotated in place as a worked example of why that marking matters. de25-implementation-path.md is the settled path. Binding the mainline FPGA manager needs no carried patch — a two-string DT fallback compatible binds the stock driver, since both match tables are data-free — but binding is not programming, and mainline svc lacks behaviour Terasic's vendor tree keys off the agilex5 compatible. The one mainline reconfiguration attempted on real silicon wedged a board, so §2.6 specifies the four-step hardware test that settles it. Confidence there is deliberately low. Kernel pinned to 7.2: 6.18 has no clk-agilex5.c, so clkmgr never probes and every consumer including mmc0 defers forever. The mmc0 DMA fault is a separate problem the version pin does not fix — it is a vendor-vs-mainline driver delta, not a regression, and needs a carried sdhci-cadence patch coupled to its DTS string. §1.1 exists to stop those two being read as one fix. de25-nano-tasks.md records D0/D1 completion and corrects a gate drawn at the wrong level: D2 was read as uniformly hardware-gated, but D2.1's own acceptance criterion is a local green build, and D2.3/D2.4 are largely authorable now. The closing section also records why a verify stage must not run concurrently with the stage producing what it verifies — D0.1 was launched that way, and 17 of its 22 brick-risk claims turned out to be generated by the research it ran alongside. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FYjrnzEEu4HzJSPWNAaRvm
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
There are a few internal documentation inconsistencies (notably mismatched reconciled counts and a cross-doc contradiction about the two-string DT fallback vs dtbs_check) that should be corrected to keep the docs self-consistent and reliably actionable.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Docs-only update that closes out DE25-Nano D0 (recon) and D1 (readiness guards) deliverables and records the chosen implementation path (kernel/U-Boot/DTS/FPGA reconfig approach), without changing build/CI/code.
Changes:
- Adds DE25-Nano dossier docs covering FPGA reconfiguration, kernel patch portability, readiness ledger, and the implementation path/decisions.
- Updates the DE25 task list to mark D0/D1 complete and clarify D2 gating/sequencing.
- Reserves DE25-specific downloader/db.json channel namespace via forward-pointer sections.
File summaries
| File | Description |
|---|---|
| docs/downloader-contract.md | Adds DE25-Nano reserved channel namespace clarification and its implications for the downloader contract. |
| docs/de25-readiness-ledger.md | New ledger enumerating DE10-coupled references and what must/need-not be parameterized for DE25 readiness. |
| docs/de25-patch-portability.md | New audit classifying kernel patches by arm64 portability and target series (shared vs board-specific). |
| docs/de25-nano-tasks.md | Updates task status/sequence and clarifies which D2 items are hardware-gated vs buildable now. |
| docs/de25-implementation-path.md | New “settled path” doc capturing owner decisions and mainline-first implementation rationale. |
| docs/de25-fpga-reconfig.md | New DE25 FPGA reconfiguration dossier (fpga-region/DT overlay flow, gaps, risks, measurement plan). |
| docs/db-json-versioning.md | Adds DE25 reservation note clarifying it is not a second versioning scheme. |
Review details
Suppressed comments (2)
docs/de25-readiness-ledger.md:31
- This paragraph hard-codes a "51 of the 55 files" count, but §7 shows a different total (54). Since the exact split is secondary to the point being made, removing the hard-coded numbers avoids another source of drift.
Everything else — 51 of the 55 files — says `de10nano` because that is where the board's files
*live*, or says `zImage_dtb` because that is what today's only kernel artifact is *called*.
docs/de25-readiness-ledger.md:36
- This sentence refers to "fifty-five" files, but §7’s reconciliation table reports 54 distinct files hit. It should match the reconciled number (or avoid the specific count).
real design decisions to fifty-five.
- Files reviewed: 8/9 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
…ualify two-string dtbs_check claim Ledger intro said 55 files where §7's reconciliation table says 54; the hard-coded 51/55 split is replaced by prose so the headline cannot drift from the table again. fpga-reconfig's "free and forward-compatible" now says at runtime only, cross-referencing implementation-path §2.5, which records that dtbs_check warns on the two-string form today. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01FYjrnzEEu4HzJSPWNAaRvm
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Docs-only. Closes out phases D0 (recon) and D1 (readiness guards) of the DE25-Nano plan (
docs/de25-nano-tasks.md, ADR 0027) and records the settled implementation path. Nothing is built; no code, config, or CI is touched.New / expanded dossiers
docs/de25-boot-chain.mdu-boot.itb→ Linux. SDM cannot boot from microSD, so the QSPI seam is permanent. Factory SPL contract extracted (FAT partition 1, FIT at0x82000000, ATF, FIT signature enabled with no keys). Factorygolden_top_hps.jicidentified and byte-verified. Brick-risk register with refuted/amended claims marked.docs/de25-fpga-reconfig.mdfpga-region+ DT overlay is the Agilex-native idiom; UIO doorbell patches 0043-0045 are not ported. Main_MiSTer owns the load; the image only has to expose the hardware.docs/de25-patch-portability.mddocs/de25-readiness-ledger.mdlint.yml(fails silently), the renovate bump axis,release.yml. Canonical query isgit grep, not the ugrep wrapper.docs/de25-reference-implementation.mddocs/de25-implementation-path.mdclkmgr), carriedsdhci-cadence40-bit DMA mask patch, mainlinesvc/FPGA manager, two-partition card, no vendor U-Boot, no VAB. §2.6 is the four-step fabric-programming test to run first on real hardware.Task-list changes
Open assumption
Whether mainline
stratix10-svccan actually program the Agilex 5 fabric. Binding is proven; programming is not. Decision 9 keeps a vendor-patch escape hatch.🤖 Generated with Claude Code
https://claude.ai/code/session_01FYjrnzEEu4HzJSPWNAaRvm