zynq: ECC-preserving (OOB) network restore-to-stock (hardware-validated) #57

Open
noah wants to merge 2 commits from feat/zynq-ecc-safe-restore into main
Owner

Makes the on-board backup/restore preserve the genuine stock OOB (the stock ECC bytes) so a network restore writes the boot slots byte-identical to original stock and the stock boot chain reads them. The alkane kernel writes NAND with soft-BCH 8b/512, which the stock Zynq U-Boot cannot decode; a plain nandwrite restore left the slots unreadable and bricked the board (SD-recovery only). This was the S17 .111 brick of 2026-11-13.

  • Backup format v2 (ALKSTKB2): carve captures each boot image data+OOB and stores it in the stock-backup region; v1 (data-only) backups are refused for restore.
  • restore_from_onboard: a scratch-block self-check proves nandwrite --noecc --oob round-trips the stock OOB BEFORE any boot slot is written (abort, never brick); each slot is written raw and read back raw (nanddump --noecc --oob); reboots only if all three verify.
  • Vendor-file restore-to-stock disabled on Zynq (no OOB in a vendor file).
  • Method-free progress logger ($ALKANE_OUTCOME_LOG) for sealed installs.

Hardware-validated on a bench S17: full stock<->alkane network cycle, genuine stock booted clean (lighttpd 401 antMiner Configuration), no brick, no SD card. HW finding: this mtd-utils nanddump defaults to --omitoob and ECC-correct, so read-backs must be --noecc --oob. 93 flash-crate tests green.

Pairs with alkane-sdk feat/zynq-boot-slot-mtd.

Generated with Claude Code

Makes the on-board backup/restore preserve the genuine stock OOB (the stock ECC bytes) so a network restore writes the boot slots byte-identical to original stock and the stock boot chain reads them. The alkane kernel writes NAND with soft-BCH 8b/512, which the stock Zynq U-Boot cannot decode; a plain nandwrite restore left the slots unreadable and bricked the board (SD-recovery only). This was the S17 .111 brick of 2026-11-13. - Backup format v2 (ALKSTKB2): carve captures each boot image data+OOB and stores it in the stock-backup region; v1 (data-only) backups are refused for restore. - restore_from_onboard: a scratch-block self-check proves `nandwrite --noecc --oob` round-trips the stock OOB BEFORE any boot slot is written (abort, never brick); each slot is written raw and read back raw (`nanddump --noecc --oob`); reboots only if all three verify. - Vendor-file restore-to-stock disabled on Zynq (no OOB in a vendor file). - Method-free progress logger ($ALKANE_OUTCOME_LOG) for sealed installs. Hardware-validated on a bench S17: full stock<->alkane network cycle, genuine stock booted clean (lighttpd 401 antMiner Configuration), no brick, no SD card. HW finding: this mtd-utils nanddump defaults to --omitoob and ECC-correct, so read-backs must be `--noecc --oob`. 93 flash-crate tests green. Pairs with alkane-sdk feat/zynq-boot-slot-mtd. Generated with [Claude Code](https://claude.com/claude-code)
noah added 2 commits 2026-11-18 15:08:47 -07:00
The alkane kernel writes NAND with soft-BCH 8b/512 ECC, which the stock Zynq
U-Boot nandboot reader cannot decode: an alkane-side `nandwrite -p` of the boot
slots leaves them unreadable by the stock boot chain ("ECC unrecoverable" loop),
and these boards have no U-Boot prompt, so recovery is SD-card only. This was
the S17 .111 brick of 2026-11-13.

Make the on-board backup/restore preserve the genuine stock OOB (the stock ECC
bytes) so a restore writes the boot slots byte-identical to original stock:

- Backup format v2 ("ALKSTKB2"): carve captures each boot image's data+OOB with
  nanddump and stores the blob in the stock-backup region; the manifest records
  blob offset/length and the on-NAND data length. v1 (data-only) backups are
  detected and refused for restore (they cannot reproduce stock ECC).
- restore_from_onboard: a scratch-block self-check proves `nandwrite --noecc
  --oob` round-trips the stock OOB on this board BEFORE any boot slot is written
  (abort, never brick); each slot is written raw (--noecc --oob) and read back
  WITH OOB; the board reboots only if all three slots are byte-identical to the
  backup.
- restore_to_stock (vendor FILE path): disabled on Zynq - a vendor file carries
  no OOB, so it cannot be restored without recomputing soft-BCH ECC (brick). The
  safe network return-to-stock is restore_from_onboard.

Removes the ECC-recomputing copy_abs. 93 flash-crate tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
zynq: fix the OOB read-backs (raw --noecc --oob); self-logging; HW-validated
verify / verify (pull_request) Failing after 9m0s
verify / verify-windows (pull_request) Skipped
source / check (pull_request) Skipped
117e572407
The ECC-safe restore is now proven end-to-end on a bench S17: stock -> Alkane
0.1.3 (v2 OOB backup carved) -> network restore-from-onboard -> genuine stock
booted clean (lighttpd 401 "antMiner Configuration"), no ECC-unrecoverable
brick, no SD card.

Two fixes found on hardware:
- This mtd-utils `nanddump` defaults to --omitoob and to ECC-correcting. The
  restore read-backs (scratch self-check and per-slot verify) must read RAW,
  WITH OOB (`nanddump --noecc --oob`): the boot slots carry the foreign stock
  ECC, which the alkane soft-BCH engine would "correct" into garbage, and the
  default omit-oob made the read-back shorter than the written data+OOB. Proven
  on the board that `nandwrite --noecc --oob` + `nanddump --noecc --oob` round-
  trips the stock OOB byte-for-byte.
- carve `dump_with_oob` now passes --oob explicitly instead of relying on the
  nanddump default (version-robust OOB capture).

Also adds a method-free progress logger (`$ALKANE_OUTCOME_LOG`) so a sealed,
DSH-driven from-stock install can report its own steps (root/carve/write/verify)
without relying on the harness to summarise - the lines are written by this code
and never carry the stock-access method. 93 flash-crate tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Some required checks failed
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 9m0s
Required
Details
verify / verify-windows (pull_request) Skipped
Some required checks were not successful.
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/zynq-ecc-safe-restore:feat/zynq-ecc-safe-restore
git checkout feat/zynq-ecc-safe-restore
Sign in to join this conversation.