docs(uboot): fold in the ADR 0023 draft, re-pin at 2026.07, desk plan for both boards - #177
Merged
Merged
Conversation
…, and lay out the desk plan for both boards The never-merged branch docs/adr-0023-uboot-mainline-handoff (491c0d9, 2026-07-25) proposed an ADR whose number was later taken by the 7-Zip ADR. ADR 0024 absorbed its conclusion (carry the fork's qts/*.h) but not its evidence or its gate. Both land here, in docs/uboot-mainline-port.md: - section 3.2a: the binary-level proof that the shipped SPL carries the fork's handoff tables (sys_mgr_init_table @0x0AAC8, IOCSR chains 0-2 @0x096B8/0x09718/0x097F0 found; mainline's absent), with the packing method so it stays reproducible, and what it does NOT prove; - section 6: a handoff-equality check that runs the same search against our built SPL -- no hardware, and it catches the one silent-brick delta a cold-boot test cannot. Version drift: Buildroot 2026.08 bundles U-Boot 2026.07, so the plan's "LATEST resolves to 2026.04" is stale. Re-pinned at 2026.07 (the DE25's tarball) after re-checking deltas 1-4 in that tarball: the missing raw-mode line, the dead TARGET_SOCFPGA_GEN5 guard (board.c:214-215), the 64-bit division in fs/exfat/time.c and FPGAPORTRST=0x1FF are all still there. The pin now rides the Buildroot bump, guarded by the resolved .config assertion plus the handoff check instead of a frozen version. Owner decisions of 2026-09-14, one rule -- mirror stock: the warm-reboot bridge behaviour is carried as the fork's C change (d6010efe50), the fork's QTS values are carried unmodified, and the fork's `mt` command is carried (23 lines) so the default environment is byte-identical to stock's and the parity check becomes a plain cmp. ADR 0024's header records the amendments; its body is untouched. docs/uboot-tasks.md is rewritten as the desk plan for BOTH boards: the DE10 U-series (wave A fans out to 13 agents, wave B integrates then verifies with a Fable pass; U6 hardware deferred indefinitely) and a new DE25 DU-series (the QSPI-audit build assertion, the now-redundant custom pin, FIT cross-tree reproducibility, TF-A signature, the section 13 decisions). Five owner questions are listed up front; nothing is started. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015UwVRTNY37gE8GQjEqvU5k
…I audit hook
Executes docs/uboot-tasks.md wave A (13 tasks, each independently verified).
DE10-Nano (ships nowhere; builds as part of the regular image):
- configs/mister_de10nano_defconfig: BR2_TARGET_UBOOT via Buildroot's
LATEST_VERSION pin (2026.07), socfpga_de10_nano + our fragment + our
env text file, FORMAT_CUSTOM u-boot-with-spl.sfp. NEEDS_GNUTLS is
TEMPORARY: the pristine board defconfig resolves TOOLS_MKEFICAPSULE=y
(host tool, needs gnutls); the real fragment turns it off and U2g
drops the line again. Stub uboot.fragment / uboot.env hold the build
green until the real ones land (staged, verified, integrated by U2g).
- scripts/check-uboot-parity.sh + test-uboot-parity.sh: structural
parity (4x SPL, Altera header, uImage CRCs, load address), the
default environment cmp'd against stock's 1,150-byte blob, command
table coverage. 39 fixture assertions pass against the stock blob.
- scripts/check-uboot-handoff.sh + scripts/lib/qts-tables.py +
test-uboot-handoff.sh: the ADR 0023 handoff-equality gate. The fork's
seven QTS tables are found in stock's SPL copy 0 at the plan's
offsets; pristine mainline's headers fail on the four diverged tables.
- docs/uboot-mainline-port.md 3.3: the warm-reboot bridge argument.
- uboot-patches/.gitkeep retired; patches live in patches/uboot/.
DE25-Nano:
- configs/mister_de25nano_defconfig: LATEST_VERSION instead of the
custom 2026.07 pin; patches/uboot/uboot.hash removed (Buildroot
2026.08 carries the same hash line). u-boot.itb byte-identical
before/after (f4e5c924...). TF-A stays on its custom v2.15.0 pin.
- external.mk: MISTER_UBOOT_DE25_QSPI_AUDIT, an UBOOT_POST_BUILD_HOOKS
hook guarded on the DE25 board defconfig, fails the build if the
fragment asks for, or the resolved .config carries, any
docs/de25-uboot.md section 7 QSPI symbol, if ENV_IS_IN_FAT is not y,
or if u-boot.itb carries a QSPI-write command string beyond the one
documented gate-closed linux_qspi_enable line. Negative test
(ENV_IS_IN_UBI=y in the fragment) fails naming section 7.
- scripts/ci-tests.sh: the Linux-side half (no fw_env.config naming an
MTD/UBI device in the DE25 rootfs).
- arm-trusted-firmware.hash: the v2.15.0 tag signature is verified
against the tagger's self-published key; trust anchor stated.
Staged outside the repo for U2g: the five DE10 patches, the real
fragment and env (byte-identical to stock's blob), and drafted-not-sent
upstream mails for the two U-Boot fixes and the DE25 mtdids guard.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015UwVRTNY37gE8GQjEqvU5k
…esk work closed; DE25 build repaired
DE10-Nano (builds on every image; ships nowhere):
- board/mister/de10nano/patches/uboot/: 0001 dead raw-sector hook guard,
0002 exFAT 64-bit division (both to be submitted upstream, drafts not
sent), 0003 the fork's QTS handoff headers unmodified, 0004 the fork's
`mt`, 0005 the fork's release-bridges-after-reset behaviour re-expressed
against misc_gen5.c, 0006 bound the Linux boot map at 64 MiB.
- uboot.fragment / uboot.env: the real deltas and stock's 21 env entries;
the built default_environment[] is byte-identical to stock's 1,150 B.
BR2_TARGET_UBOOT_NEEDS_GNUTLS gone (TOOLS_MKEFICAPSULE is off).
- external.mk: MISTER_UBOOT_DE10_CONFIG_ASSERT -- the resolved .config
and the SPL's raw-sector hook asserted at build time; deleting a
fragment line fails the build naming it.
- scripts/ci-tests.sh: offline U-Boot checks on every run (structure,
handoff tables in our SPL, no uboot.img / no .sfp in a release stage);
release.yml runs the full stock comparison where the blob already is.
lint-kernel-patches.sh lints both boards' U-Boot series.
- docs/verification/uboot-mainline.md: what was built, every allowed
diff, both check transcripts, the negative handoff run, and a
section-11 adversarial review (bridge argument, effective-env, mailbox
region, ih_ep/ih_load mixing hazard, watchdog takeover).
DE25-Nano:
- The factory loader's FIT acceptance closed by reference: the FIT on
Terasic's factory SD image is crc32-only, unsigned, same layout as ours
(de25-uboot.md 12; de25-boot-chain.md 7 row 6, 8.3).
- patches/arm-trusted-firmware/0001: BL31 boot+crash console to UART1,
the header UART -- the one change Terasic's own BL31 makes. BL31 lines
are now expected at bring-up (de25-uboot.md 11).
- FIT byte-identical across three clean trees (DU3); section 13
decisions dispositioned (DU4); wave-4 boot-path re-review logged (DU7).
- Field notes from another DE25-Nano port recorded as device facts
(de25-boot-chain.md 7b): no fpga load from U-Boot, HPS-first images,
post-JTAG SD quirks, random HPS MAC, unsigned bitstreams accepted.
- docs/de25-nano-overview.md: "how is this going to work", the chain link
by link, blockers ranked, first-session plan; README row.
- Kernel pin 7.2.5 (was 7.2.3 with no hash line after the RT bump), the
hash file symlinked to package/linux-rt/linux-rt.hash, and the DE25
defconfig added to the kernel-rt-7.2 Renovate manager so both move in
one PR. All 34 DE25 patches apply with offsets, no fuzz.
- package/linux-rt/linux-rt.mk: name LINUX_RT_KCONFIG_FILE only when the
package is enabled. pkg-kconfig registers `<file>: | linux-rt-patch`
for every package naming a kconfig file, so the DE25 tree's main
kernel config depended on an empty-version RT download; `make de25`
had been broken since ADR 0030. Full make de25 now green,
check-sdcard-de25.sh passes.
References to the private third-party DE25 trees removed from the DE25
docs and DTS comments; facts kept, Terasic's public branches cited where
the facts are Terasic's.
Gates run locally: check-defconfigs OK (3/3), test-uboot-parity 39/0,
test-uboot-handoff both fixtures, ci-tests.sh PASS (183+), lint-kernel-
patches 46/46 git-am-able, shellcheck clean, make de25 green.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015UwVRTNY37gE8GQjEqvU5k
mcfbytes
added a commit
that referenced
this pull request
Sep 16, 2026
docs(uboot): fold in the ADR 0023 draft, re-pin at 2026.07, desk plan for both boards
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
1 participant
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.
Docs only. Three things:
1. The orphan branch is folded in and deleted.
docs/adr-0023-uboot-mainline-handoff(491c0d9, 2026-07-25) proposed an ADR whose number was later taken by the 7-Zip ADR. ADR 0024 absorbed its conclusion but not its evidence: the binary-level proof that the shipped SPL carries the fork's QTS handoff tables (found at fixed offsets in stock's SPL copy 0; mainline's tables absent) and the no-hardware handoff-equality gate that proof enables. Both are nowdocs/uboot-mainline-port.md§3.2a and §6. The branch is deleted with this PR.2. Version drift fixed. Buildroot 2026.08 bundles U-Boot 2026.07, so ADR 0024's "LATEST resolves to 2026.04" was stale. Re-pinned at 2026.07 (the DE25's tarball) after re-checking deltas 1–4 in that tarball — all still present. ADR 0024's header carries the amendment; the body is untouched.
3. Owner decisions recorded and the desk plan written. Mirror stock: the warm-reboot bridge fix is carried as the fork's C change, the fork's QTS values are carried unmodified, and
mtis carried so the environment is byte-identical (amends ADR 0024 §Decision 5).docs/uboot-tasks.mdis rewritten as the plan for both boards — DE10 U-series (13-agent wave A, integrate, Fable review; U6 hardware deferred indefinitely) and DE25 DU-series — with five owner questions up front. Nothing is started.Also:
PLAN.md/TASKS.md"2026.04" pointers → 2026.07;docs/de25-nano-tasks.mdpoints at the DU-series.🤖 Generated with Claude Code
https://claude.ai/code/session_015UwVRTNY37gE8GQjEqvU5k