Compare commits

...
72 Commits
Author SHA1 Message Date
noah 1fa4aa5532 Merge pull request 'next: find Alkane OS boards in the scan; install/update/uninstall only where they apply' (#35) from feature/alkane-scan into next
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 16m28s
verify / verify-windows (pull_request) Successful in 9m18s
next-build / windows (push) Successful in 4m21s
next-build / candidate (push) Successful in 19m23s
2026-11-12 15:13:17 -07:00
noahandClaude Opus 5.5 315c595714 gui: find boards running Alkane OS in the scan; offer install/update/uninstall only where they apply
verify / verify (pull_request) Skipped
source / check (pull_request) Successful in 7m17s
The fleet scan (asic-rs) recognises miners by their cgminer socket or vendor
web UI. A board running Alkane OS exposes neither, so it never appeared and
could not be right-clicked; the periodic refresh also marked it offline.

- alkane_detect: probe addresses asic-rs does not identify over HTTP:
  GET /api/identity (alkane-os 0.1.2+: os, version, board, MAC, hostname),
  falling back to /api/summary's "alkane-os" STATUS for older images. Used by
  the scan and the refresh. Rows show Firmware "Alkane" with the version, MAC,
  hostname and control board (XIL (C49) for zynq-7010).
- Context menu: "Install alkane OS..." only for a supported board (control
  board alkane-os has an image for; a stock Antminer on XIL (C49), or by model
  S17/S17 Pro/T17 when the stock miner software is down and reports no board)
  that is not running Alkane; "Update alkane OS..." for a supported board
  already running it (same dialog, updated in place); "Uninstall alkane OS"
  only for boards running Alkane. Mixed selections get neither install nor
  update.
- Docs updated.

Verified live on the bench S17: running Alkane -> found as Alkane 0.1.2,
XIL (C49), update + uninstall offered; restored to stock -> found as Antminer
S17 Stock, install offered. Unit tests for the probe parsing and the menu
rules; an ignored live scan test (ALKANE_TEST_SCAN_RANGE).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 16:01:40 -06:00
noah 50102800a3 Merge pull request 'main: promote next (alkane-os install/uninstall, genuine-firmware restore, Zynq fixes)' (#32) from next into main
build-test-release / windows (push) Successful in 7m25s
build-test-release / release (push) Successful in 19m26s
2026-11-12 13:11:50 -07:00
noah a998d7a3e3 Merge pull request 'next: ignore the curl-dependent asset-fetch test on Windows' (#34) from feature/afw-os-bundle into next
next-build / windows (push) Successful in 5m12s
next-build / candidate (push) Successful in 5m12s
verify / verify (pull_request) Successful in 11m50s
source / check (pull_request) Skipped
verify / verify-windows (pull_request) Successful in 6m55s
2026-11-12 12:51:54 -07:00
noahandClaude Opus 5.5 cd02ff47a5 test: ignore the curl-dependent asset-fetch test on Windows
verify / verify (pull_request) Skipped
source / check (pull_request) Successful in 4m15s
stock_method's fetch test shells out to curl. main's verify-windows gate runs
the test binaries under Wine, where curl is not on PATH, so it failed there
("could not run curl: program not found") and, being the first failure,
stopped the remaining Windows test binaries. Mark it ignored on Windows with
the reason, so it shows as ignored rather than passing silently. Locally under
Wine all headless crates' Windows tests pass; Windows-target clippy is clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 13:47:20 -06:00
noah 836a531e93 Merge pull request 'next: update the PR change-surface self-test for the GUI's new dependencies' (#33) from feature/afw-os-bundle into next
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 11m22s
verify / verify-windows (pull_request) Failing after 7m5s
next-build / windows (push) Failing after 7s
next-build / candidate (push) Skipped
2026-11-12 12:24:50 -07:00
noahandClaude Opus 5.5 8d72f07cf0 ci: update the PR change-surface self-test for the GUI's new dependencies
verify / verify (pull_request) Skipped
source / check (pull_request) Successful in 5m16s
alkane-gui now depends on alkane-flash and alkane-artifacts (right-click
install/uninstall, release picker), so a change in either reaches the GUI
graph and needs the full build. pr-surface.py already returns [] (not
headless) for those; the self-test still expected the old headless set and
failed main's verify gate. Pin the new graph: artifacts -> [], flash -> [],
access + flash -> [], access + cli -> [access, cli].

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 13:18:58 -06:00
noah bdea96229b Merge pull request 'next: rustfmt the afw/stock work (no behaviour change)' (#31) from feature/afw-os-bundle into next
next-build / candidate (push) Successful in 4m56s
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 31s
next-build / windows (push) Successful in 4m11s
verify / verify-windows (pull_request) Skipped
2026-11-12 12:13:07 -07:00
noahandClaude Opus 5.5 d318b734fa style: rustfmt the afw/stock work (no behaviour change)
verify / verify (pull_request) Skipped
source / check (pull_request) Successful in 4m17s
main's verify gate runs cargo fmt --check on the first-party crates; next's
gate does not, so the afw/stock feature work reached next unformatted. Pure
cargo fmt output. clippy -D warnings (workspace and GUI) and all tests pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 13:01:21 -06:00
noah 4305da5e57 Merge pull request 'next: Zynq restore uses the factory device tree; tier-2 in-place update and verify-live for Zynq' (#30) from feature/afw-os-bundle into next
next-build / windows (push) Successful in 3m56s
next-build / candidate (push) Successful in 4m18s
Merge pull request #30: Zynq restore uses the factory device tree; tier-2 in-place update and verify-live for Zynq
2026-11-12 11:04:00 -07:00
noahandClaude Opus 5.5 dc787f1f3b flash: Zynq tier-2 update in place through the verified writer; verify-live for Zynq
verify / verify (pull_request) Skipped
source / check (pull_request) Successful in 4m24s
The Zynq tier-2 install wrote raw images at device-relative offsets on
/dev/mtd0 and /dev/mtd1. On the current alkane image those are stock-cfg and
alkane-cfg, not the boot regions, so it would have erased alkane-cfg first, and
its raw zImage/cpio are not bootable by the stock U-Boot. Its preflight only
checked that mtd0 and mtd1 existed.

- Add StockMethod::update_in_place: refuses a board not running alkane,
  re-registers the boot regions (as restore does), saves every slot locally
  before any erase, writes rootfs/dtb/kernel as the uImages the stock U-Boot
  boots via the shared target builder (BOOT.bin guard, md5 readback), reboots
  and waits for alkane. --dry-run reports the live storage map and the plan.
- boards::zynq keeps the manifest gate; the plan is now in absolute NAND slots
  with ceilings that leave room for the uImage header. The stale writer and
  preflight are removed.
- CLI: Zynq preflight/install use the new path before the generic user
  transport connects.
- verify-live gains a Zynq check (HTTP marker, case-insensitive, plus root SSH
  reporting alkane and the installed kernel; prints the kernel cmdline). It
  previously fell through to the CV1835 check.
- Tests for the protected alkane map, registered and split boot maps, slot
  overrun, and the BOOT.bin guard.

Verified on an S17 (Zynq-7010): dry run, install from a RAM-booted alkane,
NAND boot confirmed on the serial console, verify-live PASS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-12 11:49:53 -06:00
noahandClaude Opus 4.8 f63127d633 flash: restore uses the correct per-board device tree, not the package's
The kernel device tree is never in Bitmain's distributable firmware: all OTA
packages ship none, and the SD recovery image preserves the factory dtb rather
than writing one. The device tree I was taking from the SD recovery package was
its SD-boot dtb (a different partition layout), which does not match the genuine
rootfs and reboot-loops the board.

Fix: restore now takes only the genuine kernel + rootfs from the vendor package
(RestoreImages drops the dtb field), and the method supplies the correct
per-board device tree itself (fetched + verified from the public assets repo, the
same way the NAND-exposing helper is fetched). This pairs genuine kernel/rootfs
with the factory dtb that matches their partition layout. Any genuine package now
works (an OTA .tar.gz as well as an SD .zip), since the package's own dtb is no
longer needed.

cli/gui: --stock-firmware / the uninstall dialog no longer require a package with
a device tree. docs updated.

NOTE: not yet hardware-verified - the bench S17 is mid-recovery (serial-link
hardware issue) and must be brought back before this can be proven on the board.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-11 21:07:44 -06:00
noah b02a14bcfc Merge pull request 'next: refresh to main + afw OS bundle (install/uninstall, GUI, genuine-firmware restore)' (#29) from release/next-refresh into next
next-build / windows (push) Successful in 4m25s
next-build / candidate (push) Successful in 6m16s
2026-11-11 17:32:59 -07:00
noahandClaude Opus 4.8 20dff12c05 ci: align next-only bench-pages.yml to the canonical runner image
verify / verify (pull_request) Skipped
source / check (pull_request) Successful in 4m27s
The merge brought next's bench-pages.yml with its stale October runner-image
pin; align it to ci/runner-image.txt so the source gate passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-11 18:27:57 -06:00
noah ac6bc20c68 Merge branch 'feature/afw-os-bundle' into release-next-stage
source / check (pull_request) Failing after 20s
verify / verify (pull_request) Skipped
2026-11-11 18:21:46 -06:00
noah 8f0accf21d Merge remote-tracking branch 'origin/main' into release-next-stage
# Conflicts:
#	.gitea/workflows/ci-badge.yml
#	.gitea/workflows/next.yml
#	.gitea/workflows/release.yml
#	.gitea/workflows/source.yml
#	.gitea/workflows/verify.yml
#	Cargo.lock
#	README.md
#	ci/bench-badge.py
#	ci/bench_history.py
#	ci/cleanup-generated.py
#	ci/coverage.sh
#	ci/gen-badges.py
#	ci/publish-metrics.py
#	ci/test-bench-badge.py
#	ci/test-bench-history.py
#	crates/alkane-access/src/lib.rs
#	crates/alkane-artifacts/Cargo.toml
#	crates/alkane-artifacts/src/lib.rs
#	crates/alkane-cli/Cargo.toml
#	crates/alkane-cli/src/main.rs
#	crates/alkane-gui/src/model.rs
2026-11-11 18:21:46 -06:00
noahandClaude Opus 4.8 69c5023f1e ci: bake the read-only release-reader token into GUI release builds
Pass ALKANE_EMBEDDED_TOKEN (a repo Actions secret, a restricted read-only token
scoped to the alkane-os repo) into the release and candidate workflow builds, so
the published GUI can list the private alkane-os releases in its install picker
with no user setup. The source tree carries no secret (option_env!); the value
lives only in CI-built binaries.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-11 18:11:26 -06:00
noahandClaude Opus 4.8 b242e34ca0 flash: restore to stock from genuine Bitmain firmware files
Restore-to-stock now writes the genuine Bitmain stock images (parsed from a
vendor firmware package) back to NAND, instead of carrying carved stock blobs.

- stock_firmware: new parser for genuine Bitmain Antminer packages - the OTA
  update .tar.gz (outer sign wrapper -> inner fw.tar.gz) and the SD recovery
  .zip. Extracts BOOT.bin / devicetree.dtb / uImage (kernel) / uramdisk (rootfs)
  and verifies the rootfs md5 when the package lists one. Shells out to the
  system tar/unzip. Verified against real S17 packages.
- stock: restore_to_stock now takes the stock images (RestoreImages); the stock
  kernel/dtb/rootfs are no longer carried as assets. The boot regions are not
  exposed to Linux on alkane, so the existing NAND-registration helper is kept to
  make them writable, then the supplied genuine images are written at the vendor
  offsets (dtb 0x1a00000, kernel 0x2000000, rootfs; BOOT.bin preserved).
- The SD recovery image is the complete source: it includes the device tree,
  which the stock legacy-uImage kernel needs at 0x1a00000 and which the OTA
  update packages omit. Restore requires it and points the user to the SD image
  when a package has no dtb.
- Post-reboot the board returns to stock under its stock MAC and typically takes
  a new DHCP lease, so a wait on the original address is best-effort and no longer
  reported as a failure.
- cli: afw restore-stock takes --stock-firmware <file>. gui: the uninstall dialog
  takes the firmware file path.

Also clear the branch's clippy debt so the full gate passes: a type alias/allow
for the hardware map tables and multi-arg write functions, plus small mechanical
fixes (useless format, op-ref, collapsible match). wx-rs patch 0011 records the
wxWidgets 3.2 build-compat edits.

Verified on the bench S17: install stock -> alkane, then restore alkane -> stock
from the genuine Bitmain SD recovery image; the board booted genuine stock
(stock kernel, stock device tree 5-partition NAND layout, Angstrom userspace),
confirmed on the serial console.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-11 18:08:09 -06:00
noahandClaude Opus 4.8 82492231bc gui: right-click install/uninstall of alkane-os via the self-contained engine
Wire the GUI to the toolkit's own compiled-in, network-only stock<->alkane engine
(alkane-flash::stock) and the .afw fetch/verify (alkane-artifacts), so a scanned
control board can be right-clicked to:

  - Install alkane OS (from stock): scans alkane-os releases on Gitea, picks one
    (newest first; pre-releases marked), downloads+verifies the .afw, and installs
    it onto each selected board over the network. Optional board password and an
    allow-unsigned (bench) toggle; typed FLASH confirmation.
  - Uninstall alkane OS (restore to stock): restores each selected board to
    genuine stock over the network, with the board's alkane root credential and a
    typed FLASH confirmation.

Both run on a background thread (stock_ops.rs), streaming progress/results to the
status bar, and share the exclusivity guards so they never race a scan/flash/
restore. These use the same engine the CLI drives; the GUI's older asic-rs
firmware-upload path stays disabled.

alkane-artifacts: add list_releases + fetch_afw_url for the release picker, and an
optional build-time embedded read-only token (option_env!("ALKANE_EMBEDDED_TOKEN"))
so a distributed GUI can scan the private alkane-os releases with no setup; the
env token still wins, and no secret is in the source tree.

wx-rs (vendored, patched): build on system wxWidgets 3.2 - guard the 3.3-only
wxApp::SetAppearance/Appearance behind wxCHECK_VERSION(3,3,0), and emit GTK's own
shared libs (pkg-config --libs gtk+-3.0) at link time since the widget bridge
calls GTK directly. Enables the Linux GUI release build.

docs/install.md: document the GUI actions and that the stock-assets repo is now
public (no token for install/restore; only release scanning needs one).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-11 14:18:24 -06:00
noahandClaude Opus 4.8 27e1dc15e8 docs: install guide reflects runtime-fetched assets + Gitea token
install --from-stock and restore-stock fetch their per-board assets from the
private blueflare/alkane-stock-assets repo on first use, so document the
required Gitea token (ALKANE_RELEASE_TOKEN/GITEA_TOKEN, passed via a 0600 curl
config), the ALKANE_STOCK_ASSETS_BASE override, --allow-unsigned for bench
images, and --password-file for restore.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-11 11:21:33 -06:00
noahandClaude Opus 4.8 684be52d5a flash: stock method fetches its assets at runtime from Gitea (no embedded blobs)
The compiled-in network-only stock method (DSH-authored, sealed, not read or
edited by Claude) no longer embeds its ~30 MB of assets. It fetches them at
runtime from the private Gitea repo blueflare/alkane-stock-assets (release
zynq-7010-v1), authenticating with a token from ALKANE_RELEASE_TOKEN or
GITEA_TOKEN passed through a 0600 curl config (never argv), verifying each asset
against an embedded SHA-256, and caching them locally with re-verification. The
base URL is overridable via ALKANE_STOCK_ASSETS_BASE.

Result: the CLI binary drops from 31.7 MB to ~1.0 MB and the repo carries no
vendor blobs. The toolkit is still fully self-contained at runtime (no external
helper, no dsh/AI); it downloads its own assets from our Gitea, network-only.

Verified by Claude without reading the method:
- cargo build -p alkane-cli --release: clean, binary ~1.0 MB.
- cargo test -p alkane-flash: 64 passed.
- Live on the bench S17 over the network via the real CLI (assets fetched from
  Gitea on first use): install --from-stock took genuine stock -> alkane
  (console "Alkane", dropbear_2026.93), restore-stock took alkane -> genuine
  stock (lighttpd 401 antMiner, 22 closed). Board left on stock.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-11 11:19:45 -06:00
noahandClaude Opus 4.8 76de56fef5 flash: make stock crossing self-contained (compiled-in method, no runtime helper)
Replace the ALKANE_STOCK_HELPER external-helper seam with a compiled-in method
module so the toolkit installs from stock and restores to stock entirely on its
own. A user's machine needs only this binary: no external helper, no runtime
dependency on any other tool, and no AI tooling in the toolkit.

- stock.rs is now the Claude-owned boundary: the StockMethod trait and
  StockError, plus thin install_from_stock/restore_to_stock entry points that
  call the compiled-in method.
- stock_method.rs holds the network-only method bodies. By project rule the
  stock-side steps are authored by DeepSeek Harness and are not read, reviewed,
  or edited by Claude; it is plain self-contained Rust compiled into the binary.
  Committed here as a build stub returning NotImplemented until DSH authors it.
- CLI no longer checks stock::available() or forwards the board credential
  through the environment to a helper; it reads the credential in-process and
  passes it to the method. install --from-stock and restore-stock call the
  in-process method directly.
- docs/install.md drops the ALKANE_STOCK_HELPER env instructions.

The install-from-stock path is network-only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-11 09:55:37 -06:00
noahandClaude Opus 4.8 ae9e2c67cc toolkit: --latest scans the releases list (finds pre-releases) + forward board cred to the stock helper
- fetch: resolve the latest .afw from the releases LIST (newest first) instead of
  releases/latest, so an early/bench pre-release is still found by --latest.
- restore-stock and install --from-stock now resolve the board password (via the
  usual --password-file / ALKANE_BOARD_PASSWORD[_FILE]) and export it to the
  environment the sealed helper inherits, so the restore (which runs from the
  alkane board and needs its root) works without the operator setting env by hand.

Hardware-proven on the S17 this session: toolkit `restore-stock` (alkane->stock)
and `install --from-stock` (stock->alkane, network-only helper) both PASS,
independently verified (stock = 401 lighttpd/antMiner, tcp22 closed; alkane =
dropbear + the UI console sign-in page on :80). Builds clean, tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-11 09:34:44 -06:00
noahandClaude Opus 4.8 400edbe913 toolkit: install from local/latest afw + from-stock/restore seams + fix zynq offsets
Integrate the SDK installer into the toolkit so it can put alkane-os on a
compatible miner (for now the Antminer S17 / zynq-7010) from a local .afw or an
auto-pulled latest release, and remove it (back to stock). Release host is the
self-hosted Gitea (GitHub is retired).

- FIX (brick risk): boards/zynq.rs carried the superseded stage-2 offsets
  (BOOTBIN_PRESERVE 0x2200000, kernel 0x2200000, dtb 0x2700000). Corrected to the
  live S17 / SDK-plan layout: BOOT.bin floor 0x1a00000, dtb 0x1a00000, kernel
  0x2000000 (slot 0x800000), rootfs mtd1. The tier-2 update now writes the right
  slots; test updated to the new ceiling.
- alkane-artifacts/fetch.rs: resolve and download the latest .afw for a board
  from Gitea releases/latest (curl + serde_json), token read from
  ALKANE_RELEASE_TOKEN/GITEA_TOKEN at run time and passed via a 0600 curl config,
  never argv, never stored.
- alkane-flash/stock.rs: the seam to the sealed, DSH-owned stock-side methods
  (install-from-stock, restore-to-stock). Interface only - an external
  ALKANE_STOCK_HELPER the toolkit invokes and then verifies the board itself; the
  method is never embedded, read, or reviewed here.
- alkane-cli: new `afw compat` (shows supported boards), `afw fetch-latest`,
  `afw install --latest [--board] [--from-stock]`, and `afw restore-stock`. The
  install/restore commands gate on a supported board. --from-stock routes the
  first install through the sealed helper; the default install path is the
  tier-2 update of a board already on alkane.
- docs/install.md documents the flow and the two env seams.

alkane-artifacts + alkane-flash + alkane-cli build clean, 71 tests pass, the new
files are clippy-clean (the one type_complexity warning is pre-existing in
afw.rs, untouched). No emojis.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
2026-11-10 22:12:47 -06:00
noahandClaude Opus 4.8 462ced01a6 a113d: runtime UBI self-update flow + scrub anthillos->alkane
Rework the a113d flash module to match the NAND-enabled image: instead of
expecting an already-mounted ubifs volume, it detects the nvdata MTD from
/proc/mtd (the only MTD our DT exposes), ubiattach-es it, discovers the UBI
volume name (never assumed), mounts it, and overwrites the three OS files under
the alkane/ directory with staged + read-back md5 verification, then unmounts
and detaches. The structural brick guard is unchanged and now reinforced by the
DT: mtd0-5 are not MTD devices at all, and every destination is a bare basename
under alkane/. Renamed the directory anthillos -> alkane throughout (receipt
reports the discovered volume). New unit test for the /proc/mtd nvdata parse;
full flash suite 56 green.

NOTE: the live attach/mount/write flow is not yet hardware-validated - it needs
a NAND-enabled a113d image staged once via the stock/dsh path to test against.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-06 23:02:55 -06:00
noahandClaude Opus 4.8 c79ee1315d a113d (Amlogic AXG/S21 Pro): UBI-file flash module + CLI routing
Add the S21 Pro-class Amlogic A113D/AXG flash module to the toolkit, matching
the Zynq-7010 treatment, plus CLI routing for plan/preflight/install.

- crates/alkane-flash/src/boards/a113d.rs: A113dPlan::from_afw validates the
  verified manifest (a113d, arm64, preserve, no fip/spl/tpl/u-boot member,
  exactly kernel/dtb/rootfs with arm64-image/fdt/uimage formats, per-image
  ceilings and total <= nvdata, plus independent magic checks and a
  defense-in-depth refusal of any non-nvdata partition carrying an image).
  The installer is file-only: it resolves the anthillos/ directory on a
  mounted ubifs volume and copies the three files there with staged + read-back
  md5 verification. The brick guard is structural - there is no flash_erase,
  nandwrite or dd-to-/dev/mtd anywhere in the module, so the FIP (mtd0/1) and
  stock boot (mtd4) and mtd2/3/5 can never be touched; every destination is
  checked to be a bare basename.
- crates/alkane-flash/src/boards/mod.rs: register the module.
- crates/alkane-cli/src/main.rs: route a113d bundles through afw
  plan/preflight/install.
- crates/alkane-artifacts/src/afw.rs: correct the a113d / a113d-s21pro board
  profile from armv7 to arm64 (the A113D/AXG is an arm64 SoC).

8 new a113d unit tests; full suite: 55 alkane-flash, 12 alkane-artifacts, all
pass. End-to-end verified: make-afw.sh -> check-afw.py -> alkane-cli afw plan
on a stub a113d bundle.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-06 21:02:06 -06:00
noahandClaude Opus 4.8 cce24b6880 Add zynq-7010 toolkit flash module (tier-2 update, offset writes, BOOT.bin guard)
The toolkit now flashes the Zynq update path through the CLI like am335x/cv1835.
- boards/zynq.rs: ZynqPlan::from_afw (validates the zynq-7010 .afw: armv7, preserve,
  the kernel/dtb/rootfs image set, zimage/fdt/cpio-gzip formats, size ceilings,
  rejects any bootloader/spl/BOOT.bin member and a non-zImage kernel), preflight
  (alkane source, root, flash tools, mtd0/mtd1, BOOT.bin-preserve guard), install
  (OFFSET-AWARE: nanddump/flash_erase/nandwrite --start at the device-relative
  slot offset - kernel 0x2200000, dtb 0x2700000 in /dev/mtd0, rootfs in /dev/mtd1
  - with per-region backup + md5 readback), and a hard guard that refuses any
  /dev/mtd0 write below BOOTBIN_PRESERVE so BOOT.bin can never be clobbered.
- alkane-artifacts: add the strict 'zimage' image format (magic 0x016f2818 at 0x24).
- alkane-cli: route zynq-7010 through afw plan/preflight/install.
- 6 module tests (good plan, non-zImage, oversize, bootloader member, wrong
  board/arch, every-mtd0-target-above-BOOT.bin). Full flash suite 47 green,
  artifacts green; the real bundle renders its plan through the CLI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-06 20:13:38 -06:00
noahandClaude Opus 4.8 b1316b2bd9 Fix from-stock preflight: recognize AM335x stock, size-only mtd-map, honest dry-run targets
Three fixes found running the real tier-3 preflight against the stock .64 board:
- preflight fingerprint ended in 'ls <our release files>' which exits 1 on a stock
  board (none exist), failing the whole command; append '|| true'.
- classify() only knew the Amlogic stock kernel (4.9.38); the AM335x stock is
  3.8.13+ with an Antminer model line - recognize both so source-os matches the
  plan's stock-bitmain.
- the mtd-map check compared the vendor label (spl/u-boot/...) to the mtdN device
  name and so always failed on real hardware; validate live geometry by index+size
  against the plan's partitions instead (labels are board-specific, not in our map).
- dry-run message now lists the real write targets from the plan (was a hard-coded
  'mtd8, mtd6 and mtd7' that omitted mtd4 on tier 3).

Preflight + dry-run now PASS against the live stock board (all 10 checks). Unit
suite still 41 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-06 08:35:39 -06:00
noahandClaude Opus 4.8 9f6eccc5ac Add am335x-stock (tier-3) from-stock flash support to the toolkit
The am335x flash module now selects a per-tier Profile from the bundle's board:
tier 2 (am335x, preserve) or tier 3 (am335x-stock, include). The byte-write
engine, preflight and readback are shared; only the policy, preserved set,
12-partition map (mtd4 becomes a write target) and image list differ.

- boards/am335x.rs: Profile/profile_for/owns_board; MTD_MAP_STOCK (mtd4 writable,
  kernel at write_order 4 so U-Boot lands first); from_afw accepts am335x-stock,
  permits exactly the u-boot bootloader member, still rejects any SPL member and
  a u-boot member on tier 2; check_uimage expects firmware type 5 for u-boot;
  the plan carries its board + preserved set; render is tier-aware.
- restore() takes the preserved set per profile; SPL copies (mtd0-3) are never a
  restore target on any tier; mtd4 is restorable on tier 3.
- alkane-cli: route am335x-stock to the module (plan/preflight/install); restore
  is profile-driven and adds --held-uboot (mtd4) for the from-stock set.
- alkane-artifacts: board_profile knows am335x-stock (arm, include).
- tests: tier-3 from_afw acceptance (4 targets, U-Boot before kernel, mtd4 not
  preserved), wrong-U-Boot-type and SPL-write-target rejection, and a tier-3
  restore test (mtd4 allowed, SPL refused). Full flash suite 41 green; tier-2 and
  cv1835 unchanged. The real bundle parses and verifies through the CLI.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qHxYpv7yf7Ah57g4rQ
2026-11-05 21:51:29 -06:00
noah 4d1adeb05e Install AM335x mtd7/mtd8 over SSH with held backups 2026-11-04 17:03:14 -06:00
noahandDeepSeek Harness 628c0630a5 Install .afw OS bundles on CV1835 over the network
Parse and verify the fixed-order .afw container, add the CV1835 board
module and an SSH transport with the stock update-daemon root stage, a
read-only preflight, a held p1 backup, whole-partition read-back, live
verification and network restore. Add the headless afw CLI and offline
fixtures for good, tampered, wrong-board, truncated, traversal and
oversize bundles.

Co-Authored-By: DeepSeek Harness <noreply@deepseek.com>
2026-11-04 14:31:35 -06:00
noah 75b7424a0d Merge pull request 'Avoid duplicate Toolkit feature branch CI' (#14) from ci/drop-duplicate-toolkit-feature-verify into next
next-build / candidate (push) Successful in 11m8s
2026-10-21 06:58:54 -06:00
noah 8d4fe502be Avoid duplicate Toolkit feature branch CI 2026-10-21 06:57:38 -06:00
noah 038c1b1c2b Merge pull request 'Add fast next pull request source gate' (#13) from ci/next-pr-source-check into next 2026-10-21 06:55:56 -06:00
noah 20d7f49c9d Scope Toolkit source checks to changed Rust 2026-10-21 06:54:48 -06:00
noah 74cee50d35 Add fast next pull request source gate 2026-10-21 06:51:32 -06:00
noah 32a75c92ef Merge pull request 'Route toolkit benchmark publication to verifier' (#9) from ci/isolate-fast-runner-next into next 2026-10-21 06:49:08 -06:00
noah f4d9c12bb6 Route toolkit benchmark publication to verifier 2026-10-20 18:45:04 -06:00
noah b610ce3d7f Validate SDK archive contents in Rust before install 2026-10-17 11:13:17 -06:00
noah 1a5dcd17a9 Verify SDK release archives from checksum sidecar 2026-10-17 10:11:15 -06:00
noah 3b1b1fa63e Document running build verification and lock CLI dependency 2026-10-17 10:08:34 -06:00
noah 7880b14e47 Expose running build verification in toolkit CLI 2026-10-17 10:03:34 -06:00
noah 5bbf5b71b7 Verify running board build marker against CI artifact 2026-10-17 10:01:04 -06:00
noah cfec9606a4 Require observed MTD geometry before resolving flash target 2026-10-17 09:02:13 -06:00
noah e8d7cdc77a Parse MTD layouts before board flash planning 2026-10-17 08:02:02 -06:00
noah 8ba585679a Add bounded read-only SSH board probes 2026-10-17 07:02:01 -06:00
noah ea102130ac docs: shorten Toolkit entry guide 2026-10-17 01:42:10 -06:00
noah e656402ec8 Publish Toolkit benchmarks on the standing Alkane runner 2026-10-17 01:21:27 -06:00
noah 80f3c22582 Validate public benchmark page before upload 2026-10-16 08:47:42 -06:00
noah a79ac3e09e Publish Toolkit benchmarks to public Pages site 2026-10-16 07:20:03 -06:00
noah 6580005e77 Bound queued Toolkit CI attempts per branch 2026-10-16 07:08:58 -06:00
noah 2734c8e356 Average benchmark improvements equally in Toolkit badge 2026-10-16 06:02:55 -06:00
noah 0c2897ce37 Require complete Toolkit benchmarks before release 2026-10-16 05:12:21 -06:00
noah fbc903fa6a Benchmark health diagnostics on representative miners 2026-10-15 20:19:36 -06:00
noah fe9617ab56 Guard UTF-8 naming and repair headless screenshots 2026-10-15 20:10:42 -06:00
noah 1e9e4f16b5 Stage verified flash images before device writes 2026-10-15 19:10:45 -06:00
noah 6a6a5e7ded Grade Toolkit code quality from static checks 2026-10-15 19:04:10 -06:00
noah e20b6890d3 Simplify Toolkit docs and update installer status 2026-10-15 14:37:27 -06:00
noah 17bee91248 Clean candidate build after prerelease decision 2026-10-15 12:43:24 -06:00
noah 63d0de8ae3 Clean generated Toolkit builds after CI and local GUI builds 2026-10-15 11:52:21 -06:00
noah 9a8efc807a Parse Rust test harness benchmark output 2026-10-15 04:06:52 -06:00
noah 9879a0eb25 Compare toolkit benchmarks on matching CPU classes 2026-10-15 03:37:30 -06:00
noah 03c19ef7c6 Derive toolkit quality grade from measured coverage 2026-10-15 03:34:41 -06:00
noah 2540801140 Revalidate artifacts and guard complete flash streams 2026-10-14 20:54:42 -06:00
noah dd28fa233c Use Gitea-compatible pinned artifact upload 2026-10-14 20:51:35 -06:00
noah e5ca519df0 Publish measured toolkit badges from main CI 2026-10-14 20:45:03 -06:00
noah 06c8e01eb5 Guard verified artifact writes with recovery checks 2026-10-14 20:40:35 -06:00
noah 990439985d Verify toolkit firmware artifacts before install 2026-10-14 20:31:26 -06:00
noah 54136b71ef Record private toolkit benchmark history 2026-10-14 20:21:38 -06:00
noah 5d18304f0f Standardize toolkit CI badges and scoped release auth 2026-10-14 20:06:48 -06:00
noah 8bbf844bb6 Merge branch 'tooling-standard' into next 2026-10-13 12:10:34 -06:00
noah 97607a0a91 Point next CI badge at next attempts 2026-10-13 11:54:38 -06:00
39 changed files with 13411 additions and 40 deletions
+36
View File
@@ -0,0 +1,36 @@
name: public-benchmark-pages
on:
schedule:
- cron: '*/15 * * * *'
workflow_dispatch:
concurrency:
group: alkane-toolkit-public-benchmark-pages
cancel-in-progress: false
jobs:
publish:
runs-on: alkane-verify
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
permissions:
contents: read
steps:
- uses: actions/checkout@v4
- name: Install SSH client
run: |
apt-get update -qq
apt-get install -y -qq --no-install-recommends openssh-client
- name: Render measured benchmark history
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
run: python3 ci/bench_history.py render
- name: Publish public benchmark page
env:
GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
BENCH_PAGES_DEPLOY_KEY: ${{ secrets.BENCH_PAGES_DEPLOY_KEY }}
run: python3 ci/publish-bench-pages.py toolkit
- name: Clean generated page
if: always()
run: python3 ci/cleanup-generated.py
+2
View File
@@ -22,6 +22,7 @@ jobs:
CARGO_TARGET_DIR: target
CARGO_BUILD_JOBS: 2
WX_WINDOWS_PREFIX: /root/.cache/wx-3.3.3-mingw
ALKANE_EMBEDDED_TOKEN: ${{ secrets.ALKANE_EMBEDDED_TOKEN }}
steps:
- uses: actions/checkout@v4
with:
@@ -94,6 +95,7 @@ jobs:
CARGO_BUILD_JOBS: 2
WX_PREFIX: /root/.cache/wx-3.3.3-linux
WX_RS_WXCONFIG: /root/.cache/wx-3.3.3-linux/bin/wx-config
ALKANE_EMBEDDED_TOKEN: ${{ secrets.ALKANE_EMBEDDED_TOKEN }}
steps:
- uses: actions/checkout@v4
with:
+6
View File
@@ -28,6 +28,9 @@ jobs:
CARGO_TARGET_DIR: target
CARGO_BUILD_JOBS: 2
WX_WINDOWS_PREFIX: /root/.cache/wx-3.3.3-mingw
# Read-only token baked into the GUI so the release picker can list the
# private alkane-os releases with no user setup (option_env!).
ALKANE_EMBEDDED_TOKEN: ${{ secrets.ALKANE_EMBEDDED_TOKEN }}
steps:
- name: Checkout (full history for tags)
uses: actions/checkout@v4
@@ -136,6 +139,9 @@ jobs:
# Set once for the whole job so build/clippy/test/bench steps don't each
# re-export it (round 18 #12).
WX_RS_WXCONFIG: /root/.cache/wx-3.3.3-linux/bin/wx-config
# Read-only token baked into the GUI so the release picker can list the
# private alkane-os releases with no user setup (option_env!).
ALKANE_EMBEDDED_TOKEN: ${{ secrets.ALKANE_EMBEDDED_TOKEN }}
steps:
- name: Checkout (full history for tags)
uses: actions/checkout@v4
Generated
+7
View File
@@ -40,6 +40,8 @@ name = "alkane-artifacts"
version = "0.1.0"
dependencies = [
"alkane-core",
"serde",
"serde_json",
"sha2",
"thiserror",
]
@@ -50,6 +52,8 @@ version = "0.1.0"
dependencies = [
"alkane-artifacts",
"alkane-core",
"alkane-flash",
"serde_json",
]
[[package]]
@@ -74,6 +78,7 @@ version = "0.1.0"
dependencies = [
"alkane-artifacts",
"alkane-core",
"serde_json",
"sha2",
"tempfile",
"thiserror",
@@ -84,8 +89,10 @@ name = "alkane-gui"
version = "0.1.0"
dependencies = [
"aes",
"alkane-artifacts",
"alkane-core",
"alkane-discovery",
"alkane-flash",
"asic-rs",
"base64 0.21.7",
"ecb",
+1
View File
@@ -19,6 +19,7 @@ license = "MIT"
thiserror = "2"
serde = { version = "1", features = ["derive"] }
sha2 = "0.10"
serde_json = "1"
# Release binary: small, self-contained, and fast enough for a fleet GUI whose
# hot path is network I/O, not CPU (round 18 #12). opt-level "s" + fat LTO +
+44
View File
@@ -47,6 +47,50 @@ and Intel, macOS 11 or later; see [docs/macos.md](docs/macos.md).
Discovery is read-only. Control and restore actions change miners. Check the
selected devices before applying them.
## Headless .afw install (CV1835 and AM335x)
`alkane-cli` is the headless engine; the GUI uses the same engine. A verified
`.afw` is a full OS bundle for exactly one board. The CV1835 installer writes
only `/dev/mmcblk0p1` over SSH, holds the current p1 first, reads the whole
partition back, and reboots only after the read-back matches.
The AM335x installer writes mtd8 (type-3 ramdisk), mtd6 (dtb) and mtd7
(legacy kernel uImage) with `flash_erase` + `nandwrite`. It never touches
mtd0-5 (SPL/U-Boot/bootenv), holds a backup of each target before writing it,
and reads every target back before reboot. Its `verify-live` checks SSH
(kernel string), the HTTP marker on port 80, the API on port 4028, and the
eth0 DHCP lease.
```sh
alkane-cli afw verify BUNDLE.afw --allow-unsigned
alkane-cli afw plan BUNDLE.afw --host 10.255.1.167
alkane-cli afw preflight BUNDLE.afw --host 10.255.1.167
alkane-cli afw install BUNDLE.afw --host 10.255.1.167 --dry-run
alkane-cli afw install BUNDLE.afw --host 10.255.1.167 --confirm FLASH
alkane-cli afw verify-live BUNDLE.afw --host 10.255.1.167
alkane-cli afw restore --host 10.255.1.167 --held-backup p1.img --confirm FLASH
```
For AM335x the same subcommands infer the board from the bundle; restore names
the three held copies explicitly:
```sh
alkane-cli afw plan BUNDLE.afw --host 10.255.1.64
alkane-cli afw preflight BUNDLE.afw --host 10.255.1.64
alkane-cli afw install BUNDLE.afw --host 10.255.1.64 --dry-run
alkane-cli afw install BUNDLE.afw --host 10.255.1.64 --confirm FLASH
alkane-cli afw verify-live BUNDLE.afw --host 10.255.1.64 --timeout 300
alkane-cli afw restore --board am335x --host 10.255.1.64 \
--held-backup mtd8.img --held-kernel mtd7.img --held-dtb mtd6.img --confirm FLASH
```
On stock Bitmain CV1835 the SSH login is the unprivileged `miner` account; the
toolkit obtains root through the stock update-daemon loopback channel, not a
serial console. Credentials come only from `ALKANE_BOARD_PASSWORD` or
`ALKANE_BOARD_PASSWORD_FILE`, or from `--password-file` / `--identity-file`.
No credential value is printed. `--allow-unsigned` is bench-only; site use
needs an Ed25519-signed bundle.
## Development
```sh
+121
View File
@@ -0,0 +1,121 @@
#!/usr/bin/env python3
# SPDX-License-Identifier: MIT
"""Publish a measured benchmark page to the public, data-only Pages repo."""
import argparse
import json
import os
from pathlib import Path
import shlex
import subprocess
import tempfile
from urllib.request import Request, urlopen
PAGES_REPO = "ssh://git@gitea.bluefla.re:2222/blueflare/alkane-benchmarks.git"
GUARD_REPO = "https://gitea.bluefla.re/blueflare/alkane-benchmarks.git"
GUARD_COMMIT = "ea160545c49bc419a245692deda8dd7db7a611eb"
PAGES_HOST = "gitea.bluefla.re"
PAGES_HOST_FINGERPRINT = "SHA256:lqB5cmC9E5HNeg/lkzdOwQ++I8A70Wx7lnNs6liN24g"
PAGES_HOST_KEY = "[gitea.bluefla.re]:2222 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIO1II6NkmRW+QAd+Wj+7qbNrA8Oo+/N/WRog4hELskn/"
def run(*args: str, env: dict[str, str] | None = None,
cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
return subprocess.run(args, env=env, cwd=cwd, text=True,
capture_output=True, check=True)
def current_main_sha() -> str:
api = os.environ["GITHUB_API_URL"].rstrip("/")
repo = os.environ["GITHUB_REPOSITORY"]
token = os.environ["GITEA_TOKEN"]
request = Request(f"{api}/repos/{repo}/branches/main",
headers={"Authorization": f"token {token}"})
with urlopen(request, timeout=20) as response:
branch = json.load(response)
return branch["commit"]["id"]
def publish(site: str) -> None:
if os.environ.get("GITHUB_REF") != "refs/heads/main":
raise ValueError("benchmark Pages publication requires main")
sha = os.environ["GITHUB_SHA"]
if current_main_sha() != sha:
print("Skipping benchmark page from a superseded main commit")
return
page = Path("bench-site/index.html").read_bytes()
if not page.startswith(b"<!doctype html>") or len(page) > 1_048_576:
raise ValueError("invalid benchmark page")
with tempfile.TemporaryDirectory(prefix="alkane-pages-") as directory:
temporary = Path(directory)
guard_checkout = temporary / "guard"
run("git", "clone", "--quiet", "--single-branch", "--branch", "next",
GUARD_REPO, str(guard_checkout))
guard_source = run("git", "show", f"{GUARD_COMMIT}:ci/validate_site.py",
cwd=guard_checkout).stdout
guard_script = temporary / "validate_site.py"
guard_script.write_text(guard_source)
run("python3", str(guard_script), "--page", site,
str(Path("bench-site/index.html").resolve()))
key = os.environ["BENCH_PAGES_DEPLOY_KEY"]
if not key.startswith("-----BEGIN OPENSSH PRIVATE KEY-----"):
raise ValueError("missing benchmark Pages deploy key")
key_path = temporary / "deploy_key"
key_path.write_text(key.rstrip("\n") + "\n")
key_path.chmod(0o600)
known_hosts = temporary / "known_hosts"
known_hosts.write_text(PAGES_HOST_KEY + "\n")
fingerprint = run("ssh-keygen", "-lf", str(known_hosts)).stdout.split()[1]
if fingerprint != PAGES_HOST_FINGERPRINT:
raise ValueError("benchmark Pages SSH host key changed")
git_env = os.environ.copy()
ssh_command = (f"ssh -i {shlex.quote(str(key_path))} -o IdentitiesOnly=yes "
f"-o UserKnownHostsFile={shlex.quote(str(known_hosts))} "
"-o StrictHostKeyChecking=yes -o ConnectTimeout=10")
git_env["GIT_SSH_COMMAND"] = ssh_command
git_env["GIT_TERMINAL_PROMPT"] = "0"
checkout = temporary / "site"
run("git", "clone", "--quiet", "--single-branch", "--branch", "gh-pages",
PAGES_REPO, str(checkout), env=git_env)
run("git", "config", "user.name", "Alkane CI", cwd=checkout)
run("git", "config", "user.email", "ci@bluefla.re", cwd=checkout)
for attempt in range(3):
if current_main_sha() != sha:
print("Skipping benchmark page from a superseded main commit")
return
run("git", "fetch", "--quiet", "origin", "gh-pages", env=git_env,
cwd=checkout)
run("git", "checkout", "-q", "-B", "bench-publish", "origin/gh-pages",
cwd=checkout)
destination = checkout / site / "index.html"
destination.parent.mkdir(exist_ok=True)
destination.write_bytes(page)
run("git", "add", f"{site}/index.html", cwd=checkout)
changed = subprocess.run(("git", "diff", "--cached", "--quiet"),
cwd=checkout, check=False)
if changed.returncode == 0:
print(f"{site} benchmark page is already current")
return
if changed.returncode != 1:
raise RuntimeError("cannot compare benchmark page")
run("git", "commit", "-q", "-m",
f"Update {site} benchmarks for {sha[:10]} [skip ci]", cwd=checkout)
pushed = subprocess.run(("git", "push", "--quiet", "origin",
"HEAD:gh-pages"), env=git_env, cwd=checkout,
text=True, capture_output=True, check=False)
if pushed.returncode == 0:
print(f"Published {site} benchmark page for {sha[:10]}")
return
if attempt == 2:
raise RuntimeError(f"benchmark Pages push failed: {pushed.stderr.strip()}")
raise RuntimeError("benchmark Pages publication did not complete")
def main() -> None:
parser = argparse.ArgumentParser()
parser.add_argument("site", choices=("sdk", "os", "toolkit"))
publish(parser.parse_args().site)
if __name__ == "__main__":
main()
+9 -4
View File
@@ -136,12 +136,17 @@ def main() -> None:
["README.md", "ci/pr-surface.py"]):
assert not pr_surface.documentation_only(paths), paths
assert pr_surface.headless_packages(["crates/alkane-cli/src/main.rs"]) == ["alkane-cli"]
assert pr_surface.headless_packages(["crates/alkane-artifacts/src/lib.rs"]) == [
"alkane-artifacts", "alkane-cli", "alkane-flash",
]
# alkane-gui depends on alkane-flash and alkane-artifacts (right-click
# install/uninstall and the release picker), so a change in either reaches
# the GUI graph and needs the full build: not a headless-only change.
assert pr_surface.headless_packages(["crates/alkane-artifacts/src/lib.rs"]) == []
assert pr_surface.headless_packages(["crates/alkane-flash/src/lib.rs"]) == []
assert pr_surface.headless_packages([
"crates/alkane-access/src/lib.rs", "crates/alkane-flash/tests/update.rs",
]) == ["alkane-access", "alkane-flash"]
]) == []
assert pr_surface.headless_packages([
"crates/alkane-access/src/lib.rs", "crates/alkane-cli/src/main.rs",
]) == ["alkane-access", "alkane-cli"]
for paths in ([], ["crates/alkane-core/src/lib.rs"],
["crates/alkane-discovery/src/lib.rs"],
["crates/alkane-gui/src/main.rs"],
+2
View File
@@ -6,5 +6,7 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
serde.workspace = true
serde_json.workspace = true
sha2.workspace = true
thiserror.workspace = true
File diff suppressed because it is too large Load Diff
+404
View File
@@ -0,0 +1,404 @@
// SPDX-License-Identifier: MIT
//! Fetch the latest alkane-os `.afw` release from a Gitea repository.
//!
//! GitHub is retired for this project; releases live on the self-hosted Gitea.
//! This resolves `releases/latest`, picks the `.afw` asset for a board, and
//! downloads it so the normal verify -> plan -> preflight -> install flow runs on
//! it exactly as it would on a local file. TLS is required, so this shells out to
//! `curl` (as the GUI already does) rather than the plaintext TCP path used for
//! liveness checks.
//!
//! A private repo needs a token; it is read from the environment at run time
//! (`ALKANE_RELEASE_TOKEN`, else `GITEA_TOKEN`) and passed to curl through a
//! 0600 config file, never on the command line.
//!
//! As a convenience for the GUI, a read-only token can be baked into the binary
//! at build time by compiling with `ALKANE_EMBEDDED_TOKEN=<token>` set (see
//! `EMBEDDED_TOKEN`). The source tree carries no secret - the value lives only in
//! a binary built with that variable set - and the environment variables above
//! always take precedence, so a user can override it. When no such token is baked
//! in and none is in the environment, the token is simply absent (fine for public
//! repos; a private repo then returns 401/404).
use std::fs;
use std::path::{Path, PathBuf};
use std::process::Command;
use serde_json::Value;
use thiserror::Error;
/// A read-only Gitea token baked in at build time when the crate is compiled
/// with `ALKANE_EMBEDDED_TOKEN` set. `None` in an ordinary build (no secret in
/// the source tree). The environment variables win over this, so it is only a
/// fallback for a distributed binary (the GUI) that ships without asking the user
/// to configure a token. Scope it read-only on the server side; anyone with the
/// binary can extract it.
const EMBEDDED_TOKEN: Option<&str> = option_env!("ALKANE_EMBEDDED_TOKEN");
#[derive(Debug, Error)]
pub enum FetchError {
#[error("curl failed: {0}")]
Curl(String),
#[error("release metadata did not parse: {0}")]
Parse(String),
#[error("no .afw asset for board {0} in the latest release")]
NoAsset(String),
#[error("io: {0}")]
Io(String),
}
/// Where releases come from. Defaults to the alkane-os repo on the self-hosted
/// Gitea; the base URL and token are read from the environment.
pub struct ReleaseSource {
pub base_url: String,
pub owner: String,
pub repo: String,
pub token: Option<String>,
}
impl ReleaseSource {
/// The alkane-os release source, honoring `ALKANE_RELEASE_BASE` and a token
/// from `ALKANE_RELEASE_TOKEN` or `GITEA_TOKEN`.
pub fn alkane_os() -> Self {
let base_url = std::env::var("ALKANE_RELEASE_BASE")
.ok()
.filter(|s| !s.is_empty())
.unwrap_or_else(|| "https://gitea.bluefla.re".to_string());
let token = std::env::var("ALKANE_RELEASE_TOKEN")
.ok()
.or_else(|| std::env::var("GITEA_TOKEN").ok())
.filter(|t| !t.is_empty())
.or_else(|| EMBEDDED_TOKEN.map(str::to_string).filter(|t| !t.is_empty()));
Self {
base_url,
owner: "blueflare".to_string(),
repo: "alkane-os".to_string(),
token,
}
}
/// The releases list (newest first). Unlike `releases/latest`, this includes
/// pre-releases, so an early/bench channel is still found by `--latest`.
fn api_list(&self) -> String {
format!(
"{}/api/v1/repos/{}/{}/releases?limit=50",
self.base_url.trim_end_matches('/'),
self.owner,
self.repo
)
}
}
/// Find the first `.afw` asset for `board` across a newest-first list of
/// releases. Returns (name, url).
fn pick_asset(releases: &Value, board: &str) -> Option<(String, String)> {
let needle = format!("-{board}-");
for release in releases.as_array()? {
let Some(assets) = release.get("assets").and_then(Value::as_array) else {
continue;
};
for asset in assets {
let name = asset.get("name").and_then(Value::as_str).unwrap_or("");
if name.ends_with(".afw") && name.contains(&needle) {
if let Some(url) = asset.get("browser_download_url").and_then(Value::as_str) {
return Some((name.to_string(), url.to_string()));
}
}
}
}
None
}
/// A temp curl `--config` file carrying the auth header, removed on drop so the
/// token never lands in a process argument or a lingering file.
struct TokenConfig {
path: Option<PathBuf>,
}
impl TokenConfig {
fn new(token: &Option<String>) -> Result<Self, FetchError> {
let Some(token) = token else {
return Ok(Self { path: None });
};
let path = std::env::temp_dir().join(format!("alkane-fetch-{}.cfg", std::process::id()));
write_private(
&path,
&format!("header = \"Authorization: token {token}\"\n"),
)?;
Ok(Self { path: Some(path) })
}
fn apply(&self, cmd: &mut Command) {
if let Some(path) = &self.path {
cmd.arg("--config").arg(path);
}
}
}
impl Drop for TokenConfig {
fn drop(&mut self) {
if let Some(path) = &self.path {
let _ = fs::remove_file(path);
}
}
}
#[cfg(unix)]
fn write_private(path: &Path, contents: &str) -> Result<(), FetchError> {
use std::io::Write;
use std::os::unix::fs::OpenOptionsExt;
let mut file = fs::OpenOptions::new()
.write(true)
.create(true)
.truncate(true)
.mode(0o600)
.open(path)
.map_err(|e| FetchError::Io(e.to_string()))?;
file.write_all(contents.as_bytes())
.map_err(|e| FetchError::Io(e.to_string()))
}
#[cfg(not(unix))]
fn write_private(path: &Path, contents: &str) -> Result<(), FetchError> {
fs::write(path, contents).map_err(|e| FetchError::Io(e.to_string()))
}
fn curl_bytes(src: &ReleaseSource, url: &str) -> Result<Vec<u8>, FetchError> {
let config = TokenConfig::new(&src.token)?;
let mut cmd = Command::new("curl");
cmd.arg("-fsSL").arg("--max-time").arg("120");
config.apply(&mut cmd);
cmd.arg(url);
let out = cmd.output().map_err(|e| FetchError::Curl(e.to_string()))?;
if !out.status.success() {
return Err(FetchError::Curl(format!(
"{} ({})",
String::from_utf8_lossy(&out.stderr).trim(),
out.status
)));
}
Ok(out.stdout)
}
fn curl_download(src: &ReleaseSource, url: &str, dest: &Path) -> Result<(), FetchError> {
let config = TokenConfig::new(&src.token)?;
let mut cmd = Command::new("curl");
cmd.arg("-fsSL")
.arg("--max-time")
.arg("600")
.arg("-o")
.arg(dest);
config.apply(&mut cmd);
cmd.arg(url);
let out = cmd.output().map_err(|e| FetchError::Curl(e.to_string()))?;
if !out.status.success() {
return Err(FetchError::Curl(format!(
"{} ({})",
String::from_utf8_lossy(&out.stderr).trim(),
out.status
)));
}
Ok(())
}
/// Resolve the latest release's `.afw` asset for `board`: returns (name, url).
/// Scans the newest-first releases list (so a pre-release counts as latest).
pub fn latest_afw_asset(src: &ReleaseSource, board: &str) -> Result<(String, String), FetchError> {
let body = curl_bytes(src, &src.api_list())?;
let releases: Value =
serde_json::from_slice(&body).map_err(|e| FetchError::Parse(e.to_string()))?;
pick_asset(&releases, board).ok_or_else(|| FetchError::NoAsset(board.to_string()))
}
/// Download the latest `.afw` for `board` into `dest_dir`; returns its path.
pub fn fetch_latest_afw(
src: &ReleaseSource,
board: &str,
dest_dir: &Path,
) -> Result<PathBuf, FetchError> {
let (name, url) = latest_afw_asset(src, board)?;
fs::create_dir_all(dest_dir).map_err(|e| FetchError::Io(e.to_string()))?;
let dest = dest_dir.join(&name);
curl_download(src, &url, &dest)?;
Ok(dest)
}
/// One `.afw` asset in a release.
#[derive(Debug, Clone)]
pub struct AfwAsset {
pub name: String,
pub url: String,
}
/// A release as listed for the GUI's release picker: its tag/name, whether it is
/// a pre-release or draft, when it was published, and the `.afw` assets it holds.
#[derive(Debug, Clone)]
pub struct ReleaseInfo {
pub tag: String,
pub name: String,
pub prerelease: bool,
pub draft: bool,
pub published_at: String,
pub afw_assets: Vec<AfwAsset>,
}
impl ReleaseInfo {
/// The `.afw` asset for `board` in this release, if any (matched by the
/// `-<board>-` segment of the filename, as `pick_asset` does).
pub fn asset_for_board(&self, board: &str) -> Option<&AfwAsset> {
let needle = format!("-{board}-");
self.afw_assets.iter().find(|a| a.name.contains(&needle))
}
}
/// Parse a Gitea releases array (newest first) into `ReleaseInfo`s, keeping only
/// the `.afw` assets of each. Drafts are included so the caller can decide.
fn parse_releases(releases: &Value) -> Vec<ReleaseInfo> {
let mut out = Vec::new();
let Some(arr) = releases.as_array() else {
return out;
};
for release in arr {
let tag = release
.get("tag_name")
.and_then(Value::as_str)
.unwrap_or("")
.to_string();
let name = release
.get("name")
.and_then(Value::as_str)
.unwrap_or("")
.to_string();
let prerelease = release
.get("prerelease")
.and_then(Value::as_bool)
.unwrap_or(false);
let draft = release
.get("draft")
.and_then(Value::as_bool)
.unwrap_or(false);
let published_at = release
.get("published_at")
.or_else(|| release.get("created_at"))
.and_then(Value::as_str)
.unwrap_or("")
.to_string();
let mut afw_assets = Vec::new();
if let Some(assets) = release.get("assets").and_then(Value::as_array) {
for asset in assets {
let aname = asset.get("name").and_then(Value::as_str).unwrap_or("");
if aname.ends_with(".afw") {
if let Some(url) = asset.get("browser_download_url").and_then(Value::as_str) {
afw_assets.push(AfwAsset {
name: aname.to_string(),
url: url.to_string(),
});
}
}
}
}
out.push(ReleaseInfo {
tag,
name,
prerelease,
draft,
published_at,
afw_assets,
});
}
out
}
/// List the releases (newest first) of the source repo, each with its `.afw`
/// assets. Used by the GUI to scan alkane-os releases and pick one to install.
pub fn list_releases(src: &ReleaseSource) -> Result<Vec<ReleaseInfo>, FetchError> {
let body = curl_bytes(src, &src.api_list())?;
let releases: Value =
serde_json::from_slice(&body).map_err(|e| FetchError::Parse(e.to_string()))?;
Ok(parse_releases(&releases))
}
/// Download a specific release asset (by its `browser_download_url`) into
/// `dest_dir`, saving it under `name`; returns the written path.
pub fn fetch_afw_url(
src: &ReleaseSource,
name: &str,
url: &str,
dest_dir: &Path,
) -> Result<PathBuf, FetchError> {
fs::create_dir_all(dest_dir).map_err(|e| FetchError::Io(e.to_string()))?;
let dest = dest_dir.join(name);
curl_download(src, url, &dest)?;
Ok(dest)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn source_defaults_to_alkane_os_on_gitea() {
std::env::remove_var("ALKANE_RELEASE_BASE");
let src = ReleaseSource::alkane_os();
assert_eq!(src.owner, "blueflare");
assert_eq!(src.repo, "alkane-os");
assert!(src
.api_list()
.contains("/api/v1/repos/blueflare/alkane-os/releases"));
assert!(src.api_list().starts_with("https://gitea.bluefla.re"));
}
#[test]
fn pick_asset_takes_the_newest_matching_afw() {
// Newest-first list of releases; the board's .afw in the first release wins.
let releases = serde_json::json!([
{"tag_name": "v0.1.0-bench1", "assets": [
{"name": "SHA256SUMS", "browser_download_url": "u0"},
{"name": "alkane-os-0.1.0-am335x-arm.afw", "browser_download_url": "u1"},
{"name": "alkane-os-0.1.0-zynq-7010-armv7.afw", "browser_download_url": "u2"},
]},
{"tag_name": "v0.0.9", "assets": [
{"name": "alkane-os-0.0.9-zynq-7010-armv7.afw", "browser_download_url": "old"},
]},
]);
assert_eq!(
pick_asset(&releases, "zynq-7010"),
Some(("alkane-os-0.1.0-zynq-7010-armv7.afw".into(), "u2".into()))
);
assert_eq!(pick_asset(&releases, "cv1835"), None);
}
#[test]
fn list_parses_releases_and_filters_afw_assets() {
let releases = serde_json::json!([
{"tag_name": "v0.2.0-bench1", "name": "bench", "prerelease": true, "draft": false,
"published_at": "2026-11-11T10:00:00Z", "assets": [
{"name": "SHA256SUMS", "browser_download_url": "s"},
{"name": "alkane-os-0.2.0-zynq-7010-armv7.afw", "browser_download_url": "z"},
]},
{"tag_name": "v0.1.0", "name": "", "prerelease": false, "draft": false,
"published_at": "2026-10-01T00:00:00Z", "assets": [
{"name": "alkane-os-0.1.0-am335x-arm.afw", "browser_download_url": "a"},
]},
]);
let parsed = parse_releases(&releases);
assert_eq!(parsed.len(), 2);
// Newest first; only .afw assets kept; SHA256SUMS dropped.
assert_eq!(parsed[0].tag, "v0.2.0-bench1");
assert!(parsed[0].prerelease);
assert_eq!(parsed[0].afw_assets.len(), 1);
// The board filter matches the -<board>- segment.
assert_eq!(
parsed[0]
.asset_for_board("zynq-7010")
.map(|a| a.url.as_str()),
Some("z")
);
assert!(parsed[0].asset_for_board("am335x").is_none());
assert_eq!(
parsed[1].asset_for_board("am335x").map(|a| a.name.as_str()),
Some("alkane-os-0.1.0-am335x-arm.afw")
);
assert!(parsed[1].asset_for_board("zynq-7010").is_none());
}
}
+3
View File
@@ -1,6 +1,9 @@
// SPDX-License-Identifier: MIT
//! Verify local firmware artifacts before an install path consumes them.
pub mod afw;
pub mod fetch;
use sha2::{Digest, Sha256};
use std::collections::HashSet;
use std::fs::File;
+2
View File
@@ -7,3 +7,5 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-artifacts = { path = "../alkane-artifacts" }
alkane-flash = { path = "../alkane-flash" }
serde_json.workspace = true
File diff suppressed because it is too large Load Diff
+1
View File
@@ -7,6 +7,7 @@ license.workspace = true
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-artifacts = { path = "../alkane-artifacts" }
serde_json.workspace = true
sha2.workspace = true
thiserror.workspace = true
tempfile = "3"
+880
View File
@@ -0,0 +1,880 @@
// SPDX-License-Identifier: MIT
//! Amlogic A113D / AXG (Antminer S21 Pro-class) board module: tier-2 network
//! UPDATE of a board already running alkane. Our OS is staged as FILES in the
//! nvdata UBI volume: alkane/{vmlinux.bin, devicetree.dtb, uramdisk.image.gz}.
//! (The legacy vendor path name "anthillos" from AnthillOS is no longer used;
//! our own bootcmd loads from alkane/.)
//!
//! The running alkane image exposes ONLY the nvdata region as an MTD (the board
//! DT declares a single `nvdata` fixed-partition; the FIP bootloader and the
//! stock boot/recovery/misc/config regions are deliberately undeclared, so they
//! are never registered as MTD devices and cannot be written from Linux). This
//! module attaches UBI to that one nvdata MTD, mounts the UBIFS volume, and
//! overwrites the three files under alkane/. It performs no raw mtd0-5 write and
//! never changes the bootloader: the brick-sensitive regions are physically
//! unreachable.
//!
//! The first from-stock install (past the signed bootloader) is handled
//! elsewhere and is NOT this module. This is the repeatable alkane-to-alkane
//! update.
use crate::md5::md5_hex;
use crate::preflight::{classify, parse_digest};
use crate::transport::{Remote, RemoteError};
use alkane_artifacts::afw::{AfwImage, BootloaderPolicy, VerifiedAfw};
use std::fs;
use std::io::Write;
use std::path::PathBuf;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
use thiserror::Error;
pub const BOARD: &str = "a113d";
pub const ARCH: &str = "arm64";
/// The UBI volume subdirectory our boot chain reads our OS files from. This is
/// alkane's own name; the board's `ourbootcmd` loads from here.
pub const ALKANE_DIR: &str = "alkane";
/// nvdata UBI usable size; the three files together must fit (0xB900000).
pub const NVDATA_USABLE: u64 = 0xB900000;
/// The only MTD partition our DT exposes. mtd0-5 (FIP + stock boot) are not
/// declared in the DT at all, so they are not MTD devices on a running image.
pub const NVDATA_LABEL: &str = "nvdata";
/// Authoritative file targets: (image, on-board basename, ceiling, format).
/// Written rootfs -> dtb -> kernel so a mid-write interruption never leaves a
/// new rootfs beside an old kernel (the kernel file lands last).
const TARGETS: [(&str, &str, u64, &str); 3] = [
("rootfs", "uramdisk.image.gz", 0x6000000, "uimage"),
("dtb", "devicetree.dtb", 0x100000, "fdt"),
("kernel", "vmlinux.bin", 0x4000000, "arm64-image"),
];
#[derive(Debug, Error)]
pub enum A113dPlanError {
#[error("bundle is for {0}, not a113d")]
WrongBoard(String),
#[error("bundle arch is {0}, a113d needs arm64")]
WrongArch(String),
#[error("a113d requires bootloader_policy preserve (the FIP is never written)")]
BootloaderPolicy,
#[error("a113d bundle carries a bootloader/spl/fip/tpl member: {0}")]
BootloaderMember(String),
#[error("manifest is not an OS payload")]
PayloadType,
#[error("manifest marker is empty")]
Marker,
#[error("a113d must install exactly kernel, dtb and rootfs")]
InstallCount,
#[error("a113d is missing the {0} image")]
MissingImage(String),
#[error("a113d {image} format is {actual}, expected {expected}")]
ImageFormat {
image: String,
actual: String,
expected: &'static str,
},
#[error("a113d {image} is {size} bytes, over the 0x{ceiling:x}-byte ceiling")]
ImageTooLarge {
image: String,
size: u64,
ceiling: u64,
},
#[error("a113d images total {total} bytes, over the nvdata UBI (0x{usable:x})")]
OverNvdata { total: u64, usable: u64 },
#[error("a113d {image} is not an arm64 Image")]
NotArm64 { image: String },
#[error("a113d {image} is not an FDT")]
NotFdt { image: String },
#[error("a113d {image} is not a legacy uImage")]
NotUimage { image: String },
#[error("a113d refuses: preserved partition {0} (mtd0-5) carries an image")]
PreservedCarriesImage(String),
#[error("a113d refuses an unsafe destination for {image}: {dest}")]
UnsafeDest { image: String, dest: String },
}
#[derive(Clone, Debug)]
pub struct A113dTarget {
pub image_name: String,
/// On-board basename inside the alkane directory (never a device path).
pub dest: String,
pub size: u64,
pub data: Vec<u8>,
pub expected_md5: String,
}
#[derive(Clone, Debug)]
pub struct A113dPlan {
pub targets: Vec<A113dTarget>,
pub marker: String,
pub kernel_version: String,
pub sdk_revision: String,
pub os_revision: String,
pub afw_sha256: String,
pub min_free_bytes: u64,
}
fn is_bootloaderish(image: &AfwImage) -> bool {
let lowered = format!("{} {} {}", image.name, image.file, image.role).to_lowercase();
image.role == "bootloader"
|| lowered.contains("spl")
|| lowered.contains("u-boot")
|| lowered.contains("uboot")
|| lowered.contains("fip")
|| lowered.contains("tpl")
}
/// A destination is safe only as a bare basename (no separators, no traversal,
/// not a device path). This keeps every write inside the alkane/ directory.
fn is_safe_dest(dest: &str) -> bool {
!dest.is_empty()
&& !dest.contains('/')
&& !dest.contains("..")
&& !dest.starts_with("/dev/")
&& dest == dest.trim()
}
impl A113dPlan {
pub fn from_afw(afw: &VerifiedAfw) -> Result<Self, A113dPlanError> {
let manifest = &afw.manifest;
if manifest.board != BOARD {
return Err(A113dPlanError::WrongBoard(manifest.board.clone()));
}
if manifest.arch != ARCH {
return Err(A113dPlanError::WrongArch(manifest.arch.clone()));
}
if manifest.payload_type != "os" {
return Err(A113dPlanError::PayloadType);
}
if manifest.bootloader_policy != BootloaderPolicy::Preserve {
return Err(A113dPlanError::BootloaderPolicy);
}
if manifest.marker.is_empty() {
return Err(A113dPlanError::Marker);
}
// FIP / bootloader members are never allowed - we reuse the board's.
for image in &manifest.images {
if is_bootloaderish(image) {
return Err(A113dPlanError::BootloaderMember(image.file.clone()));
}
}
// Defense in depth: only nvdata (mtd6) may carry an image; mtd0-5 preserved.
for partition in &manifest.partitions {
if partition.name != "nvdata" && partition.image.is_some() {
return Err(A113dPlanError::PreservedCarriesImage(
partition.name.clone(),
));
}
}
let installs: Vec<&AfwImage> = manifest.images.iter().filter(|i| i.install).collect();
if installs.len() != TARGETS.len() {
return Err(A113dPlanError::InstallCount);
}
let mut targets = Vec::with_capacity(TARGETS.len());
let mut total = 0u64;
for (image_name, dest, ceiling, expected_format) in TARGETS {
let image = manifest
.images
.iter()
.find(|i| i.name == image_name && i.install)
.ok_or_else(|| A113dPlanError::MissingImage(image_name.to_owned()))?;
if image.format != expected_format {
return Err(A113dPlanError::ImageFormat {
image: image_name.to_owned(),
actual: image.format.clone(),
expected: expected_format,
});
}
if image.size > ceiling {
return Err(A113dPlanError::ImageTooLarge {
image: image_name.to_owned(),
size: image.size,
ceiling,
});
}
if !is_safe_dest(dest) {
return Err(A113dPlanError::UnsafeDest {
image: image_name.to_owned(),
dest: dest.to_owned(),
});
}
let data = afw
.image(image_name)
.map(|(_, data)| data)
.ok_or_else(|| A113dPlanError::MissingImage(image_name.to_owned()))?;
// Each arm validates a different magic; keeping them as explicit
// arms (not match guards) reads more clearly than collapsing.
#[allow(clippy::collapsible_match)]
match expected_format {
"arm64-image" => {
if !(data.len() >= 0x3C && data[0x38..0x3C] == *b"ARMd") {
return Err(A113dPlanError::NotArm64 {
image: image_name.to_owned(),
});
}
}
"fdt" => {
if !(data.len() >= 4 && data[0..4] == [0xd0, 0x0d, 0xfe, 0xed]) {
return Err(A113dPlanError::NotFdt {
image: image_name.to_owned(),
});
}
}
"uimage" => {
if !(data.len() >= 4 && data[0..4] == [0x27, 0x05, 0x19, 0x56]) {
return Err(A113dPlanError::NotUimage {
image: image_name.to_owned(),
});
}
}
_ => {}
}
total += image.size;
targets.push(A113dTarget {
image_name: image_name.to_owned(),
dest: dest.to_owned(),
size: image.size,
expected_md5: md5_hex(data),
data: data.to_vec(),
});
}
if total > NVDATA_USABLE {
return Err(A113dPlanError::OverNvdata {
total,
usable: NVDATA_USABLE,
});
}
Ok(Self {
targets,
marker: manifest.marker.clone(),
kernel_version: manifest.kernel_version.clone(),
sdk_revision: manifest.sdk_revision.clone(),
os_revision: manifest.os_revision.clone(),
afw_sha256: afw.archive_sha256.clone(),
min_free_bytes: manifest
.preflight
.get("min_free_bytes")
.and_then(|v| v.as_u64())
.unwrap_or(16 * 1024 * 1024),
})
}
pub fn render(&self) -> String {
let mut out = format!("board {BOARD} arch {ARCH}\n");
out.push_str(
"tier 2 update: attach UBI to the nvdata MTD, mount it, and overwrite the OS files \
under alkane/; the FIP + stock boot/recovery/misc/config are not MTD devices at all, \
so no raw NAND write is possible\n",
);
out.push_str("image format kernel=arm64-image, dtb=fdt, rootfs=uimage\n");
for target in &self.targets {
out.push_str(&format!(
"write {} -> {ALKANE_DIR}/{} size {} B md5 {}\n",
target.image_name, target.dest, target.size, target.expected_md5
));
}
out.push_str(&format!(
"marker {} kernel {} sdk {} os {}",
self.marker,
self.kernel_version,
short(&self.sdk_revision),
short(&self.os_revision),
));
out
}
}
fn short(rev: &str) -> &str {
rev.get(..12).unwrap_or(rev)
}
#[derive(Debug, Error)]
pub enum A113dError {
#[error("preflight failed:\n{0}")]
Preflight(String),
#[error("--confirm FLASH is required to write")]
Confirm,
#[error("the running image exposes no '{0}' MTD; it needs a NAND-enabled a113d kernel")]
NoNvdataMtd(String),
#[error("could not attach UBI to the nvdata MTD / find its volume")]
UbiAttach,
#[error("could not mount the nvdata UBIFS volume")]
Mount,
#[error("refusing an unsafe destination: {0}")]
UnsafeDest(String),
#[error("{0} staged md5 differs from the verified bundle")]
StageMismatch(String),
#[error("{0} read-back md5 mismatch; do not reboot")]
Readback(String),
#[error(transparent)]
Remote(#[from] RemoteError),
#[error(transparent)]
Io(#[from] std::io::Error),
}
#[derive(Clone, Debug)]
pub struct A113dCheck {
pub name: String,
pub ok: bool,
pub detail: String,
}
#[derive(Clone, Debug)]
pub struct A113dPreflight {
pub host: String,
pub checks: Vec<A113dCheck>,
/// The nvdata MTD index (e.g. 0 for /dev/mtd0), when the running image
/// exposes it. Used for `ubiattach -m <index>`.
pub nvdata_mtd: Option<u32>,
}
impl A113dPreflight {
pub fn ok(&self) -> bool {
self.checks.iter().all(|c| c.ok)
}
pub fn render(&self) -> String {
let mut out = format!("preflight {}\n", self.host);
for c in &self.checks {
out.push_str(&format!(
"check {} {}: {}\n",
c.name,
if c.ok { "ok" } else { "FAIL" },
c.detail
));
}
out.push_str(&format!(
"result {}",
if self.ok() {
"PASS"
} else {
"FAIL (do not write)"
}
));
out
}
}
/// Parse /proc/mtd for a partition labelled "nvdata" and return its mtd index.
/// e.g. `mtd0: 0b900000 00020000 "nvdata"` -> Some(0).
fn parse_nvdata_mtd(proc_mtd: &str) -> Option<u32> {
for line in proc_mtd.lines() {
let line = line.trim();
if !line.starts_with("mtd") {
continue;
}
let (dev, rest) = line.split_once(':')?;
if rest.contains(&format!("\"{NVDATA_LABEL}\"")) {
return dev.trim_start_matches("mtd").parse::<u32>().ok();
}
}
None
}
pub fn preflight(
plan: &A113dPlan,
remote: &mut dyn Remote,
host: &str,
) -> Result<A113dPreflight, A113dError> {
let mut checks = Vec::new();
let fingerprint = remote.user_command(
"uname -r; echo __MODEL__; cat /proc/device-tree/model 2>/dev/null; echo; \
echo __RELEASE__; cat /etc/os-release 2>/dev/null; cat /etc/alkane-release 2>/dev/null \
|| true",
Duration::from_secs(20),
)?;
let text = String::from_utf8_lossy(&fingerprint).into_owned();
let mut it = text.split("__MODEL__");
let kernel = it.next().unwrap_or("").trim().to_owned();
let rest = it.next().unwrap_or("");
let mut it2 = rest.split("__RELEASE__");
let _model = it2.next().unwrap_or("");
let release = it2.next().unwrap_or("");
let source = classify(&kernel, release, &text);
checks.push(A113dCheck {
name: "source-os".to_owned(),
ok: source == "alkane",
detail: format!("{source} (update path requires alkane)"),
});
let uid = String::from_utf8_lossy(&remote.root_command("id -u", Duration::from_secs(20))?)
.trim()
.to_owned();
checks.push(A113dCheck {
name: "root".to_owned(),
ok: uid == "0",
detail: format!("uid {uid}"),
});
let tools = remote.user_command(
"for c in ubiattach ubidetach mount umount cp md5sum sync; do \
command -v $c >/dev/null 2>&1 && echo $c || echo missing:$c; done",
Duration::from_secs(15),
)?;
let missing: Vec<String> = String::from_utf8_lossy(&tools)
.lines()
.filter_map(|l| l.strip_prefix("missing:").map(str::to_owned))
.collect();
checks.push(A113dCheck {
name: "commands".to_owned(),
ok: missing.is_empty(),
detail: if missing.is_empty() {
"ubi/file tools present".to_owned()
} else {
format!("missing {}", missing.join(", "))
},
});
// The nvdata MTD must be exposed (NAND-enabled a113d kernel). If absent, the
// running image cannot self-update - it needs the DT with the nvdata
// fixed-partition. mtd0-5 are intentionally never exposed, so nvdata is the
// ONLY mtd this board should ever present.
let proc_mtd = String::from_utf8_lossy(
&remote.user_command("cat /proc/mtd 2>/dev/null", Duration::from_secs(20))?,
)
.into_owned();
let nvdata_mtd = parse_nvdata_mtd(&proc_mtd);
checks.push(A113dCheck {
name: "nvdata-mtd".to_owned(),
ok: nvdata_mtd.is_some(),
detail: match nvdata_mtd {
Some(n) => format!("nvdata is /dev/mtd{n} (the only exposed MTD)"),
None => format!("no 'nvdata' MTD exposed: {}", proc_mtd.replace('\n', " ")),
},
});
// Every destination is a bare basename - the structural brick guard.
let dests_safe = plan.targets.iter().all(|t| is_safe_dest(&t.dest));
checks.push(A113dCheck {
name: "file-only".to_owned(),
ok: dests_safe,
detail: format!("all writes are files under {ALKANE_DIR}/ on the nvdata UBI"),
});
Ok(A113dPreflight {
host: host.to_owned(),
checks,
nvdata_mtd,
})
}
#[derive(Clone, Debug)]
pub struct A113dInstallOptions {
pub dry_run: bool,
pub confirm: Option<String>,
pub no_reboot: bool,
pub backup_dir: PathBuf,
}
#[derive(Clone, Debug)]
pub struct A113dBackup {
pub image_name: String,
pub dest: String,
pub path: Option<PathBuf>,
pub md5: Option<String>,
pub size: u64,
}
#[derive(Clone, Debug)]
pub struct A113dReceipt {
pub volume: String,
pub backups: Vec<A113dBackup>,
pub rebooted: bool,
}
pub enum A113dOutcome {
DryRun(Box<A113dPreflight>),
Installed(A113dReceipt),
}
const MNT: &str = "/tmp/.alkane-nvdata";
/// Attach UBI to the nvdata MTD and mount its single user volume read-write.
/// Returns (ubi device number, volume name). The volume name is DISCOVERED, never
/// assumed (vendor histories leave different names: umc_os_rootfs, nvdada_log,
/// overlay, ...).
fn attach_and_mount(remote: &mut dyn Remote, nvdata_mtd: u32) -> Result<String, A113dError> {
// Attach (idempotent: if ubi0 already exists, reuse it).
let _ = remote.root_command(
&format!(
"if [ ! -d /sys/class/ubi/ubi0 ]; then ubiattach -m {nvdata_mtd} -d 0 >/dev/null 2>&1; fi"
),
Duration::from_secs(60),
)?;
// Discover the first user volume name under ubi0.
let name = String::from_utf8_lossy(&remote.root_command(
"for n in /sys/class/ubi/ubi0_*/name; do [ -f \"$n\" ] && cat \"$n\" && break; done",
Duration::from_secs(20),
)?)
.trim()
.to_owned();
if name.is_empty() {
return Err(A113dError::UbiAttach);
}
// Mount it read-write.
remote.root_command(
&format!("mkdir -p {MNT} && mount -t ubifs ubi0:{name} {MNT}"),
Duration::from_secs(60),
)?;
// Confirm the mount actually took.
let mounted = remote.user_command(
&format!("mount | grep -c ' {MNT} '"),
Duration::from_secs(20),
)?;
if String::from_utf8_lossy(&mounted).trim() == "0" {
return Err(A113dError::Mount);
}
Ok(name)
}
fn unmount(remote: &mut dyn Remote) {
let _ = remote.root_command(
&format!(
"sync; umount {MNT} 2>/dev/null; ubidetach -d 0 2>/dev/null; rmdir {MNT} 2>/dev/null"
),
Duration::from_secs(60),
);
}
pub fn install(
plan: &A113dPlan,
remote: &mut dyn Remote,
options: &A113dInstallOptions,
host: &str,
) -> Result<A113dOutcome, A113dError> {
let report = preflight(plan, remote, host)?;
if !report.ok() {
return Err(A113dError::Preflight(report.render()));
}
if options.dry_run {
return Ok(A113dOutcome::DryRun(Box::new(report)));
}
if options.confirm.as_deref() != Some("FLASH") {
return Err(A113dError::Confirm);
}
let nvdata_mtd = report
.nvdata_mtd
.ok_or_else(|| A113dError::NoNvdataMtd(NVDATA_LABEL.to_owned()))?;
fs::create_dir_all(&options.backup_dir)?;
let epoch = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs();
let volume = attach_and_mount(remote, nvdata_mtd)?;
let alkane_dir = format!("{MNT}/{ALKANE_DIR}");
let _ = remote.root_command(&format!("mkdir -p {alkane_dir}"), Duration::from_secs(20))?;
let mut backups = Vec::new();
let result = (|| -> Result<(), A113dError> {
for target in &plan.targets {
// Structural guard at the point of writing: a bare basename only.
if !is_safe_dest(&target.dest) {
return Err(A113dError::UnsafeDest(target.dest.clone()));
}
let name = &target.image_name;
let dest_path = format!("{alkane_dir}/{}", target.dest);
// Back up the existing file, if present.
let have = remote.user_command(
&format!("test -f {dest_path} && echo __YES__"),
Duration::from_secs(15),
)?;
if String::from_utf8_lossy(&have).contains("__YES__") {
let local = options
.backup_dir
.join(format!("{}-{epoch}.bak", target.dest));
remote.pull(&dest_path, &local, Duration::from_secs(300))?;
let data = fs::read(&local)?;
backups.push(A113dBackup {
image_name: name.clone(),
dest: target.dest.clone(),
md5: Some(md5_hex(&data)),
size: data.len() as u64,
path: Some(local),
});
} else {
backups.push(A113dBackup {
image_name: name.clone(),
dest: target.dest.clone(),
md5: None,
size: 0,
path: None,
});
}
// Stage the verified payload and prove its remote md5 before copying.
let mut staged = tempfile::NamedTempFile::new()?;
staged.write_all(&target.data)?;
staged.flush()?;
let remote_stage = format!("/tmp/.alkane-a113d-{name}.img");
remote.push(staged.path(), &remote_stage, Duration::from_secs(300))?;
let staged_md5 = parse_digest(
&remote.root_command(&format!("md5sum {remote_stage}"), Duration::from_secs(60))?,
32,
)
.unwrap_or_default();
if staged_md5 != target.expected_md5 {
let _ =
remote.root_command(&format!("rm -f {remote_stage}"), Duration::from_secs(15));
return Err(A113dError::StageMismatch(name.clone()));
}
// Copy into the UBIFS volume (file write only), then sync.
remote.root_command(
&format!("cp -f {remote_stage} {dest_path} && sync"),
Duration::from_secs(300),
)?;
// Read back the copied file and compare md5.
let readback = parse_digest(
&remote.root_command(&format!("md5sum {dest_path}"), Duration::from_secs(60))?,
32,
)
.unwrap_or_default();
let _ = remote.root_command(&format!("rm -f {remote_stage}"), Duration::from_secs(15));
if readback != target.expected_md5 {
return Err(A113dError::Readback(name.clone()));
}
}
Ok(())
})();
// Always unmount/detach, success or failure, before returning or rebooting.
unmount(remote);
result?;
let rebooted = if options.no_reboot {
false
} else {
remote.reboot()?;
true
};
Ok(A113dOutcome::Installed(A113dReceipt {
volume,
backups,
rebooted,
}))
}
pub fn owns_board(board: &str) -> bool {
board == BOARD
}
/// True when no plan target would ever name a preserved raw partition. Used by
/// tests to assert the structural guard holds for the fixed TARGETS table.
pub fn no_raw_device_targets(plan: &A113dPlan) -> bool {
plan.targets.iter().all(|t| is_safe_dest(&t.dest))
}
#[cfg(test)]
mod tests {
use super::*;
use alkane_artifacts::afw::{AfwManifest, AfwMember};
use serde_json::json;
use sha2::{Digest, Sha256};
const REV: &str = "0123456789abcdef0123456789abcdef01234567";
fn arm64_image(payload: &[u8]) -> Vec<u8> {
let mut b = vec![0u8; 64];
b[0x38..0x3C].copy_from_slice(b"ARMd");
b.extend_from_slice(payload);
b
}
fn dtb() -> Vec<u8> {
let mut b = vec![0u8; 2048];
b[0..4].copy_from_slice(&[0xd0, 0x0d, 0xfe, 0xed]);
b
}
fn uramdisk() -> Vec<u8> {
let mut b = vec![0u8; 64];
b[0..4].copy_from_slice(&[0x27, 0x05, 0x19, 0x56]);
b
}
fn afw_with(
kernel: Vec<u8>,
dtb: Vec<u8>,
rootfs: Vec<u8>,
partitions: serde_json::Value,
) -> VerifiedAfw {
let image = |name: &str, file: &str, role: &str, fmt: &str, data: &[u8]| {
let sha: String = Sha256::digest(data)
.iter()
.map(|b| format!("{b:02x}"))
.collect();
json!({"name": name, "file": file, "role": role, "format": fmt,
"size": data.len(), "sha256": sha, "partition": "nvdata", "install": true})
};
let value = json!({
"schema": 2, "format": "afw", "board": "a113d", "arch": "arm64",
"version": "0.1.0", "build_date": "2026-11-06T00:00:00Z",
"sdk_revision": REV, "os_revision": REV, "payload_type": "os",
"bootloader_policy": "preserve",
"signature": {"type": "unsigned", "member": null, "public_key_hex": null},
"partitions": partitions,
"images": [
image("kernel", "payload/vmlinux.bin", "kernel", "arm64-image", &kernel),
image("dtb", "payload/devicetree.dtb", "dtb", "fdt", &dtb),
image("rootfs", "payload/uramdisk.image.gz", "rootfs", "uimage", &rootfs),
],
"boot_switch": {}, "preflight": {"min_free_bytes": 16777216},
"recovery": {}, "marker": "Alkane", "kernel_version": "6.18.48"
});
let manifest: AfwManifest = serde_json::from_value(value).unwrap();
VerifiedAfw {
manifest,
members: vec![
AfwMember {
name: "payload/vmlinux.bin".to_owned(),
data: kernel,
},
AfwMember {
name: "payload/devicetree.dtb".to_owned(),
data: dtb,
},
AfwMember {
name: "payload/uramdisk.image.gz".to_owned(),
data: rootfs,
},
],
manifest_sha256: "0".repeat(64),
archive_sha256: "0".repeat(64),
}
}
fn preserved_partitions() -> serde_json::Value {
json!([
{"name":"bootloader","device":"/dev/mtd0","offset":0,"size":2097152,
"secure":true,"boot_critical":true,"write_order":0,"image":null},
{"name":"nvdata","device":"/dev/mtd6","offset":74448896,"size":193986560,
"secure":false,"boot_critical":true,"write_order":1,"image":"kernel"}
])
}
fn good() -> VerifiedAfw {
afw_with(arm64_image(b"k"), dtb(), uramdisk(), preserved_partitions())
}
#[test]
fn accepts_a_good_plan_as_file_copies() {
let plan = A113dPlan::from_afw(&good()).unwrap();
assert_eq!(plan.targets.len(), 3);
// write order rootfs, dtb, kernel (kernel file lands last)
assert_eq!(plan.targets[0].image_name, "rootfs");
assert_eq!(plan.targets[2].image_name, "kernel");
assert!(no_raw_device_targets(&plan));
for t in &plan.targets {
assert!(
!t.dest.contains('/'),
"{} has a path, not a basename",
t.image_name
);
}
assert!(plan.render().contains("alkane/"));
assert!(plan.render().contains("no raw NAND write is possible"));
}
#[test]
fn refuses_a_non_arm64_kernel() {
let r = A113dPlan::from_afw(&afw_with(
vec![0u8; 64],
dtb(),
uramdisk(),
preserved_partitions(),
));
assert!(matches!(r, Err(A113dPlanError::NotArm64 { .. })));
}
#[test]
fn refuses_an_oversize_kernel() {
let big = arm64_image(&vec![0u8; 0x4000000]);
let r = A113dPlan::from_afw(&afw_with(big, dtb(), uramdisk(), preserved_partitions()));
assert!(matches!(r, Err(A113dPlanError::ImageTooLarge { .. })));
}
#[test]
fn refuses_a_fip_member() {
let mut v = good();
v.manifest.images[0].role = "bootloader".to_owned();
assert!(matches!(
A113dPlan::from_afw(&v),
Err(A113dPlanError::BootloaderMember(_))
));
let mut v = good();
v.manifest.images[1].file = "payload/fip.bin".to_owned();
assert!(matches!(
A113dPlan::from_afw(&v),
Err(A113dPlanError::BootloaderMember(_))
));
}
#[test]
fn refuses_a_preserved_partition_carrying_an_image() {
let partitions = json!([
{"name":"bootloader","device":"/dev/mtd0","offset":0,"size":2097152,
"secure":true,"boot_critical":true,"write_order":0,"image":"kernel"},
{"name":"nvdata","device":"/dev/mtd6","offset":74448896,"size":193986560,
"secure":false,"boot_critical":true,"write_order":1,"image":"kernel"}
]);
let v = afw_with(arm64_image(b"k"), dtb(), uramdisk(), partitions);
assert!(matches!(
A113dPlan::from_afw(&v),
Err(A113dPlanError::PreservedCarriesImage(_))
));
}
#[test]
fn wrong_board_and_arch_are_refused() {
let mut v = good();
v.manifest.board = "zynq-7010".to_owned();
assert!(matches!(
A113dPlan::from_afw(&v),
Err(A113dPlanError::WrongBoard(_))
));
let mut v = good();
v.manifest.arch = "armv7".to_owned();
assert!(matches!(
A113dPlan::from_afw(&v),
Err(A113dPlanError::WrongArch(_))
));
}
#[test]
fn every_target_is_a_basename_never_a_device() {
for (image, dest, _ceiling, _fmt) in TARGETS {
assert!(
is_safe_dest(dest),
"{image} dest {dest} is not a safe basename"
);
}
}
#[test]
fn unsafe_dest_is_rejected_by_guard() {
assert!(!is_safe_dest("/dev/mtd0"));
assert!(!is_safe_dest("../escape"));
assert!(!is_safe_dest("sub/dir/file"));
assert!(is_safe_dest("vmlinux.bin"));
}
#[test]
fn parses_the_nvdata_mtd_index() {
let proc_mtd = "dev: size erasesize name\n\
mtd0: 0b900000 00020000 \"nvdata\"\n";
assert_eq!(parse_nvdata_mtd(proc_mtd), Some(0));
// No nvdata line -> None (the no-NAND running image).
assert_eq!(parse_nvdata_mtd("dev: size erasesize name\n"), None);
// Different index is honored.
assert_eq!(
parse_nvdata_mtd("mtd3: 0b900000 00020000 \"nvdata\"\n"),
Some(3)
);
}
}
File diff suppressed because it is too large Load Diff
+406
View File
@@ -0,0 +1,406 @@
// SPDX-License-Identifier: MIT
//! CV1835 board module: the only write is the 16 MiB p1 FIT.
//!
//! The vendor boot0, BL2, BL31 and U-Boot chain is preserved. The board plan is
//! read from the verified `.afw` manifest, not guessed at runtime.
use crate::md5::md5_hex;
use alkane_artifacts::afw::{
AfwImage, AfwManifest, AfwPartition, BootloaderPolicy, VerifiedAfw, CV1835_P1_SIZE,
};
use thiserror::Error;
pub const BOARD: &str = "cv1835";
pub const ARCH: &str = "arm64";
pub const P1_DEVICE: &str = "/dev/mmcblk0p1";
pub const MARKER: &str = "CVBOOT";
pub const UPDATE_DAEMON_PORT: u16 = 12887;
pub const GOLDEN_LBA_BYTES: u64 = 0x300000 * 512;
#[derive(Debug, Error)]
pub enum CvPlanError {
#[error("bundle is for {0}, not cv1835")]
WrongBoard(String),
#[error("bundle arch is {0}, cv1835 needs arm64")]
WrongArch(String),
#[error("cv1835 requires bootloader_policy preserve")]
BootloaderPolicy,
#[error("cv1835 bundle carries a bootloader member")]
BootloaderMember,
#[error("cv1835 bundle must install exactly p1")]
MissingP1,
#[error("cv1835 p1 is {0} bytes, not the 16 MiB padded FIT")]
P1Size(u64),
#[error("cv1835 p1 partition is not /dev/mmcblk0p1")]
P1Device,
#[error("cv1835 p1 partition must be 16 MiB, non-secure and written once")]
P1Geometry,
#[error("cv1835 p1 is not a bootable FIT: {0}")]
Fit(String),
#[error("manifest marker is empty")]
Marker,
#[error("manifest kernel_version is empty")]
KernelVersion,
#[error("manifest is not an OS payload")]
PayloadType,
#[error("manifest preflight is missing {0}")]
Preflight(String),
}
#[derive(Clone, Debug)]
pub struct Cv1835Plan {
pub image: AfwImage,
pub data: Vec<u8>,
pub partition: AfwPartition,
pub expected_md5: String,
pub expected_sha256: String,
pub marker: String,
pub kernel_version: String,
pub sdk_revision: String,
pub os_revision: String,
pub source_os: Vec<String>,
pub required_commands: Vec<String>,
pub min_free_bytes: u64,
pub golden_lba_bytes: u64,
}
impl Cv1835Plan {
pub fn from_afw(afw: &VerifiedAfw) -> Result<Self, CvPlanError> {
let manifest = &afw.manifest;
if manifest.board != BOARD {
return Err(CvPlanError::WrongBoard(manifest.board.clone()));
}
if manifest.arch != ARCH {
return Err(CvPlanError::WrongArch(manifest.arch.clone()));
}
if manifest.payload_type != "os" {
return Err(CvPlanError::PayloadType);
}
if manifest.bootloader_policy != BootloaderPolicy::Preserve {
return Err(CvPlanError::BootloaderPolicy);
}
if manifest
.images
.iter()
.any(|image| image.role == "bootloader")
{
return Err(CvPlanError::BootloaderMember);
}
if manifest.marker.is_empty() {
return Err(CvPlanError::Marker);
}
if manifest.kernel_version.is_empty() {
return Err(CvPlanError::KernelVersion);
}
let install: Vec<&AfwImage> = manifest
.images
.iter()
.filter(|image| image.install)
.collect();
if install.len() != 1 || install[0].name != "p1" {
return Err(CvPlanError::MissingP1);
}
let image = install[0].clone();
if image.format != "fit" {
return Err(CvPlanError::Fit("format is not fit".to_owned()));
}
if image.size != CV1835_P1_SIZE {
return Err(CvPlanError::P1Size(image.size));
}
let (_, data) = afw.install_image().ok_or(CvPlanError::MissingP1)?;
if !data.starts_with(b"\xd0\x0d\xfe\xed") {
return Err(CvPlanError::Fit("missing FDT/FIT magic".to_owned()));
}
if !contains(data, b"config@cv1835_miner_emmc") {
return Err(CvPlanError::Fit(
"missing config@cv1835_miner_emmc".to_owned(),
));
}
if contains(data, b"signature@") {
return Err(CvPlanError::Fit("carries signature@ nodes".to_owned()));
}
let partition = manifest
.partitions
.iter()
.find(|part| part.name == "p1")
.ok_or(CvPlanError::P1Device)?
.clone();
if partition.device != P1_DEVICE {
return Err(CvPlanError::P1Device);
}
if partition.size != CV1835_P1_SIZE
|| partition.secure
|| !partition.boot_critical
|| partition.write_order != 1
{
return Err(CvPlanError::P1Geometry);
}
if manifest
.partitions
.iter()
.any(|part| part.write_order > 0 && part.name != "p1")
{
return Err(CvPlanError::MissingP1);
}
let source_os = json_strings(&manifest.preflight, "source_os");
let required_commands = json_strings(&manifest.preflight, "required_commands");
let min_free_bytes = manifest
.preflight
.get("min_free_bytes")
.and_then(|value| value.as_u64())
.unwrap_or(32 * 1024 * 1024);
let golden_lba_bytes = manifest
.recovery
.get("golden_lba_bytes")
.and_then(|value| value.as_u64())
.unwrap_or(GOLDEN_LBA_BYTES);
Ok(Self {
expected_md5: md5_hex(data),
expected_sha256: image.sha256.clone(),
image,
data: data.to_vec(),
partition,
marker: manifest.marker.clone(),
kernel_version: manifest.kernel_version.clone(),
sdk_revision: manifest.sdk_revision.clone(),
os_revision: manifest.os_revision.clone(),
source_os,
required_commands,
min_free_bytes,
golden_lba_bytes,
})
}
pub fn render(&self) -> String {
format!(
"board cv1835 arch arm64\n\
partition {} {} {} B secure=false boot_critical=true write_order={}\n\
image {} {} {} B sha256 {}\n\
image md5 {}\n\
bootloader preserve (vendor boot0/BL2/BL31/U-Boot kept)\n\
boot switch partition-overwrite (p1 is the switch)\n\
marker {} kernel {} sdk {} os {}",
self.partition.name,
self.partition.device,
self.partition.size,
self.partition.write_order,
self.image.name,
self.image.file,
self.image.size,
self.image.sha256,
self.expected_md5,
self.marker,
self.kernel_version,
short_revision(&self.sdk_revision),
short_revision(&self.os_revision),
)
}
}
fn short_revision(revision: &str) -> &str {
revision.get(..12).unwrap_or(revision)
}
fn contains(haystack: &[u8], needle: &[u8]) -> bool {
haystack
.windows(needle.len())
.any(|window| window == needle)
}
fn json_strings(value: &serde_json::Value, key: &str) -> Vec<String> {
value
.get(key)
.and_then(|item| item.as_array())
.map(|items| {
items
.iter()
.filter_map(|item| item.as_str().map(str::to_owned))
.collect()
})
.unwrap_or_default()
}
pub fn manifest_from_json(value: serde_json::Value) -> Result<AfwManifest, serde_json::Error> {
serde_json::from_value(value)
}
#[cfg(test)]
mod tests {
use super::*;
use alkane_artifacts::afw::AfwMember;
use serde_json::json;
use sha2::{Digest, Sha256};
const P1: usize = CV1835_P1_SIZE as usize;
const REV: &str = "0000000000000000000000000000000000000000";
fn sha_hex(data: &[u8]) -> String {
Sha256::digest(data)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect()
}
fn p1_image() -> Vec<u8> {
let mut fit = vec![0_u8; P1];
fit[..4].copy_from_slice(b"\xd0\x0d\xfe\xed");
let marker = b"config@cv1835_miner_emmc";
fit[0x100..0x100 + marker.len()].copy_from_slice(marker);
fit
}
fn manifest_value(p1: &[u8]) -> serde_json::Value {
json!({
"schema": 2,
"format": "afw",
"board": "cv1835",
"arch": "arm64",
"version": "0.1.0",
"build_date": "2026-11-04T00:00:00Z",
"sdk_revision": REV,
"os_revision": REV,
"payload_type": "os",
"bootloader_policy": "preserve",
"signature": {"type": "unsigned", "member": null, "public_key_hex": null},
"partitions": [
{"name": "p1", "device": "/dev/mmcblk0p1", "offset": 0,
"size": CV1835_P1_SIZE, "secure": false, "boot_critical": true,
"write_order": 1, "image": "p1"},
{"name": "boot0", "device": "/dev/mmcblk0boot0", "offset": 0,
"size": 4194304, "secure": true, "boot_critical": true,
"write_order": 0, "image": null}
],
"images": [
{"name": "p1", "file": "payload/p1.fit", "role": "boot",
"format": "fit", "size": p1.len(),
"sha256": sha_hex(p1),
"partition": "p1", "install": true}
],
"boot_switch": {"method": "partition-overwrite"},
"preflight": {"required_commands": ["dd", "md5sum", "sync"],
"source_os": ["stock-bitmain", "vnish", "braiins", "ouros", "alkane"],
"min_free_bytes": 33554432},
"recovery": {"network": "afw restore", "golden_lba_bytes": GOLDEN_LBA_BYTES},
"marker": "CVBOOT",
"kernel_version": "6.18.48"
})
}
fn afw(p1: &[u8]) -> VerifiedAfw {
let manifest = manifest_from_json(manifest_value(p1)).unwrap();
VerifiedAfw {
manifest,
members: vec![AfwMember {
name: "payload/p1.fit".to_owned(),
data: p1.to_vec(),
}],
manifest_sha256: "0".repeat(64),
archive_sha256: "0".repeat(64),
}
}
#[test]
fn accepts_the_cv_plan() {
let data = p1_image();
let plan = Cv1835Plan::from_afw(&afw(&data)).unwrap();
assert_eq!(plan.partition.device, "/dev/mmcblk0p1");
assert_eq!(plan.image.size, CV1835_P1_SIZE);
assert_eq!(plan.marker, "CVBOOT");
assert!(plan
.render()
.contains("partition p1 /dev/mmcblk0p1 16777216"));
}
#[test]
fn refuses_a_bundle_for_another_board() {
let data = p1_image();
let mut verified = afw(&data);
verified.manifest.board = "zynq-7010".to_owned();
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::WrongBoard(_))
));
}
#[test]
fn refuses_include_bootloader_policy() {
let data = p1_image();
let mut verified = afw(&data);
verified.manifest.bootloader_policy = BootloaderPolicy::Include;
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::BootloaderPolicy)
));
}
#[test]
fn refuses_a_bootloader_member() {
let data = p1_image();
let mut verified = afw(&data);
verified.manifest.images.push(AfwImage {
name: "u-boot".to_owned(),
file: "payload/u-boot.img".to_owned(),
role: "bootloader".to_owned(),
format: "uimage".to_owned(),
size: 4,
sha256: "0".repeat(64),
partition: None,
install: false,
});
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::BootloaderMember)
));
}
#[test]
fn refuses_a_short_p1() {
let data = vec![0_u8; 1024];
let verified = afw(&data);
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::P1Size(1024))
));
}
#[test]
fn refuses_a_secure_p1() {
let data = p1_image();
let mut verified = afw(&data);
verified.manifest.partitions[0].secure = true;
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::P1Geometry)
));
}
#[test]
fn refuses_a_wrong_device() {
let data = p1_image();
let mut verified = afw(&data);
verified.manifest.partitions[0].device = "/dev/mmcblk0p3".to_owned();
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::P1Device)
));
}
#[test]
fn refuses_a_fit_without_the_board_config() {
let mut data = p1_image();
for byte in data.iter_mut() {
if *byte == b'c' {
*byte = b'x';
}
}
let verified = afw(&data);
assert!(matches!(
Cv1835Plan::from_afw(&verified),
Err(CvPlanError::Fit(_))
));
}
}
+8
View File
@@ -0,0 +1,8 @@
// SPDX-License-Identifier: MIT
//! Board modules. Each module validates the verified manifest for its family
//! and exposes the exact write plan the installer follows.
pub mod a113d;
pub mod am335x;
pub mod cv1835;
pub mod zynq;
+410
View File
@@ -0,0 +1,410 @@
// SPDX-License-Identifier: MIT
//! Zynq-7010 board module: the manifest gate and write plan for putting our
//! OS onto a Zynq control board (Antminer S17/S19 class).
//!
//! This module decides WHAT may be written and WHERE, in absolute NAND terms.
//! It does not write. The write itself (for a board already on alkane, and for
//! the first install from stock) is done by the compiled-in method behind
//! `crate::stock` (`update_in_place` / `install_from_stock`), because on a board
//! running alkane the boot regions are deliberately not exposed to Linux and
//! have to be re-registered first; that mechanism lives with the method.
//!
//! Layout (absolute NAND offsets, 128 KiB erase blocks): BOOT.bin (FSBL + FPGA
//! bitstream + stock U-Boot + env) occupies 0x0..0x1a00000 and is never
//! written. The stock U-Boot reads the dtb at 0x1a00000, the kernel at
//! 0x2000000 and the ramdisk at 0x2800000, and boots the kernel and ramdisk as
//! legacy uImages, so both are written with a 64-byte uImage header.
//!
//! History: an earlier version of this module wrote raw images at
//! device-relative offsets on /dev/mtd0 and /dev/mtd1. That matched an early
//! alkane image that exposed the whole NAND, not the current one (which exposes
//! only the small `stock-cfg` and `alkane-cfg` partitions), and its raw kernel
//! and ramdisk were not bootable by the stock U-Boot. It was removed.
use crate::md5::md5_hex;
use alkane_artifacts::afw::{AfwImage, BootloaderPolicy, VerifiedAfw};
use thiserror::Error;
pub const BOARD: &str = "zynq-7010";
pub const ARCH: &str = "armv7";
/// Absolute NAND 0x0..0x1a00000 is BOOT.bin (FSBL + FPGA bitstream + stock
/// U-Boot) + the U-Boot env, and is NEVER erased or written.
pub const BOOTBIN_PRESERVE: u64 = 0x1A00000;
/// Size of the legacy uImage header the stock U-Boot needs on the kernel and
/// the ramdisk.
const UIMAGE_HEADER: u64 = 64;
/// Write targets in write order (rootfs, dtb, kernel, so an interrupted write
/// never leaves a new rootfs under an old kernel): (image, absolute NAND
/// offset, slot size, expected manifest format, uImage-wrapped).
const TARGETS: [(&str, u64, u64, &str, bool); 3] = [
("rootfs", 0x2800000, 0x2000000, "cpio-gzip", true),
("dtb", 0x1A00000, 0x20000, "fdt", false),
("kernel", 0x2000000, 0x800000, "zimage", true),
];
#[derive(Debug, Error)]
pub enum ZynqPlanError {
#[error("bundle is for {0}, not zynq-7010")]
WrongBoard(String),
#[error("bundle arch is {0}, zynq-7010 needs armv7")]
WrongArch(String),
#[error("zynq-7010 requires bootloader_policy preserve")]
BootloaderPolicy,
#[error("zynq-7010 bundle carries a bootloader/spl/BOOT.bin member: {0}")]
BootloaderMember(String),
#[error("manifest is not an OS payload")]
PayloadType,
#[error("manifest marker is empty")]
Marker,
#[error("zynq-7010 must install exactly kernel, dtb and rootfs")]
InstallCount,
#[error("zynq-7010 is missing the {0} image")]
MissingImage(String),
#[error("zynq-7010 {image} format is {actual}, expected {expected}")]
ImageFormat {
image: String,
actual: String,
expected: &'static str,
},
#[error("zynq-7010 {image} is {size} bytes, over the {ceiling}-byte ceiling for its 0x{slot:x} slot")]
ImageTooLarge {
image: String,
size: u64,
ceiling: u64,
slot: u64,
},
#[error("zynq-7010 {image} is not an ARM zImage")]
NotZImage { image: String },
#[error("zynq-7010 refuses to place {image} at 0x{offset:x}: below BOOT.bin (0x{bootbin:x})")]
WouldClobberBootbin {
image: String,
offset: u64,
bootbin: u64,
},
}
#[derive(Clone, Debug)]
pub struct ZynqTarget {
pub image_name: String,
/// Absolute NAND offset of the slot.
pub absolute: u64,
pub slot: u64,
/// Size of the image as shipped in the `.afw` (before any uImage header).
pub size: u64,
pub uimage_wrapped: bool,
pub data: Vec<u8>,
pub expected_md5: String,
}
#[derive(Clone, Debug)]
pub struct ZynqPlan {
pub targets: Vec<ZynqTarget>,
pub marker: String,
pub kernel_version: String,
pub sdk_revision: String,
pub os_revision: String,
pub afw_sha256: String,
}
fn is_bootloaderish(image: &AfwImage) -> bool {
let lowered = format!("{} {} {}", image.name, image.file, image.role).to_lowercase();
image.role == "bootloader"
|| lowered.contains("spl")
|| lowered.contains("u-boot")
|| lowered.contains("uboot")
|| lowered.contains("boot.bin")
}
impl ZynqPlan {
pub fn from_afw(afw: &VerifiedAfw) -> Result<Self, ZynqPlanError> {
let manifest = &afw.manifest;
if manifest.board != BOARD {
return Err(ZynqPlanError::WrongBoard(manifest.board.clone()));
}
if manifest.arch != ARCH {
return Err(ZynqPlanError::WrongArch(manifest.arch.clone()));
}
if manifest.payload_type != "os" {
return Err(ZynqPlanError::PayloadType);
}
if manifest.bootloader_policy != BootloaderPolicy::Preserve {
return Err(ZynqPlanError::BootloaderPolicy);
}
if manifest.marker.is_empty() {
return Err(ZynqPlanError::Marker);
}
// BOOT.bin / bootloader members are never allowed - we reuse the board's.
for image in &manifest.images {
if is_bootloaderish(image) {
return Err(ZynqPlanError::BootloaderMember(image.file.clone()));
}
}
let installs: Vec<&AfwImage> = manifest.images.iter().filter(|i| i.install).collect();
if installs.len() != TARGETS.len() {
return Err(ZynqPlanError::InstallCount);
}
let mut targets = Vec::with_capacity(TARGETS.len());
for (image_name, absolute, slot, expected_format, wrapped) in TARGETS {
let image = manifest
.images
.iter()
.find(|i| i.name == image_name && i.install)
.ok_or_else(|| ZynqPlanError::MissingImage(image_name.to_owned()))?;
if image.format != expected_format {
return Err(ZynqPlanError::ImageFormat {
image: image_name.to_owned(),
actual: image.format.clone(),
expected: expected_format,
});
}
let ceiling = if wrapped { slot - UIMAGE_HEADER } else { slot };
if image.size > ceiling {
return Err(ZynqPlanError::ImageTooLarge {
image: image_name.to_owned(),
size: image.size,
ceiling,
slot,
});
}
// The hard brick guard: nothing is ever placed inside BOOT.bin.
if absolute < BOOTBIN_PRESERVE {
return Err(ZynqPlanError::WouldClobberBootbin {
image: image_name.to_owned(),
offset: absolute,
bootbin: BOOTBIN_PRESERVE,
});
}
let data = afw
.image(image_name)
.map(|(_, data)| data)
.ok_or_else(|| ZynqPlanError::MissingImage(image_name.to_owned()))?;
if expected_format == "zimage"
&& !(data.len() >= 0x28 && data[0x24..0x28] == [0x18, 0x28, 0x6f, 0x01])
{
return Err(ZynqPlanError::NotZImage {
image: image_name.to_owned(),
});
}
targets.push(ZynqTarget {
image_name: image_name.to_owned(),
absolute,
slot,
size: image.size,
uimage_wrapped: wrapped,
expected_md5: md5_hex(data),
data: data.to_vec(),
});
}
Ok(Self {
targets,
marker: manifest.marker.clone(),
kernel_version: manifest.kernel_version.clone(),
sdk_revision: manifest.sdk_revision.clone(),
os_revision: manifest.os_revision.clone(),
afw_sha256: afw.archive_sha256.clone(),
})
}
pub fn render(&self) -> String {
let mut out = format!("board {BOARD} arch {ARCH}\n");
out.push_str(&format!(
"boot slots (absolute NAND); BOOT.bin 0x0..0x{BOOTBIN_PRESERVE:x} preserved, never written\n"
));
out.push_str(
"kernel and rootfs are written as legacy uImages (what the stock U-Boot boots); dtb raw\n",
);
for target in &self.targets {
out.push_str(&format!(
"write {:<6} abs 0x{:x} slot 0x{:x} size {} B{} md5 {}\n",
target.image_name,
target.absolute,
target.slot,
target.size,
if target.uimage_wrapped {
" +64 B header"
} else {
""
},
target.expected_md5
));
}
out.push_str(&format!(
"marker {} kernel {} sdk {} os {}",
self.marker,
self.kernel_version,
short(&self.sdk_revision),
short(&self.os_revision),
));
out
}
}
fn short(rev: &str) -> &str {
rev.get(..12).unwrap_or(rev)
}
pub fn owns_board(board: &str) -> bool {
board == BOARD
}
#[cfg(test)]
mod tests {
use super::*;
use alkane_artifacts::afw::{AfwManifest, AfwMember};
use serde_json::json;
use sha2::{Digest, Sha256};
const REV: &str = "0123456789abcdef0123456789abcdef01234567";
fn zimage(payload: &[u8]) -> Vec<u8> {
let mut b = vec![0u8; 64];
b[0x24..0x28].copy_from_slice(&[0x18, 0x28, 0x6f, 0x01]);
b.extend_from_slice(payload);
b
}
fn afw(kernel: Vec<u8>, dtb: Vec<u8>, rootfs: Vec<u8>) -> VerifiedAfw {
let image = |name: &str, file: &str, role: &str, fmt: &str, data: &[u8]| {
let sha: String = Sha256::digest(data)
.iter()
.map(|b| format!("{b:02x}"))
.collect();
json!({"name": name, "file": file, "role": role, "format": fmt,
"size": data.len(), "sha256": sha, "partition": "x", "install": true})
};
let value = json!({
"schema": 2, "format": "afw", "board": "zynq-7010", "arch": "armv7",
"version": "0.1.0", "build_date": "2026-11-06T00:00:00Z",
"sdk_revision": REV, "os_revision": REV, "payload_type": "os",
"bootloader_policy": "preserve",
"signature": {"type": "unsigned", "member": null, "public_key_hex": null},
"partitions": [],
"images": [
image("kernel", "payload/zImage", "kernel", "zimage", &kernel),
image("dtb", "payload/zynq-alkane.dtb", "dtb", "fdt", &dtb),
image("rootfs", "payload/rootfs.cpio.gz", "rootfs", "cpio-gzip", &rootfs),
],
"boot_switch": {}, "preflight": {"min_free_bytes": 16777216},
"recovery": {}, "marker": "Alkane", "kernel_version": "6.18.48"
});
let manifest: AfwManifest = serde_json::from_value(value).unwrap();
VerifiedAfw {
manifest,
members: vec![
AfwMember {
name: "payload/zImage".to_owned(),
data: kernel,
},
AfwMember {
name: "payload/zynq-alkane.dtb".to_owned(),
data: dtb,
},
AfwMember {
name: "payload/rootfs.cpio.gz".to_owned(),
data: rootfs,
},
],
manifest_sha256: "0".repeat(64),
archive_sha256: "0".repeat(64),
}
}
fn dtb() -> Vec<u8> {
let mut b = vec![0u8; 1024];
b[0..4].copy_from_slice(&[0xd0, 0x0d, 0xfe, 0xed]);
b
}
#[test]
fn accepts_a_good_plan_and_places_above_bootbin() {
let plan = ZynqPlan::from_afw(&afw(zimage(b"k"), dtb(), b"\x1f\x8brf".to_vec())).unwrap();
assert_eq!(plan.targets.len(), 3);
// write order rootfs, dtb, kernel
assert_eq!(plan.targets[0].image_name, "rootfs");
assert_eq!(plan.targets[2].image_name, "kernel");
for t in &plan.targets {
assert!(
t.absolute >= BOOTBIN_PRESERVE,
"{} below BOOT.bin",
t.image_name
);
}
let render = plan.render();
assert!(render.contains("BOOT.bin"));
assert!(render.contains("uImage"));
}
#[test]
fn slots_match_the_stock_uboot_layout() {
let plan = ZynqPlan::from_afw(&afw(zimage(b"k"), dtb(), b"\x1f\x8brf".to_vec())).unwrap();
let at = |name: &str| plan.targets.iter().find(|t| t.image_name == name).unwrap();
assert_eq!((at("dtb").absolute, at("dtb").slot), (0x1A00000, 0x20000));
assert_eq!(
(at("kernel").absolute, at("kernel").slot),
(0x2000000, 0x800000)
);
assert_eq!(
(at("rootfs").absolute, at("rootfs").slot),
(0x2800000, 0x2000000)
);
assert!(at("kernel").uimage_wrapped && at("rootfs").uimage_wrapped);
assert!(!at("dtb").uimage_wrapped);
}
#[test]
fn refuses_a_non_zimage_kernel() {
let result = ZynqPlan::from_afw(&afw(vec![0u8; 64], dtb(), b"\x1f\x8brf".to_vec()));
assert!(matches!(result, Err(ZynqPlanError::NotZImage { .. })));
}
#[test]
fn refuses_a_kernel_that_would_not_fit_with_its_uimage_header() {
// Exactly the slot size is too big once the 64-byte header is added.
let big = zimage(&vec![0u8; 0x800000 - 64]);
assert_eq!(big.len(), 0x800000);
let result = ZynqPlan::from_afw(&afw(big, dtb(), b"\x1f\x8brf".to_vec()));
assert!(matches!(result, Err(ZynqPlanError::ImageTooLarge { .. })));
let fits = zimage(&vec![0u8; 0x800000 - 128]);
assert!(ZynqPlan::from_afw(&afw(fits, dtb(), b"\x1f\x8brf".to_vec())).is_ok());
}
#[test]
fn refuses_a_bootloader_member() {
let mut verified = afw(zimage(b"k"), dtb(), b"\x1f\x8brf".to_vec());
verified.manifest.images[0].role = "bootloader".to_owned();
assert!(matches!(
ZynqPlan::from_afw(&verified),
Err(ZynqPlanError::BootloaderMember(_))
));
}
#[test]
fn wrong_board_and_arch_are_refused() {
let mut v = afw(zimage(b"k"), dtb(), b"\x1f\x8brf".to_vec());
v.manifest.board = "am335x".to_owned();
assert!(matches!(
ZynqPlan::from_afw(&v),
Err(ZynqPlanError::WrongBoard(_))
));
let mut v = afw(zimage(b"k"), dtb(), b"\x1f\x8brf".to_vec());
v.manifest.arch = "arm".to_owned();
assert!(matches!(
ZynqPlan::from_afw(&v),
Err(ZynqPlanError::WrongArch(_))
));
}
#[test]
fn every_target_is_above_bootbin() {
for (image, absolute, _slot, _fmt, _wrapped) in TARGETS {
assert!(
absolute >= BOOTBIN_PRESERVE,
"{image} target below BOOT.bin"
);
}
}
}
+920
View File
@@ -0,0 +1,920 @@
// SPDX-License-Identifier: MIT
//! CV1835 install, restore and live verification over the network.
//!
//! Order of operations for an install: verify the bundle, preflight the board,
//! hold the current p1 over SSH, stage the new p1, write it once, read the whole
//! partition back, and only then reboot. Any doubt before the first write stops
//! the sequence. A read-back mismatch stops before reboot and prints the exact
//! restore command.
use crate::boards::cv1835::{Cv1835Plan, CvPlanError};
use crate::md5::md5_hex;
use crate::preflight::{preflight, PreflightError, PreflightOptions, PreflightReport};
use crate::transport::{Remote, RemoteError, SshOptions, SshTransport};
use alkane_artifacts::afw::{AfwError, VerifiedAfw};
use sha2::{Digest, Sha256};
use std::fs;
use std::io::{Read, Write};
use std::net::{TcpStream, ToSocketAddrs};
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
use thiserror::Error;
const REMOTE_BACKUP: &str = "/tmp/.alkane-p1-backup.img";
const REMOTE_STAGE: &str = "/tmp/.alkane-p1-stage.img";
#[derive(Debug, Error)]
pub enum InstallError {
#[error("preflight failed; do not write\n{0}")]
Preflight(String),
#[error("install and restore need --confirm FLASH")]
Confirm,
#[error("verified .afw: {0}")]
Afw(#[from] AfwError),
#[error("cv1835 plan: {0}")]
Plan(#[from] CvPlanError),
#[error("preflight: {0}")]
PreflightError(#[from] PreflightError),
#[error("remote: {0}")]
Remote(#[from] RemoteError),
#[error("I/O: {0}")]
Io(#[from] std::io::Error),
#[error("backup {0} is not the 16 MiB p1 size")]
BackupSize(PathBuf),
#[error("backup md5 does not match the live p1; refusing to continue")]
BackupMismatch,
#[error("staged image md5 does not match the verified bundle; nothing written")]
StageMismatch,
#[error("p1 read-back md5 mismatch; do not reboot. Restore with: {0}")]
Readback(String),
#[error("restore read-back md5 mismatch; the board may still hold the new image")]
RestoreReadback,
}
#[derive(Clone, Debug)]
pub struct InstallOptions {
pub dry_run: bool,
pub confirm: Option<String>,
pub no_reboot: bool,
pub backup_dir: PathBuf,
pub held_backup: Option<PathBuf>,
pub allow_unknown_source: bool,
pub check_golden: bool,
}
impl Default for InstallOptions {
fn default() -> Self {
Self {
dry_run: false,
confirm: None,
no_reboot: false,
backup_dir: default_backup_dir(),
held_backup: None,
allow_unknown_source: false,
check_golden: false,
}
}
}
#[derive(Clone, Debug)]
pub struct InstallReceipt {
pub backup_path: PathBuf,
pub backup_md5: String,
pub backup_sha256: String,
pub image_md5: String,
pub rebooted: bool,
}
#[derive(Clone, Debug)]
pub enum InstallOutcome {
DryRun(Box<PreflightReport>),
Installed(InstallReceipt),
}
pub fn install(
_afw: &VerifiedAfw,
plan: &Cv1835Plan,
remote: &mut dyn Remote,
options: &InstallOptions,
host: &str,
) -> Result<InstallOutcome, InstallError> {
let report = preflight(
plan,
remote,
&PreflightOptions {
host,
held_backup: options.held_backup.as_deref(),
check_golden: options.check_golden,
allow_unknown_source: options.allow_unknown_source,
},
)?;
if !report.ok() {
return Err(InstallError::Preflight(report.render()));
}
if options.dry_run {
return Ok(InstallOutcome::DryRun(Box::new(report)));
}
if options.confirm.as_deref() != Some("FLASH") {
return Err(InstallError::Confirm);
}
fs::create_dir_all(&options.backup_dir)?;
let epoch = SystemTime::now()
.duration_since(UNIX_EPOCH)
.unwrap_or_default()
.as_secs();
let backup_path = options.backup_dir.join(format!("p1-{epoch}.img"));
let device = &plan.partition.device;
// Hold the current p1 as root, then pull it over the unprivileged SSH
// session. The daemon channel is blind, so this two-step path is required.
let remote_backup = REMOTE_BACKUP;
remote.root_command(
&format!("dd if={device} of={remote_backup} bs=1M 2>&1; chmod 644 {remote_backup}"),
Duration::from_secs(180),
)?;
remote.pull(remote_backup, &backup_path, Duration::from_secs(240))?;
let _ = remote.root_command(&format!("rm -f {remote_backup}"), Duration::from_secs(15));
let backup_data = fs::read(&backup_path)?;
if backup_data.len() as u64 != plan.partition.size {
return Err(InstallError::BackupSize(backup_path));
}
let backup_md5 = md5_hex(&backup_data);
if report.live_md5 != "unreadable" && backup_md5 != report.live_md5 {
return Err(InstallError::BackupMismatch);
}
let backup_sha256: String = Sha256::digest(&backup_data)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect();
write_sidecars(
&backup_path,
&backup_md5,
&backup_sha256,
&plan.partition,
&plan.expected_sha256,
epoch,
)?;
stage_and_write(plan, remote, &backup_path)?;
let rebooted = if options.no_reboot {
false
} else {
remote.reboot()?;
true
};
Ok(InstallOutcome::Installed(InstallReceipt {
backup_path,
backup_md5,
backup_sha256,
image_md5: plan.expected_md5.clone(),
rebooted,
}))
}
fn stage_and_write(
plan: &Cv1835Plan,
remote: &mut dyn Remote,
backup_path: &Path,
) -> Result<(), InstallError> {
let mut staged =
tempfile::NamedTempFile::new_in(backup_path.parent().unwrap_or_else(|| Path::new(".")))?;
staged.write_all(&plan.data)?;
staged.flush()?;
remote.push(staged.path(), REMOTE_STAGE, Duration::from_secs(240))?;
let staged_md5 =
remote.root_command(&format!("md5sum {REMOTE_STAGE}"), Duration::from_secs(60))?;
let staged_md5 = String::from_utf8_lossy(&staged_md5)
.split_whitespace()
.next()
.unwrap_or("")
.to_ascii_lowercase();
if staged_md5 != plan.expected_md5 {
let _ = remote.root_command(&format!("rm -f {REMOTE_STAGE}"), Duration::from_secs(15));
return Err(InstallError::StageMismatch);
}
remote.root_command(
&format!(
"dd if={REMOTE_STAGE} of={} bs=1M conv=fsync 2>&1; sync",
plan.partition.device
),
Duration::from_secs(240),
)?;
let readback = remote.root_command(
&format!("md5sum {}", plan.partition.device),
Duration::from_secs(90),
)?;
let readback = String::from_utf8_lossy(&readback)
.split_whitespace()
.next()
.unwrap_or("")
.to_ascii_lowercase();
let _ = remote.root_command(&format!("rm -f {REMOTE_STAGE}"), Duration::from_secs(15));
if readback != plan.expected_md5 {
return Err(InstallError::Readback(restore_command(
&plan.partition.device,
backup_path,
)));
}
Ok(())
}
#[derive(Clone, Debug)]
pub struct RestoreOptions {
pub confirm: Option<String>,
pub no_reboot: bool,
}
#[derive(Clone, Debug)]
pub struct RestoreReceipt {
pub backup_path: PathBuf,
pub image_md5: String,
pub rebooted: bool,
}
pub fn restore(
backup: &Path,
remote: &mut dyn Remote,
options: &RestoreOptions,
) -> Result<RestoreReceipt, InstallError> {
if options.confirm.as_deref() != Some("FLASH") {
return Err(InstallError::Confirm);
}
let data = fs::read(backup)?;
if data.len() != 16 * 1024 * 1024 {
return Err(InstallError::BackupSize(backup.to_path_buf()));
}
let md5 = md5_hex(&data);
let sha256: String = Sha256::digest(&data)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect();
if let Some(sidecar) = read_sidecar(backup) {
if sidecar != sha256 {
return Err(InstallError::BackupMismatch);
}
}
let root_uid = String::from_utf8_lossy(&remote.root_command("id -u", Duration::from_secs(20))?)
.trim()
.to_owned();
if root_uid != "0" {
return Err(InstallError::Preflight(format!(
"root channel returned uid {root_uid}"
)));
}
let size = remote.user_command(
"cat /sys/class/block/mmcblk0p1/size 2>/dev/null || true",
Duration::from_secs(15),
)?;
let sectors: u64 = String::from_utf8_lossy(&size).trim().parse().unwrap_or(0);
if sectors.saturating_mul(512) != 16 * 1024 * 1024 {
return Err(InstallError::Preflight(
"the board does not expose a 16 MiB /dev/mmcblk0p1".to_owned(),
));
}
let staged = tempfile::NamedTempFile::new()?;
fs::write(staged.path(), &data)?;
remote.push(staged.path(), REMOTE_STAGE, Duration::from_secs(240))?;
let staged_md5 =
remote.root_command(&format!("md5sum {REMOTE_STAGE}"), Duration::from_secs(60))?;
let staged_md5 = String::from_utf8_lossy(&staged_md5)
.split_whitespace()
.next()
.unwrap_or("")
.to_ascii_lowercase();
if staged_md5 != md5 {
let _ = remote.root_command(&format!("rm -f {REMOTE_STAGE}"), Duration::from_secs(15));
return Err(InstallError::StageMismatch);
}
remote.root_command(
&format!("dd if={REMOTE_STAGE} of=/dev/mmcblk0p1 bs=1M conv=fsync 2>&1; sync"),
Duration::from_secs(240),
)?;
let readback = remote.root_command("md5sum /dev/mmcblk0p1", Duration::from_secs(90))?;
let readback = String::from_utf8_lossy(&readback)
.split_whitespace()
.next()
.unwrap_or("")
.to_ascii_lowercase();
let _ = remote.root_command(&format!("rm -f {REMOTE_STAGE}"), Duration::from_secs(15));
if readback != md5 {
return Err(InstallError::RestoreReadback);
}
let rebooted = if options.no_reboot {
false
} else {
remote.reboot()?;
true
};
Ok(RestoreReceipt {
backup_path: backup.to_path_buf(),
image_md5: md5,
rebooted,
})
}
fn restore_command(device: &str, backup: &Path) -> String {
format!(
"alkane-cli afw restore --host <ip> --held-backup {} --confirm FLASH (the held copy of {device} is at {})",
backup.display(),
backup.display()
)
}
fn default_backup_dir() -> PathBuf {
alkane_core::platform::config_path("backups")
}
fn write_sidecars(
path: &Path,
md5: &str,
sha256: &str,
partition: &alkane_artifacts::afw::AfwPartition,
image_sha256: &str,
epoch: u64,
) -> Result<(), InstallError> {
let file_name = path
.file_name()
.map(|name| name.to_string_lossy().into_owned())
.unwrap_or_else(|| "p1.img".to_owned());
fs::write(
path.with_extension("img.sha256"),
format!("{sha256} {file_name}\n"),
)?;
let metadata = serde_json::json!({
"board": "cv1835",
"partition": partition.name,
"device": partition.device,
"size": partition.size,
"md5": md5,
"sha256": sha256,
"afw_sha256": image_sha256,
"created_unix": epoch,
});
fs::write(
path.with_extension("img.json"),
serde_json::to_vec_pretty(&metadata).unwrap_or_default(),
)?;
Ok(())
}
fn read_sidecar(path: &Path) -> Option<String> {
let text = fs::read_to_string(path.with_extension("img.sha256")).ok()?;
text.split_whitespace().next().map(str::to_owned)
}
#[derive(Clone, Debug)]
pub struct LiveReport {
pub attempts: u32,
pub http: String,
pub http_ok: bool,
pub ssh: String,
pub ssh_ok: bool,
pub api: String,
pub api_ok: bool,
}
impl LiveReport {
pub fn ok(&self) -> bool {
self.http_ok && self.ssh_ok && self.api_ok
}
pub fn render(&self) -> String {
format!(
"verify-live attempts {}\n http {}: {}\n ssh {}: {}\n api {}: {}\nresult {}",
self.attempts,
if self.http_ok { "ok" } else { "FAIL" },
self.http,
if self.ssh_ok { "ok" } else { "FAIL" },
self.ssh,
if self.api_ok { "ok" } else { "FAIL" },
self.api,
if self.ok() { "PASS" } else { "FAIL" }
)
}
}
pub fn verify_live(
host: &str,
marker: &str,
kernel_version: &str,
timeout: Duration,
ssh_options: &SshOptions,
) -> LiveReport {
let deadline = Instant::now() + timeout;
let mut attempts = 0;
loop {
attempts += 1;
let (http, http_ok) = match http_get(host, "/", Duration::from_secs(5)) {
Ok(body) => {
let ok = body.contains(marker);
(
if ok {
format!("marker {marker} present")
} else {
format!("marker {marker} absent ({} bytes)", body.len())
},
ok,
)
}
Err(error) => (error, false),
};
let (ssh, ssh_ok) = match SshTransport::connect(ssh_options.clone(), false) {
Ok(mut session) => match session.user_command("uname -r", Duration::from_secs(15)) {
Ok(output) => {
let kernel = String::from_utf8_lossy(&output).trim().to_owned();
let ok = !kernel.is_empty()
&& (kernel_version.is_empty() || kernel.contains(kernel_version));
(
format!(
"kernel {kernel}{}",
if ok {
""
} else {
" (expected the installed kernel)"
}
),
ok,
)
}
Err(error) => (format!("{error}"), false),
},
Err(error) => (format!("{error}"), false),
};
let (api, api_ok) = match api_version(host, Duration::from_secs(5)) {
Ok(body) => {
let ok = body.contains("\"STATUS\"")
|| body.contains("\"VERSION\"")
|| body.to_lowercase().contains("version");
(format!("{} bytes", body.len()), ok)
}
Err(error) => (error, false),
};
if http_ok && ssh_ok && api_ok {
return LiveReport {
attempts,
http,
http_ok,
ssh,
ssh_ok,
api,
api_ok,
};
}
if Instant::now() >= deadline {
return LiveReport {
attempts,
http,
http_ok,
ssh,
ssh_ok,
api,
api_ok,
};
}
std::thread::sleep(Duration::from_secs(5));
}
}
pub(crate) fn http_get(host: &str, path: &str, timeout: Duration) -> Result<String, String> {
let address = (host, 80_u16)
.to_socket_addrs()
.map_err(|error| format!("resolve: {error}"))?
.next()
.ok_or_else(|| "no address".to_owned())?;
let mut stream = TcpStream::connect_timeout(&address, timeout)
.map_err(|error| format!("connect: {error}"))?;
stream
.set_read_timeout(Some(timeout))
.map_err(|error| error.to_string())?;
let request = format!("GET {path} HTTP/1.0\r\nHost: {host}\r\nConnection: close\r\n\r\n");
stream
.write_all(request.as_bytes())
.map_err(|error| error.to_string())?;
let mut data = Vec::new();
let mut buffer = [0_u8; 8192];
loop {
match stream.read(&mut buffer) {
Ok(0) => break,
Ok(read) => {
data.extend_from_slice(&buffer[..read]);
if data.len() > 512 * 1024 {
break;
}
}
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => break,
Err(error) if error.kind() == std::io::ErrorKind::TimedOut => break,
Err(error) => return Err(error.to_string()),
}
}
let text = String::from_utf8_lossy(&data).into_owned();
let status_ok = text
.lines()
.next()
.map(|line| line.contains(" 200 ") || line.ends_with(" 200"))
.unwrap_or(false);
if status_ok {
Ok(text)
} else {
Err(text.lines().next().unwrap_or("no HTTP response").to_owned())
}
}
pub(crate) fn api_version(host: &str, timeout: Duration) -> Result<String, String> {
let address = (host, 4028_u16)
.to_socket_addrs()
.map_err(|error| format!("resolve: {error}"))?
.next()
.ok_or_else(|| "no address".to_owned())?;
let mut stream = TcpStream::connect_timeout(&address, timeout)
.map_err(|error| format!("connect: {error}"))?;
stream
.set_read_timeout(Some(timeout))
.map_err(|error| error.to_string())?;
stream
.write_all(b"{\"command\":\"version\"}\n")
.map_err(|error| error.to_string())?;
let mut data = Vec::new();
let mut buffer = [0_u8; 4096];
loop {
match stream.read(&mut buffer) {
Ok(0) => break,
Ok(read) => {
data.extend_from_slice(&buffer[..read]);
if data.len() > 64 * 1024 {
break;
}
}
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => break,
Err(error) if error.kind() == std::io::ErrorKind::TimedOut => break,
Err(error) => return Err(error.to_string()),
}
}
let text = String::from_utf8_lossy(&data).trim().to_owned();
if text.is_empty() {
Err("no API response".to_owned())
} else {
Ok(text)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn derives_backup_sidecar_names() {
let path = Path::new("/tmp/p1-1.img");
assert_eq!(
path.with_extension("img.sha256"),
Path::new("/tmp/p1-1.img.sha256")
);
assert_eq!(
path.with_extension("img.json"),
Path::new("/tmp/p1-1.img.json")
);
}
#[test]
fn restore_command_names_the_held_copy() {
let command = restore_command("/dev/mmcblk0p1", Path::new("/tmp/p1.img"));
assert!(command.contains("afw restore"));
assert!(command.contains("/tmp/p1.img"));
}
}
#[cfg(test)]
mod network_tests {
use super::*;
use alkane_artifacts::afw::{AfwImage, AfwManifest, AfwMember, AfwPartition, BootloaderPolicy};
use serde_json::json;
use std::collections::HashMap;
const P1: usize = 16 * 1024 * 1024;
const REV: &str = "0000000000000000000000000000000000000000";
struct MockRemote {
partition: Vec<u8>,
files: HashMap<String, Vec<u8>>,
commands: Vec<String>,
rebooted: bool,
readback_corrupt: bool,
}
impl MockRemote {
fn new(partition: Vec<u8>) -> Self {
Self {
partition,
files: HashMap::new(),
commands: Vec::new(),
rebooted: false,
readback_corrupt: false,
}
}
fn md5(&self, data: &[u8]) -> String {
md5_hex(data)
}
}
impl Remote for MockRemote {
fn channel(&self) -> &str {
"mock"
}
fn root_method(&self) -> &'static str {
"direct"
}
fn user_command(
&mut self,
command: &str,
_timeout: Duration,
) -> Result<Vec<u8>, RemoteError> {
self.commands.push(command.to_owned());
let text = if command.contains("uname -r") {
"6.18.48\n__MODEL__\nAlkane CV1835\n__RELEASE__\nalkane\n".to_owned()
} else if command.contains("test -b") {
"block".to_owned()
} else if command.contains("/sys/class/block/mmcblk0p1/size") {
"32768".to_owned()
} else if command.contains("for c in dd") {
"dd\nmd5sum\nsync\n".to_owned()
} else if command.contains("df -k") {
"Filesystem 1K-blocks Used Available Use% Mounted on\n/dev/root 100000 1 90000 1% /tmp\n".to_owned()
} else if command.contains("mmcblk0boot0") {
"yes".to_owned()
} else {
String::new()
};
Ok(text.into_bytes())
}
fn root_command(
&mut self,
command: &str,
_timeout: Duration,
) -> Result<Vec<u8>, RemoteError> {
self.commands.push(command.to_owned());
if command.starts_with("id -u") || command == "id" {
return Ok(b"0\n".to_vec());
}
if let Some(rest) = command.strip_prefix("md5sum /dev/mmcblk0p1") {
let _ = rest;
let mut data = self.partition.clone();
if self.readback_corrupt && self.files.contains_key(REMOTE_STAGE) {
if let Some(last) = data.last_mut() {
*last ^= 0xff;
}
self.readback_corrupt = false;
}
return Ok(format!("{} /dev/mmcblk0p1\n", self.md5(&data)).into_bytes());
}
if let Some(rest) = command.strip_prefix("md5sum ") {
let path = rest.split_whitespace().next().unwrap_or("");
let data = self.files.get(path).cloned().unwrap_or_default();
return Ok(format!("{} {path}\n", self.md5(&data)).into_bytes());
}
if let Some(rest) = command.strip_prefix("dd if=") {
let mut parts = rest.splitn(2, " of=");
let source = parts.next().unwrap_or("");
let target = parts
.next()
.unwrap_or("")
.split_whitespace()
.next()
.unwrap_or("");
if source == "/dev/mmcblk0p1" {
self.files.insert(target.to_owned(), self.partition.clone());
} else if target == "/dev/mmcblk0p1" {
if let Some(data) = self.files.get(source).cloned() {
self.partition = data;
}
}
return Ok(Vec::new());
}
if command.starts_with("rm -f ") {
let path = command.trim_start_matches("rm -f ").trim();
self.files.remove(path);
return Ok(Vec::new());
}
Ok(Vec::new())
}
fn push(
&mut self,
local: &Path,
remote: &str,
_timeout: Duration,
) -> Result<(), RemoteError> {
self.files.insert(remote.to_owned(), fs::read(local)?);
Ok(())
}
fn pull(
&mut self,
remote: &str,
local: &Path,
_timeout: Duration,
) -> Result<(), RemoteError> {
let data = self
.files
.get(remote)
.cloned()
.ok_or_else(|| RemoteError::Daemon("missing file".to_owned()))?;
fs::write(local, data)?;
Ok(())
}
fn reboot(&mut self) -> Result<(), RemoteError> {
self.rebooted = true;
Ok(())
}
}
fn p1_image() -> Vec<u8> {
let mut fit = vec![0_u8; P1];
fit[..4].copy_from_slice(b"\xd0\x0d\xfe\xed");
let marker = b"config@cv1835_miner_emmc";
fit[0x100..0x100 + marker.len()].copy_from_slice(marker);
fit
}
fn verified(data: &[u8]) -> VerifiedAfw {
let manifest = AfwManifest {
schema: 2,
format: "afw".to_owned(),
board: "cv1835".to_owned(),
arch: "arm64".to_owned(),
version: "0.1.0".to_owned(),
build_date: "2026-11-04T00:00:00Z".to_owned(),
sdk_revision: REV.to_owned(),
os_revision: REV.to_owned(),
payload_type: "os".to_owned(),
bootloader_policy: BootloaderPolicy::Preserve,
signature: alkane_artifacts::afw::AfwSignature {
kind: "unsigned".to_owned(),
member: None,
public_key_hex: None,
},
partitions: vec![
AfwPartition {
name: "p1".to_owned(),
device: "/dev/mmcblk0p1".to_owned(),
offset: 0,
size: P1 as u64,
secure: false,
boot_critical: true,
write_order: 1,
image: Some("p1".to_owned()),
},
AfwPartition {
name: "boot0".to_owned(),
device: "/dev/mmcblk0boot0".to_owned(),
offset: 0,
size: 4 * 1024 * 1024,
secure: true,
boot_critical: true,
write_order: 0,
image: None,
},
],
images: vec![AfwImage {
name: "p1".to_owned(),
file: "payload/p1.fit".to_owned(),
role: "boot".to_owned(),
format: "fit".to_owned(),
size: P1 as u64,
sha256: Sha256::digest(data)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect(),
partition: Some("p1".to_owned()),
install: true,
}],
boot_switch: json!({"method": "partition-overwrite"}),
preflight: json!({"required_commands": ["dd", "md5sum", "sync"],
"source_os": ["stock-bitmain", "vnish", "braiins", "ouros", "alkane"],
"min_free_bytes": 33554432}),
recovery: json!({"network": "afw restore", "golden_lba_bytes": 0x300000u64 * 512}),
marker: "Alkane".to_owned(),
kernel_version: "6.18.48".to_owned(),
notes: None,
};
VerifiedAfw {
manifest,
members: vec![AfwMember {
name: "payload/p1.fit".to_owned(),
data: data.to_vec(),
}],
manifest_sha256: "0".repeat(64),
archive_sha256: "0".repeat(64),
}
}
#[test]
fn installs_p1_holds_a_backup_and_verifies_before_reboot() {
let original = vec![0x11_u8; P1];
let new = p1_image();
let afw = verified(&new);
let plan = Cv1835Plan::from_afw(&afw).unwrap();
let mut remote = MockRemote::new(original.clone());
let temp = tempfile::tempdir().unwrap();
let options = InstallOptions {
dry_run: false,
confirm: Some("FLASH".to_owned()),
no_reboot: true,
backup_dir: temp.path().to_path_buf(),
held_backup: None,
allow_unknown_source: true,
check_golden: false,
};
let outcome = install(&afw, &plan, &mut remote, &options, "10.255.1.1").unwrap();
let InstallOutcome::Installed(receipt) = outcome else {
panic!("expected an install");
};
assert_eq!(remote.partition, new);
assert_eq!(receipt.backup_md5, md5_hex(&original));
assert!(receipt.backup_path.is_file());
assert!(!remote.rebooted);
assert!(remote
.commands
.iter()
.any(|command| command.starts_with("dd if=/tmp/.alkane-p1-stage.img")));
}
#[test]
fn dry_run_never_writes_the_partition() {
let original = vec![0x22_u8; P1];
let new = p1_image();
let afw = verified(&new);
let plan = Cv1835Plan::from_afw(&afw).unwrap();
let mut remote = MockRemote::new(original.clone());
let temp = tempfile::tempdir().unwrap();
let options = InstallOptions {
dry_run: true,
confirm: None,
no_reboot: false,
backup_dir: temp.path().to_path_buf(),
held_backup: None,
allow_unknown_source: true,
check_golden: false,
};
let outcome = install(&afw, &plan, &mut remote, &options, "10.255.1.1").unwrap();
assert!(matches!(outcome, InstallOutcome::DryRun(_)));
assert_eq!(remote.partition, original);
assert!(!remote
.commands
.iter()
.any(|command| command.starts_with("dd if=/tmp/.alkane-p1-stage.img")));
}
#[test]
fn a_readback_mismatch_stops_before_reboot() {
let original = vec![0x33_u8; P1];
let new = p1_image();
let afw = verified(&new);
let plan = Cv1835Plan::from_afw(&afw).unwrap();
let mut remote = MockRemote::new(original);
remote.readback_corrupt = true;
let temp = tempfile::tempdir().unwrap();
let options = InstallOptions {
dry_run: false,
confirm: Some("FLASH".to_owned()),
no_reboot: false,
backup_dir: temp.path().to_path_buf(),
held_backup: None,
allow_unknown_source: true,
check_golden: false,
};
let result = install(&afw, &plan, &mut remote, &options, "10.255.1.1");
assert!(matches!(result, Err(InstallError::Readback(_))));
assert!(!remote.rebooted);
}
#[test]
fn confirm_is_required_before_any_device_write() {
let original = vec![0x44_u8; P1];
let new = p1_image();
let afw = verified(&new);
let plan = Cv1835Plan::from_afw(&afw).unwrap();
let mut remote = MockRemote::new(original.clone());
let temp = tempfile::tempdir().unwrap();
let options = InstallOptions {
dry_run: false,
confirm: None,
no_reboot: false,
backup_dir: temp.path().to_path_buf(),
held_backup: None,
allow_unknown_source: true,
check_golden: false,
};
let result = install(&afw, &plan, &mut remote, &options, "10.255.1.1");
assert!(matches!(result, Err(InstallError::Confirm)));
assert_eq!(remote.partition, original);
}
}
+32 -2
View File
@@ -1,6 +1,36 @@
// SPDX-License-Identifier: MIT
//! Guarded write sequence for a verified artifact and an SDK partition plan.
//! Board transport adapters must supply serial, recovery and readback evidence.
//! Guarded writes plus the network-only CV1835 installer.
//!
//! The original guarded-write helpers remain for boards that need an attached
//! recovery channel. CV1835 uses the network modules below: a verified `.afw`,
//! a board plan, an SSH transport with a stock-root stage, a read-only
//! preflight, a whole-partition read-back and a network restore.
// The board modules are driven by static NAND/partition map tables (tuples) and
// multi-field hardware write functions; the two style lints below are design
// choices for this crate rather than defects.
#![allow(clippy::type_complexity, clippy::too_many_arguments)]
pub mod boards;
pub mod install;
pub mod md5;
pub mod preflight;
pub mod stock;
pub mod stock_firmware;
// Network-only stock-crossing method bodies compiled into the toolkit; the
// public interface lives in `stock`. See stock_method.rs. This module is
// maintained as a self-contained unit; the style lints below are allowed here so
// its internal layout is not churned to satisfy them.
#[allow(
clippy::needless_range_loop,
clippy::type_complexity,
clippy::too_many_arguments,
clippy::manual_repeat_n,
clippy::manual_is_multiple_of,
clippy::unnecessary_map_or
)]
mod stock_method;
pub mod transport;
use alkane_artifacts::VerifiedArtifact;
use sha2::{Digest, Sha256};
+116
View File
@@ -0,0 +1,116 @@
// SPDX-License-Identifier: MIT
//! MD5 for the CV1835 whole-partition read-back.
//!
//! The stock busybox on this board ships `md5sum` but not `sha256sum`, and the
//! proven installer gates the write on a whole-partition md5. This module is a
//! small RFC 1321 implementation so the host can compare the same digest
//! without shelling out to a tool that may not exist.
const S: [u32; 64] = [
7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 7, 12, 17, 22, 5, 9, 14, 20, 5, 9, 14, 20, 5, 9,
14, 20, 5, 9, 14, 20, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 4, 11, 16, 23, 6, 10, 15,
21, 6, 10, 15, 21, 6, 10, 15, 21, 6, 10, 15, 21,
];
const K: [u32; 64] = [
0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, 0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501,
0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be, 0x6b901122, 0xfd987193, 0xa679438e, 0x49b40821,
0xf61e2562, 0xc040b340, 0x265e5a51, 0xe9b6c7aa, 0xd62f105d, 0x02441453, 0xd8a1e681, 0xe7d3fbc8,
0x21e1cde6, 0xc33707d6, 0xf4d50d87, 0x455a14ed, 0xa9e3e905, 0xfcefa3f8, 0x676f02d9, 0x8d2a4c8a,
0xfffa3942, 0x8771f681, 0x6d9d6122, 0xfde5380c, 0xa4beea44, 0x4bdecfa9, 0xf6bb4b60, 0xbebfbc70,
0x289b7ec6, 0xeaa127fa, 0xd4ef3085, 0x04881d05, 0xd9d4d039, 0xe6db99e5, 0x1fa27cf8, 0xc4ac5665,
0xf4292244, 0x432aff97, 0xab9423a7, 0xfc93a039, 0x655b59c3, 0x8f0ccc92, 0xffeff47d, 0x85845dd1,
0x6fa87e4f, 0xfe2ce6e0, 0xa3014314, 0x4e0811a1, 0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391,
];
pub fn md5(data: &[u8]) -> [u8; 16] {
let mut state = [0x67452301_u32, 0xefcdab89, 0x98badcfe, 0x10325476];
let bit_length = (data.len() as u64).wrapping_mul(8);
let mut message = data.to_vec();
message.push(0x80);
while message.len() % 64 != 56 {
message.push(0);
}
message.extend_from_slice(&bit_length.to_le_bytes());
for chunk in message.chunks_exact(64) {
let mut words = [0_u32; 16];
for (index, word) in words.iter_mut().enumerate() {
let start = index * 4;
*word = u32::from_le_bytes([
chunk[start],
chunk[start + 1],
chunk[start + 2],
chunk[start + 3],
]);
}
let [mut a, mut b, mut c, mut d] = state;
for index in 0..64 {
let (f, g) = match index {
0..=15 => ((b & c) | (!b & d), index),
16..=31 => ((d & b) | (!d & c), (5 * index + 1) % 16),
32..=47 => (b ^ c ^ d, (3 * index + 5) % 16),
_ => (c ^ (b | !d), (7 * index) % 16),
};
let rotated = a
.wrapping_add(f)
.wrapping_add(K[index])
.wrapping_add(words[g])
.rotate_left(S[index]);
a = d;
d = c;
c = b;
b = b.wrapping_add(rotated);
}
state[0] = state[0].wrapping_add(a);
state[1] = state[1].wrapping_add(b);
state[2] = state[2].wrapping_add(c);
state[3] = state[3].wrapping_add(d);
}
let mut digest = [0_u8; 16];
for (index, word) in state.iter().enumerate() {
digest[index * 4..index * 4 + 4].copy_from_slice(&word.to_le_bytes());
}
digest
}
pub fn md5_hex(data: &[u8]) -> String {
md5(data).iter().map(|byte| format!("{byte:02x}")).collect()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rfc1321_vectors() {
assert_eq!(md5_hex(b""), "d41d8cd98f00b204e9800998ecf8427e");
assert_eq!(md5_hex(b"a"), "0cc175b9c0f1b6a831c399e269772661");
assert_eq!(md5_hex(b"abc"), "900150983cd24fb0d6963f7d28e17f72");
assert_eq!(
md5_hex(b"message digest"),
"f96b697d7cb7938d525a2f31aaf161d0"
);
assert_eq!(
md5_hex(b"abcdefghijklmnopqrstuvwxyz"),
"c3fcd3d76192e4007dfb496cca67e13b"
);
assert_eq!(
md5_hex(b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"),
"d174ab98d277d9f5a5611c2c9f419d9f"
);
assert_eq!(
md5_hex(
b"12345678901234567890123456789012345678901234567890123456789012345678901234567890"
),
"57edf4a22be3c955ac49da2e2107b67a"
);
}
#[test]
fn handles_a_block_boundary() {
let data = vec![0x42_u8; 64];
assert_eq!(md5_hex(&data), "8e558437ffca99de04c18a63b55a4fad");
}
}
+420
View File
@@ -0,0 +1,420 @@
// SPDX-License-Identifier: MIT
//! Read-only CV1835 preflight: source-OS fingerprint, root channel, partition
//! identity, held/golden backup hashes, free space and secure-region refusal.
//!
//! Every check runs over the network. A failure is reported, never repaired.
use crate::boards::cv1835::{Cv1835Plan, CvPlanError};
use crate::md5::md5_hex;
use crate::transport::{Remote, RemoteError};
use sha2::{Digest, Sha256};
use std::fs;
use std::path::{Path, PathBuf};
use std::time::Duration;
use thiserror::Error;
const P1_NAME: &str = "mmcblk0p1";
#[derive(Debug, Error)]
pub enum PreflightError {
#[error("preflight transport: {0}")]
Remote(#[from] RemoteError),
#[error("preflight I/O: {0}")]
Io(#[from] std::io::Error),
#[error("preflight plan: {0}")]
Plan(#[from] CvPlanError),
#[error("held backup {path} is {size} bytes, not 16 MiB")]
BackupSize { path: PathBuf, size: u64 },
#[error("held backup {0} has no readable md5")]
BackupUnreadable(PathBuf),
}
#[derive(Clone, Debug)]
pub struct Check {
pub name: &'static str,
pub ok: bool,
pub detail: String,
}
#[derive(Clone, Debug)]
pub struct BackupCheck {
pub path: PathBuf,
pub md5: String,
pub sha256: String,
pub matches_live: bool,
}
#[derive(Clone, Debug)]
pub struct PreflightReport {
pub host: String,
pub source_os: String,
pub kernel: String,
pub model: String,
pub root_method: String,
pub root_uid: String,
pub partition_device: String,
pub partition_size: u64,
pub live_md5: String,
pub held_backup: Option<BackupCheck>,
pub golden_md5: Option<String>,
pub free_bytes: u64,
pub boot0_present: bool,
pub checks: Vec<Check>,
}
impl PreflightReport {
pub fn ok(&self) -> bool {
self.checks.iter().all(|check| check.ok)
}
pub fn failures(&self) -> Vec<&Check> {
self.checks.iter().filter(|check| !check.ok).collect()
}
pub fn render(&self) -> String {
let mut out = String::new();
out.push_str(&format!("preflight {}\n", self.host));
out.push_str(&format!(
"source-os {} (kernel {})\n",
self.source_os, self.kernel
));
if !self.model.is_empty() {
out.push_str(&format!("model {}\n", self.model));
}
out.push_str(&format!(
"root {} (uid {})\n",
self.root_method, self.root_uid
));
out.push_str(&format!(
"partition {} {} B\n",
self.partition_device, self.partition_size
));
out.push_str(&format!("live p1 md5 {}\n", self.live_md5));
match &self.held_backup {
Some(backup) => out.push_str(&format!(
"held backup {} md5 {} ({})\n",
backup.path.display(),
backup.md5,
if backup.matches_live {
"matches live p1"
} else {
"differs from live p1"
}
)),
None => out.push_str("held backup none (install will create one before writing)\n"),
}
if let Some(golden) = &self.golden_md5 {
out.push_str(&format!("golden raw p1 md5 {golden}\n"));
}
out.push_str(&format!(
"free tmp {} MiB\n",
self.free_bytes / (1024 * 1024)
));
out.push_str(&format!(
"boot0 {} (never written)\n",
if self.boot0_present {
"present"
} else {
"not present"
}
));
for check in &self.checks {
out.push_str(&format!(
"check {} {}: {}\n",
check.name,
if check.ok { "ok" } else { "FAIL" },
check.detail
));
}
out.push_str(if self.ok() {
"result PASS\n"
} else {
"result FAIL (do not write)\n"
});
out
}
}
pub struct PreflightOptions<'a> {
pub host: &'a str,
pub held_backup: Option<&'a Path>,
pub check_golden: bool,
pub allow_unknown_source: bool,
}
pub fn preflight(
plan: &Cv1835Plan,
remote: &mut dyn Remote,
options: &PreflightOptions<'_>,
) -> Result<PreflightReport, PreflightError> {
let mut checks = Vec::new();
let fingerprint = remote.user_command(
"uname -r; echo __MODEL__; cat /proc/device-tree/model 2>/dev/null; echo; \
echo __RELEASE__; cat /etc/os-release 2>/dev/null; \
ls /etc/bos_version /etc/fw-info /etc/alkane-release /etc/ouros-release 2>/dev/null; \
test -x /nvdata/rroot && echo rroot; \
test -x /usr/sbin/update-daemon && echo update-daemon",
Duration::from_secs(20),
)?;
let text = String::from_utf8_lossy(&fingerprint).into_owned();
let mut sections = text.split("__MODEL__");
let kernel = sections.next().unwrap_or("").trim().to_owned();
let rest = sections.next().unwrap_or("");
let mut sections = rest.split("__RELEASE__");
let model = sections.next().unwrap_or("").trim().to_owned();
let release = sections.next().unwrap_or("");
let source_os = classify(&kernel, release, &text);
let source_ok = plan.source_os.is_empty()
|| plan.source_os.iter().any(|item| item == &source_os)
|| options.allow_unknown_source;
checks.push(Check {
name: "source-os",
ok: source_ok,
detail: format!(
"{source_os} (allowed: {})",
if plan.source_os.is_empty() {
"any".to_owned()
} else {
plan.source_os.join(", ")
}
),
});
let root_uid = String::from_utf8_lossy(&remote.root_command("id -u", Duration::from_secs(20))?)
.trim()
.to_owned();
checks.push(Check {
name: "root",
ok: root_uid == "0",
detail: format!("uid {root_uid}"),
});
let partition_device = plan.partition.device.clone();
let block = String::from_utf8_lossy(&remote.user_command(
&format!("test -b {partition_device} && echo block || echo missing"),
Duration::from_secs(15),
)?)
.trim()
.to_owned();
let size_out = remote.user_command(
&format!("cat /sys/class/block/{P1_NAME}/size 2>/dev/null || true"),
Duration::from_secs(15),
)?;
let sectors: u64 = String::from_utf8_lossy(&size_out)
.trim()
.parse()
.unwrap_or(0);
let partition_size = sectors.saturating_mul(512);
checks.push(Check {
name: "partition",
ok: block == "block" && partition_size == plan.partition.size,
detail: format!(
"{partition_device} {partition_size} B (plan {} B)",
plan.partition.size
),
});
let live = remote.root_command(
&format!("md5sum {partition_device}"),
Duration::from_secs(60),
)?;
let live_md5 = parse_digest(&live, 32).unwrap_or_else(|| "unreadable".to_owned());
checks.push(Check {
name: "live-p1-md5",
ok: live_md5.len() == 32,
detail: live_md5.clone(),
});
let commands = remote.user_command(
"for c in dd md5sum sync; do command -v $c >/dev/null 2>&1 && echo $c || echo missing:$c; done",
Duration::from_secs(15),
)?;
let commands_text = String::from_utf8_lossy(&commands).into_owned();
let missing: Vec<&str> = commands_text
.lines()
.filter_map(|line| line.strip_prefix("missing:"))
.collect();
checks.push(Check {
name: "commands",
ok: missing.is_empty(),
detail: if missing.is_empty() {
"dd, md5sum, sync present".to_owned()
} else {
format!("missing {}", missing.join(", "))
},
});
let free_bytes = free_bytes(remote)?;
checks.push(Check {
name: "free-space",
ok: free_bytes >= plan.min_free_bytes,
detail: format!(
"{} MiB at /tmp (plan {} MiB)",
free_bytes / (1024 * 1024),
plan.min_free_bytes / (1024 * 1024)
),
});
let boot0 = String::from_utf8_lossy(&remote.user_command(
"test -e /dev/mmcblk0boot0 && echo yes || echo no",
Duration::from_secs(15),
)?)
.trim()
.to_owned();
let boot0_present = boot0 == "yes";
checks.push(Check {
name: "secure-regions",
ok: !plan.partition.device.contains("boot0"),
detail: format!(
"boot0 {}; the write plan targets only {}",
if boot0_present { "present" } else { "absent" },
plan.partition.device
),
});
let mut held_backup = None;
if let Some(path) = options.held_backup {
let size = fs::metadata(path)?.len();
if size != plan.partition.size {
return Err(PreflightError::BackupSize {
path: path.to_path_buf(),
size,
});
}
let data = fs::read(path)?;
let md5 = md5_hex(&data);
let sha256: String = Sha256::digest(&data)
.iter()
.map(|byte| format!("{byte:02x}"))
.collect();
let matches_live = md5 == live_md5;
checks.push(Check {
name: "held-backup",
ok: true,
detail: format!(
"{} md5 {md5} ({})",
path.display(),
if matches_live {
"matches live p1"
} else {
"differs from live p1; restore will still write it"
}
),
});
held_backup = Some(BackupCheck {
path: path.to_path_buf(),
md5,
sha256,
matches_live,
});
}
let mut golden_md5 = None;
if options.check_golden {
let out = remote.root_command(
&format!(
"dd if=/dev/mmcblk0 skip={} count=32768 bs=512 2>/dev/null | md5sum",
plan.golden_lba_bytes / 512
),
Duration::from_secs(90),
)?;
if let Some(digest) = parse_digest(&out, 32) {
golden_md5 = Some(digest);
}
}
Ok(PreflightReport {
host: options.host.to_owned(),
source_os,
kernel,
model,
root_method: remote.root_method().to_owned(),
root_uid,
partition_device,
partition_size,
live_md5,
held_backup,
golden_md5,
free_bytes,
boot0_present,
checks,
})
}
pub(crate) fn classify(kernel: &str, release: &str, all: &str) -> String {
if all.contains("/etc/bos_version") || release.contains("Braiins") {
return "braiins".to_owned();
}
if all.contains("/etc/alkane-release") || kernel.starts_with("6.18") {
return "alkane".to_owned();
}
if all.contains("/etc/ouros-release") || kernel.contains("6.6.147") {
return "ouros".to_owned();
}
if all.contains("/etc/fw-info") || release.contains("Vnish") || release.contains("AnthillOS") {
return "vnish".to_owned();
}
// Stock Bitmain control boards: Amlogic stock is kernel 4.9.38; the AM335x
// (BeagleBone-class) stock is kernel 3.8.13+ with an "Antminer" model line.
if kernel.contains("4.9.38")
|| kernel.starts_with("3.8.13")
|| all.contains("update-daemon")
|| all.contains("rroot")
|| all.to_lowercase().contains("antminer")
{
return "stock-bitmain".to_owned();
}
"unknown".to_owned()
}
pub fn parse_digest(output: &[u8], length: usize) -> Option<String> {
let text = String::from_utf8_lossy(output);
text.split_whitespace()
.map(|token| token.trim().to_ascii_lowercase())
.find(|token| token.len() == length && token.bytes().all(|byte| byte.is_ascii_hexdigit()))
}
fn free_bytes(remote: &mut dyn Remote) -> Result<u64, RemoteError> {
let out = remote.user_command("df -k /tmp 2>/dev/null || df -k /", Duration::from_secs(15))?;
let text = String::from_utf8_lossy(&out);
for line in text.lines().rev() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() >= 4 {
if let Ok(kib) = fields[3].parse::<u64>() {
return Ok(kib.saturating_mul(1024));
}
}
}
Ok(0)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn classifies_the_source_os() {
assert_eq!(
classify("4.9.38-tag-", "", "update-daemon\n"),
"stock-bitmain"
);
assert_eq!(
classify("4.9.38-tag-", "/etc/fw-info\n", "/etc/fw-info\n"),
"vnish"
);
assert_eq!(classify("6.6.147", "/etc/ouros-release\n", ""), "ouros");
assert_eq!(classify("6.18.48", "", ""), "alkane");
assert_eq!(classify("4.9.38", "", "/etc/bos_version\n"), "braiins");
assert_eq!(classify("5.10.0", "", ""), "unknown");
}
#[test]
fn parses_md5_from_md5sum_output() {
let output = b"3f43804f10ce256200bfc71e7fbdd9ee /dev/mmcblk0p1\n";
assert_eq!(
parse_digest(output, 32).as_deref(),
Some("3f43804f10ce256200bfc71e7fbdd9ee")
);
assert_eq!(parse_digest(b"not a digest\n", 32), None);
}
}
+222
View File
@@ -0,0 +1,222 @@
// SPDX-License-Identifier: MIT
//! Stock <-> alkane crossing, compiled into the toolkit.
//!
//! The toolkit is self-contained: it installs alkane onto a board on stock and
//! returns a board to stock entirely on its own, with no external helper and no
//! runtime dependency on any other tool. A user's machine needs only this
//! binary.
//!
//! Getting our first image onto a board past its stock safeguards (with root),
//! and the reverse, are implemented in the sibling module `stock_method`. This
//! file is the stable public boundary around that work: the interface
//! (`StockMethod`, `StockError`) plus the toolkit-side orchestration and
//! verification around the method. The method is plain Rust and must be
//! network-only.
use alkane_artifacts::afw::VerifiedAfw;
use std::path::{Path, PathBuf};
use thiserror::Error;
#[derive(Debug, Error)]
pub enum StockError {
#[error("the stock method is not implemented in this build")]
NotImplemented,
#[error("could not reach the board: {0}")]
Network(String),
#[error("authentication failed: {0}")]
Auth(String),
#[error("the stock method failed: {0}")]
Method(String),
#[error("io: {0}")]
Io(String),
}
/// The genuine Bitmain stock kernel and rootfs to write back when restoring to
/// stock, parsed from a vendor firmware package (OTA or SD) by `stock_firmware`.
/// The matching NAND device tree is NOT taken from the package: Bitmain never
/// ships the kernel device tree in its distributable firmware (it is factory-
/// provisioned and preserved by every update), so the method supplies the
/// correct per-board dtb itself. Borrowed so the large rootfs is not copied
/// before the method needs it.
pub struct RestoreImages<'a> {
pub kernel: &'a [u8],
pub rootfs: &'a [u8],
}
/// Options for updating a board that already runs alkane, in place.
#[derive(Clone, Debug, Default)]
pub struct InPlaceOptions {
/// Read-only: report the board state, the storage map and the write plan,
/// and write nothing.
pub dry_run: bool,
/// Reboot after the images are written and read back, then wait for the
/// board to return as alkane.
pub reboot: bool,
/// Where to keep a copy of each boot slot as it was before the write. When
/// set, every slot is read and saved before any erase; a failed backup
/// aborts the update with nothing written.
pub backup_dir: Option<PathBuf>,
}
/// One boot slot as it was before an in-place update.
#[derive(Clone, Debug)]
pub struct HeldSlot {
pub name: String,
/// Absolute NAND offset of the slot.
pub absolute: u64,
pub size: u64,
pub path: PathBuf,
pub md5: String,
}
#[derive(Clone, Debug)]
pub struct InPlaceReceipt {
pub backups: Vec<HeldSlot>,
pub rebooted: bool,
}
#[derive(Clone, Debug)]
pub enum InPlaceOutcome {
/// The dry-run report; nothing was written.
DryRun(String),
Updated(InPlaceReceipt),
}
/// Result of a live check that a Zynq board is up on alkane: two channels
/// (HTTP page marker, SSH kernel/OS) must agree.
#[derive(Clone, Debug)]
pub struct LiveCheck {
pub attempts: u32,
pub http: String,
pub http_ok: bool,
pub ssh: String,
pub ssh_ok: bool,
/// The running kernel command line (informational: on a NAND boot it is
/// the board's U-Boot env bootargs).
pub cmdline: String,
}
impl LiveCheck {
pub fn ok(&self) -> bool {
self.http_ok && self.ssh_ok
}
pub fn render(&self) -> String {
format!(
"verify-live attempts {}\n http {}: {}\n ssh {}: {}\n cmdline: {}\nresult {}\n",
self.attempts,
if self.http_ok { "PASS" } else { "FAIL" },
self.http,
if self.ssh_ok { "PASS" } else { "FAIL" },
self.ssh,
if self.cmdline.is_empty() {
"(not read)"
} else {
&self.cmdline
},
if self.ok() { "PASS" } else { "FAIL" }
)
}
}
/// The stock-side methods, implemented by `stock_method`. All implementations
/// must be NETWORK-ONLY (no serial-console dependency).
pub trait StockMethod {
/// Put our first image (the `.afw`) onto a board currently on stock, past
/// stock's gates and with root, over the network only. On Ok the board is
/// installed with alkane; the caller verifies liveness.
fn install_from_stock(
&self,
host: &str,
afw_path: &Path,
afw: &VerifiedAfw,
password: Option<&str>,
) -> Result<(), StockError>;
/// Return an aftermarket (alkane) board to genuine stock, over the network
/// only, by writing the given genuine Bitmain stock images (`images`) back to
/// NAND. `password` is the board's alkane root credential. On Ok the board is
/// on stock; the caller verifies.
fn restore_to_stock(
&self,
host: &str,
images: &RestoreImages,
password: Option<&str>,
) -> Result<(), StockError>;
/// Update a board that already runs alkane to the `.afw`'s images, over the
/// network only. Refuses a board that is not running alkane (a board on
/// stock is installed with `install_from_stock`). The boot regions are not
/// exposed to Linux on alkane, so they are re-registered the same way as for
/// a restore; the images are written in the form the board's stock U-Boot
/// boots, each read back before reboot, and BOOT.bin is never written.
fn update_in_place(
&self,
host: &str,
afw: &VerifiedAfw,
password: Option<&str>,
options: &InPlaceOptions,
) -> Result<InPlaceOutcome, StockError>;
}
/// The compiled-in method implementation.
pub fn method() -> &'static dyn StockMethod {
crate::stock_method::method()
}
/// Install alkane onto a board on stock (network-only), via the compiled-in method.
pub fn install_from_stock(
host: &str,
afw_path: &Path,
afw: &VerifiedAfw,
password: Option<&str>,
) -> Result<(), StockError> {
method().install_from_stock(host, afw_path, afw, password)
}
/// Return an alkane board to stock (network-only) by writing the genuine Bitmain
/// stock `images` back to NAND, via the compiled-in method.
pub fn restore_to_stock(
host: &str,
images: &RestoreImages,
password: Option<&str>,
) -> Result<(), StockError> {
method().restore_to_stock(host, images, password)
}
/// Check, over the network, that a Zynq board is up on alkane: the web page
/// carries `marker` (case-insensitive) and SSH reports alkane with a kernel
/// containing `kernel_version` (if non-empty). Retries until `timeout`.
pub fn verify_zynq_live(
host: &str,
password: Option<&str>,
marker: &str,
kernel_version: &str,
timeout: std::time::Duration,
) -> Result<LiveCheck, StockError> {
crate::stock_method::live_check(host, password, marker, kernel_version, timeout)
}
/// Update a board already on alkane to the `.afw`'s images, in place
/// (network-only), via the compiled-in method.
pub fn update_in_place(
host: &str,
afw: &VerifiedAfw,
password: Option<&str>,
options: &InPlaceOptions,
) -> Result<InPlaceOutcome, StockError> {
method().update_in_place(host, afw, password, options)
}
#[cfg(test)]
mod tests {
use super::*;
// The interface is exercised against whatever `stock_method` provides. We
// only assert the toolkit wires a method object in; its behaviour is the
// method module's own tests.
#[test]
fn a_method_is_compiled_in() {
let _m: &dyn StockMethod = method();
}
}
+282
View File
@@ -0,0 +1,282 @@
// SPDX-License-Identifier: MIT
//! Parse a genuine Bitmain Antminer stock firmware package into the flashable
//! stock images, so the toolkit can restore a board to genuine stock using the
//! vendor's own files (no carved blobs).
//!
//! Two genuine source shapes are handled for the Zynq-7010 (Antminer S17):
//!
//! - OTA update `.tar.gz` (`Antminer-S17-user-OM-<date>-sig*.tar.gz`): a signed
//! outer tar holding `cert.pem`, `fw.tar.gz` and `runme.sh` (each with a
//! `.sig`). The inner `fw.tar.gz` holds `BOOT.bin`, `uImage` (legacy kernel),
//! `uramdisk.image.gz` (rootfs) and `md5_info` (md5 of the rootfs). The OTA
//! package does NOT carry the device tree: the factory SD provisioning writes
//! it once and OTA upgrades preserve it.
//! - SD recovery `.zip` (`SD_Antminer-S17-*.zip`): the full factory image,
//! which DOES include `devicetree.dtb` alongside `BOOT.bin`/`uImage`/
//! `uramdisk.image.gz`. This is the complete source for a from-anywhere
//! restore, because it carries the device tree the stock kernel needs.
//!
//! Extraction shells out to the system `tar`/`unzip`/`gzip` (as the release
//! fetch shells out to `curl`); nothing is written outside a private temp dir.
use std::path::Path;
use std::process::Command;
use crate::md5::md5_hex;
#[derive(Debug, thiserror::Error)]
pub enum StockFirmwareError {
#[error("io: {0}")]
Io(String),
#[error("could not read {0}")]
Read(String),
#[error("unrecognised firmware package (not a .tar.gz or .zip): {0}")]
Format(String),
#[error("extraction failed: {0}")]
Extract(String),
#[error("the firmware package is missing a stock {0} image")]
MissingImage(&'static str),
#[error("rootfs md5 mismatch: package lists {expected}, image is {actual}")]
RootfsMd5 { expected: String, actual: String },
#[error("needed system tool not found: {0}")]
MissingTool(String),
}
/// The stock images carved from a genuine Bitmain firmware package, ready to
/// write back to NAND. `boot_bin` and `dtb` are optional (an OTA package omits
/// the dtb; the bootloader is only written on an explicit full restore).
pub struct StockFirmware {
pub boot_bin: Option<Vec<u8>>,
pub dtb: Option<Vec<u8>>,
pub kernel: Vec<u8>,
pub rootfs: Vec<u8>,
pub version: Option<String>,
/// The source package kind, for logging.
pub source_kind: &'static str,
}
impl StockFirmware {
pub fn summary(&self) -> String {
let v = self.version.as_deref().unwrap_or("unknown");
format!(
"{} (version {}): kernel {} B, rootfs {} B, dtb {}, BOOT.bin {}",
self.source_kind,
v,
self.kernel.len(),
self.rootfs.len(),
self.dtb.as_ref().map_or("absent", |_| "present"),
self.boot_bin.as_ref().map_or("absent", |_| "present"),
)
}
}
fn have_tool(tool: &str) -> bool {
Command::new(tool)
.arg("--version")
.output()
.map(|o| o.status.success() || !o.stdout.is_empty() || !o.stderr.is_empty())
.unwrap_or(false)
}
fn run(cmd: &mut Command, what: &str) -> Result<(), StockFirmwareError> {
let out = cmd
.output()
.map_err(|e| StockFirmwareError::Extract(format!("{what}: {e}")))?;
if !out.status.success() {
return Err(StockFirmwareError::Extract(format!(
"{what}: {}",
String::from_utf8_lossy(&out.stderr).trim()
)));
}
Ok(())
}
/// Recursively collect files under `dir` as (relative-path-lowercased, absolute path).
fn collect_files(dir: &Path) -> Vec<(String, std::path::PathBuf)> {
fn walk(base: &Path, dir: &Path, out: &mut Vec<(String, std::path::PathBuf)>) {
let Ok(entries) = std::fs::read_dir(dir) else {
return;
};
for entry in entries.flatten() {
let path = entry.path();
if path.is_dir() {
walk(base, &path, out);
} else if let Ok(rel) = path.strip_prefix(base) {
out.push((rel.to_string_lossy().to_lowercase(), path.clone()));
}
}
}
let mut out = Vec::new();
walk(dir, dir, &mut out);
out
}
/// Pick the best file whose basename matches `name`, preferring paths that
/// contain one of `prefer` path fragments (e.g. "bin/" for the SD image, "fw"
/// for the OTA inner tree), then the shallowest path.
fn pick<'a>(
files: &'a [(String, std::path::PathBuf)],
name: &str,
prefer: &[&str],
) -> Option<&'a std::path::PathBuf> {
let name = name.to_lowercase();
let mut matches: Vec<&(String, std::path::PathBuf)> = files
.iter()
.filter(|(rel, _)| rel.rsplit('/').next() == Some(name.as_str()) || *rel == name)
.collect();
if matches.is_empty() {
return None;
}
matches.sort_by_key(|(rel, _)| {
let pref_rank = prefer
.iter()
.position(|p| rel.contains(p))
.unwrap_or(prefer.len());
let depth = rel.matches('/').count();
(pref_rank, depth)
});
matches.first().map(|(_, p)| p)
}
fn read(path: &Path) -> Result<Vec<u8>, StockFirmwareError> {
std::fs::read(path).map_err(|_| StockFirmwareError::Read(path.display().to_string()))
}
/// Parse a genuine Bitmain stock firmware package (OTA `.tar.gz` or SD `.zip`)
/// into its stock images.
pub fn parse(path: &Path) -> Result<StockFirmware, StockFirmwareError> {
let bytes = std::fs::read(path)
.map_err(|e| StockFirmwareError::Io(format!("{}: {e}", path.display())))?;
if bytes.len() < 4 {
return Err(StockFirmwareError::Format(path.display().to_string()));
}
let is_gzip = bytes[0] == 0x1f && bytes[1] == 0x8b;
let is_zip = &bytes[0..2] == b"PK";
if !is_gzip && !is_zip {
return Err(StockFirmwareError::Format(path.display().to_string()));
}
let tmp = tempfile::Builder::new()
.prefix("alkane-stockfw-")
.tempdir()
.map_err(|e| StockFirmwareError::Io(e.to_string()))?;
let root = tmp.path();
let (source_kind, prefer): (&'static str, &[&str]) = if is_zip {
if !have_tool("unzip") {
return Err(StockFirmwareError::MissingTool("unzip".into()));
}
run(
Command::new("unzip")
.arg("-qq")
.arg("-o")
.arg(path)
.arg("-d")
.arg(root),
"unzip SD recovery image",
)?;
("Bitmain SD recovery image", &["bin/"])
} else {
if !have_tool("tar") {
return Err(StockFirmwareError::MissingTool("tar".into()));
}
run(
Command::new("tar").arg("xzf").arg(path).arg("-C").arg(root),
"untar OTA package",
)?;
// The signed OTA wraps the real images in an inner fw.tar.gz; extract it.
let inner = collect_files(root)
.into_iter()
.find(|(rel, _)| rel.rsplit('/').next() == Some("fw.tar.gz"));
if let Some((_, inner_path)) = inner {
let inner_dir = root.join("fw");
std::fs::create_dir_all(&inner_dir)
.map_err(|e| StockFirmwareError::Io(e.to_string()))?;
run(
Command::new("tar")
.arg("xzf")
.arg(&inner_path)
.arg("-C")
.arg(&inner_dir),
"untar OTA inner fw.tar.gz",
)?;
}
("Bitmain OTA update package", &["fw/", "bin/"])
};
let files = collect_files(root);
let kernel_path = pick(&files, "uImage", prefer)
.ok_or(StockFirmwareError::MissingImage("uImage (kernel)"))?;
let rootfs_path = pick(&files, "uramdisk.image.gz", prefer).ok_or(
StockFirmwareError::MissingImage("uramdisk.image.gz (rootfs)"),
)?;
let kernel = read(kernel_path)?;
let rootfs = read(rootfs_path)?;
let boot_bin = pick(&files, "BOOT.bin", prefer)
.map(|p| read(p))
.transpose()?;
let dtb = pick(&files, "devicetree.dtb", &["", "bin/"])
.map(|p| read(p))
.transpose()?;
// Verify the rootfs against md5_info when the package ships one (OTA does).
if let Some(md5_path) = pick(&files, "md5_info", prefer) {
if let Ok(raw) = std::fs::read_to_string(md5_path) {
let expected = raw.split_whitespace().next().unwrap_or("").to_lowercase();
if expected.len() == 32 {
let actual = md5_hex(&rootfs);
if actual != expected {
return Err(StockFirmwareError::RootfsMd5 { expected, actual });
}
}
}
}
let version = pick(&files, "version", prefer)
.or_else(|| pick(&files, "version_number", &[""]))
.and_then(|p| std::fs::read_to_string(p).ok())
.map(|s| s.trim().to_string())
.filter(|s| !s.is_empty());
Ok(StockFirmware {
boot_bin,
dtb,
kernel,
rootfs,
version,
source_kind,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn rejects_non_archive() {
let tmp = tempfile::NamedTempFile::new().unwrap();
std::fs::write(tmp.path(), b"not an archive").unwrap();
assert!(matches!(
parse(tmp.path()),
Err(StockFirmwareError::Format(_))
));
}
// Parse a real Bitmain firmware package. Set ALKANE_TEST_STOCK_FW to its path.
// Ignored by default (needs the vendor file, not in the repo).
#[test]
#[ignore]
fn parses_real_package() {
let Ok(path) = std::env::var("ALKANE_TEST_STOCK_FW") else {
eprintln!("set ALKANE_TEST_STOCK_FW to a firmware file");
return;
};
let fw = parse(Path::new(&path)).expect("parse");
eprintln!("{}", fw.summary());
assert!(!fw.kernel.is_empty(), "kernel present");
assert!(!fw.rootfs.is_empty(), "rootfs present");
// The kernel is a legacy u-boot uImage: magic 0x27051956 big-endian.
assert_eq!(&fw.kernel[0..4], &[0x27, 0x05, 0x19, 0x56], "uImage magic");
}
}
File diff suppressed because it is too large Load Diff
+699
View File
@@ -0,0 +1,699 @@
// SPDX-License-Identifier: MIT
//! Network transport for the CV1835 installer.
//!
//! Two root channels are implemented, both over the network:
//!
//! * `direct`: the SSH login is already uid 0 (Braiins OS, ourOS/alkane with a
//! root key, or an operator-supplied root login).
//! * `update-daemon`: stock Bitmain (and Vnish, which runs on the stock
//! kernel) exposes an SSH login as `miner` (uid 1001). `/usr/sbin/update-daemon`
//! listens on 127.0.0.1:12887 and pipes its socket into `system()` as root.
//! We reach it through an SSH local forward, exactly as documented in the RE
//! notes (`cv-kvm-host` / `cvbuild/cvroot.py`,
//! `alkane-sdk-wiki/40-boot-os-and-build/cross-install-matrix.md`). The
//! channel is blind, so root output is redirected to a world-readable file
//! and read back over the unprivileged SSH session.
//! * `rroot`: an existing `/nvdata/rroot` setuid helper on CV stock/Vnish,
//! documented in `60-reverse-engineering-methods/rroot-setuid-escalation.md`.
//! It is a fallback because the helper is not durable across a p7 reformat.
//!
//! Credentials are never read here: a password is used only through
//! `sshpass -f <path>`, and that path comes from the operator (environment
//! variable materialized by the CLI, or a file named on the command line).
use std::fs;
use std::io::{Read, Write};
use std::net::{SocketAddr, TcpStream};
use std::path::{Path, PathBuf};
use std::process::{Child, Command, ExitStatus, Stdio};
use std::thread;
use std::time::{Duration, Instant};
use thiserror::Error;
const MAX_CAPTURE: usize = 64 * 1024 * 1024;
#[derive(Debug, Error)]
pub enum RemoteError {
#[error("remote I/O: {0}")]
Io(#[from] std::io::Error),
#[error("cannot start {0}")]
MissingTool(&'static str),
#[error("invalid target: {0}")]
InvalidTarget(String),
#[error("SSH transport: {0}")]
Ssh(String),
#[error("SSH command timed out after {0:?}")]
Timeout(Duration),
#[error("remote command failed ({status}): {stderr}")]
Command { status: String, stderr: String },
#[error("root access was not obtained: {0}")]
NotRoot(String),
#[error("no network root channel is available on this board")]
NoRootMethod,
#[error("update-daemon: {0}")]
Daemon(String),
#[error("remote output is over the {0}-byte cap")]
OutputTooLarge(usize),
}
impl RemoteError {
fn sanitize(text: &str) -> String {
let text = text.trim();
let mut shortened: String = text.chars().take(300).collect();
if shortened.len() < text.len() {
shortened.push_str("...");
}
shortened
}
}
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum RootMethod {
Auto,
Direct,
UpdateDaemon,
Rroot,
}
impl RootMethod {
pub fn parse(value: &str) -> Option<Self> {
match value {
"auto" => Some(Self::Auto),
"direct" => Some(Self::Direct),
"update-daemon" => Some(Self::UpdateDaemon),
"rroot" => Some(Self::Rroot),
_ => None,
}
}
}
#[derive(Clone, Debug)]
pub struct SshOptions {
pub host: String,
pub port: u16,
pub user: String,
pub identity_file: Option<PathBuf>,
pub password_file: Option<PathBuf>,
pub known_hosts: Option<PathBuf>,
pub root_method: RootMethod,
pub update_daemon_port: Option<u16>,
}
impl Default for SshOptions {
fn default() -> Self {
Self {
host: String::new(),
port: 22,
user: "miner".to_owned(),
identity_file: None,
password_file: None,
known_hosts: None,
root_method: RootMethod::Auto,
update_daemon_port: None,
}
}
}
impl SshOptions {
fn validate(&self) -> Result<(), RemoteError> {
if self.host.is_empty()
|| self.host.len() > 253
|| self.host.starts_with('-')
|| !self.host.bytes().all(|byte| {
byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-' | b':' | b'_')
})
{
return Err(RemoteError::InvalidTarget("host".to_owned()));
}
if self.user.is_empty()
|| !self
.user
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'_' | b'-' | b'.'))
{
return Err(RemoteError::InvalidTarget("user".to_owned()));
}
if self.port == 0 {
return Err(RemoteError::InvalidTarget("port".to_owned()));
}
if let Some(path) = &self.password_file {
if !path.is_file() {
return Err(RemoteError::InvalidTarget(format!(
"password file not found: {}",
path.display()
)));
}
}
Ok(())
}
}
enum Strategy {
Direct,
Rroot,
UpdateDaemon {
local_port: u16,
remote_port: u16,
tunnel: Child,
},
}
impl Drop for Strategy {
fn drop(&mut self) {
if let Self::UpdateDaemon { tunnel, .. } = self {
let _ = tunnel.kill();
let _ = tunnel.wait();
}
}
}
pub struct SshTransport {
options: SshOptions,
known_hosts: PathBuf,
strategy: Strategy,
counter: u64,
}
impl SshTransport {
/// Open a session and (when `require_root`) prove a uid-0 channel.
pub fn connect(options: SshOptions, require_root: bool) -> Result<Self, RemoteError> {
options.validate()?;
let known_hosts = options
.known_hosts
.clone()
.unwrap_or_else(|| alkane_core::platform::config_path("known_hosts"));
if let Some(parent) = known_hosts.parent() {
fs::create_dir_all(parent)?;
}
if !known_hosts.exists() {
fs::write(&known_hosts, b"")?;
}
if options.password_file.is_some() {
Command::new("sshpass")
.arg("-V")
.stdout(Stdio::null())
.stderr(Stdio::null())
.status()
.map_err(|_| RemoteError::MissingTool("sshpass"))?;
}
let mut transport = Self {
options,
known_hosts,
strategy: Strategy::Direct,
counter: 0,
};
let identity = transport.user_command("uname -r", Duration::from_secs(15))?;
let _ = identity;
if !require_root {
return Ok(transport);
}
let uid =
String::from_utf8_lossy(&transport.user_command("id -u", Duration::from_secs(15))?)
.trim()
.to_owned();
let direct = uid == "0";
let method = match transport.options.root_method {
RootMethod::Auto if direct => RootMethod::Direct,
RootMethod::Auto => {
if transport.has_update_daemon()? {
RootMethod::UpdateDaemon
} else if transport.has_rroot()? {
RootMethod::Rroot
} else {
return Err(RemoteError::NoRootMethod);
}
}
other => other,
};
match method {
RootMethod::Direct => {
if !direct {
return Err(RemoteError::NotRoot(
"the SSH login is not uid 0; use --root-method auto, update-daemon or rroot"
.to_owned(),
));
}
transport.strategy = Strategy::Direct;
}
RootMethod::Rroot => {
if !transport.has_rroot()? {
return Err(RemoteError::NotRoot(
"/nvdata/rroot is not present or not executable".to_owned(),
));
}
transport.strategy = Strategy::Rroot;
}
RootMethod::UpdateDaemon => {
if !transport.has_update_daemon()? {
return Err(RemoteError::NotRoot(
"/usr/sbin/update-daemon is not present".to_owned(),
));
}
let remote_port = transport
.options
.update_daemon_port
.unwrap_or(transport.detect_update_daemon_port()?);
let (local_port, tunnel) = transport.start_tunnel(remote_port)?;
transport.strategy = Strategy::UpdateDaemon {
local_port,
remote_port,
tunnel,
};
}
RootMethod::Auto => unreachable!(),
}
let root_output = transport.root_command("id", Duration::from_secs(20))?;
let root = String::from_utf8_lossy(&root_output);
if !root.contains("uid=0") {
return Err(RemoteError::NotRoot(
"the selected channel did not return uid=0".to_owned(),
));
}
Ok(transport)
}
pub fn channel(&self) -> String {
format!("ssh:{}@{}", self.options.user, self.options.host)
}
pub fn root_method(&self) -> &'static str {
match &self.strategy {
Strategy::Direct => "direct",
Strategy::Rroot => "rroot",
Strategy::UpdateDaemon { .. } => "update-daemon",
}
}
pub fn update_daemon_port(&self) -> Option<u16> {
match &self.strategy {
Strategy::UpdateDaemon { remote_port, .. } => Some(*remote_port),
_ => None,
}
}
fn ssh_base(&self) -> Command {
let mut command = if let Some(password) = &self.options.password_file {
let mut command = Command::new("sshpass");
command.arg("-f").arg(password).arg("ssh");
command
} else {
Command::new("ssh")
};
command
.arg("-F")
.arg("none")
.arg("-o")
.arg(if self.options.password_file.is_some() {
"BatchMode=no"
} else {
"BatchMode=yes"
})
.arg("-o")
.arg("StrictHostKeyChecking=accept-new")
.arg("-o")
.arg(format!("UserKnownHostsFile={}", self.known_hosts.display()))
.arg("-o")
.arg("GlobalKnownHostsFile=/dev/null")
.arg("-o")
.arg("ConnectTimeout=10")
.arg("-o")
.arg("ServerAliveInterval=5")
.arg("-o")
.arg("ServerAliveCountMax=3")
.arg("-o")
.arg("RequestTTY=no")
.arg("-o")
.arg("LogLevel=ERROR")
.arg("-o")
.arg("NumberOfPasswordPrompts=1")
.arg("-o")
.arg("PreferredAuthentications=publickey,password,keyboard-interactive");
if let Some(identity) = &self.options.identity_file {
command
.arg("-i")
.arg(identity)
.arg("-o")
.arg("IdentitiesOnly=yes");
}
command
}
fn ssh_command(&self, command: &str) -> Command {
let mut child = self.ssh_base();
child
.arg("-p")
.arg(self.options.port.to_string())
.arg(format!("{}@{}", self.options.user, self.options.host))
.arg(command);
child
}
fn run_user(&self, command: &str, timeout: Duration) -> Result<Vec<u8>, RemoteError> {
let (stdout, stderr, status) = run_bounded(self.ssh_command(command), timeout)?;
if !status.success() {
return Err(RemoteError::Command {
status: status.to_string(),
stderr: RemoteError::sanitize(&String::from_utf8_lossy(&stderr)),
});
}
Ok(stdout)
}
fn has_rroot(&self) -> Result<bool, RemoteError> {
let out = self.run_user(
"test -x /nvdata/rroot && echo yes || echo no",
Duration::from_secs(15),
)?;
Ok(String::from_utf8_lossy(&out).contains("yes"))
}
fn has_update_daemon(&self) -> Result<bool, RemoteError> {
let out = self.run_user(
"test -x /usr/sbin/update-daemon && echo yes || echo no",
Duration::from_secs(15),
)?;
Ok(String::from_utf8_lossy(&out).contains("yes"))
}
fn detect_update_daemon_port(&self) -> Result<u16, RemoteError> {
let out = self.run_user(
"cat /proc/net/tcp /proc/net/tcp6 2>/dev/null || true",
Duration::from_secs(15),
)?;
let text = String::from_utf8_lossy(&out);
for line in text.lines() {
let fields: Vec<&str> = line.split_whitespace().collect();
if fields.len() < 4 || fields[3] != "0A" {
continue;
}
let local = fields[1];
let port = local.rsplit(':').next().unwrap_or("");
let port = u16::from_str_radix(port, 16).unwrap_or(0);
if port == 12887 || port == 22026 {
return Ok(port);
}
}
// The CV1835 stock build listens on 12887. The fallback keeps the
// explicit --update-daemon-port option available for other builds.
Ok(12887)
}
fn start_tunnel(&self, remote_port: u16) -> Result<(u16, Child), RemoteError> {
let listener = std::net::TcpListener::bind(("127.0.0.1", 0))?;
let local_port = listener.local_addr()?.port();
drop(listener);
let mut command = self.ssh_base();
command
.arg("-N")
.arg("-o")
.arg("ExitOnForwardFailure=yes")
.arg("-L")
.arg(format!("127.0.0.1:{local_port}:127.0.0.1:{remote_port}"))
.arg("-p")
.arg(self.options.port.to_string())
.arg(format!("{}@{}", self.options.user, self.options.host))
.stdin(Stdio::null())
.stdout(Stdio::null())
.stderr(Stdio::null());
let mut tunnel = command.spawn()?;
let deadline = Instant::now() + Duration::from_secs(20);
loop {
if TcpStream::connect_timeout(
&SocketAddr::from(([127, 0, 0, 1], local_port)),
Duration::from_millis(500),
)
.is_ok()
{
return Ok((local_port, tunnel));
}
if let Some(status) = tunnel.try_wait()? {
return Err(RemoteError::Daemon(format!(
"SSH forward exited before it was ready ({status})"
)));
}
if Instant::now() >= deadline {
let _ = tunnel.kill();
return Err(RemoteError::Daemon(
"SSH forward did not become ready".to_owned(),
));
}
thread::sleep(Duration::from_millis(250));
}
}
fn daemon_send(&self, command: &str) -> Result<(), RemoteError> {
let Strategy::UpdateDaemon { local_port, .. } = &self.strategy else {
return Err(RemoteError::Daemon("not using update-daemon".to_owned()));
};
let local_port = *local_port;
if command.contains('\n') || command.contains('\r') {
return Err(RemoteError::Daemon("command contains a newline".to_owned()));
}
let mut stream = TcpStream::connect_timeout(
&SocketAddr::from(([127, 0, 0, 1], local_port)),
Duration::from_secs(10),
)?;
stream.set_write_timeout(Some(Duration::from_secs(10)))?;
stream.write_all(format!(";{command};").as_bytes())?;
stream.flush()?;
let _ = stream.set_read_timeout(Some(Duration::from_millis(500)));
let mut sink = [0_u8; 256];
let _ = stream.read(&mut sink);
Ok(())
}
fn daemon_capture(&mut self, command: &str, timeout: Duration) -> Result<Vec<u8>, RemoteError> {
let path = format!("/tmp/.alkane-root-{}-{}", std::process::id(), self.counter);
self.counter += 1;
let wrapped = format!("{{ {command} ; }} > {path} 2>&1; chmod 644 {path}");
self.daemon_send(&wrapped)?;
let deadline = Instant::now() + timeout;
loop {
let probe = format!("test -f {path} && echo ready || true");
let out = self.run_user(&probe, Duration::from_secs(15))?;
if String::from_utf8_lossy(&out).contains("ready") {
break;
}
if Instant::now() >= deadline {
return Err(RemoteError::Daemon(format!(
"root command produced no output file within {timeout:?}"
)));
}
thread::sleep(Duration::from_millis(200));
}
let output = self.run_user(&format!("cat {path}"), Duration::from_secs(60))?;
let _ = self.run_user(&format!("rm -f {path}"), Duration::from_secs(15));
Ok(output)
}
fn daemon_reboot(&mut self) -> Result<(), RemoteError> {
self.daemon_send("sync; echo b > /proc/sysrq-trigger")
}
}
impl Remote for SshTransport {
fn channel(&self) -> &str {
"ssh"
}
fn root_method(&self) -> &'static str {
SshTransport::root_method(self)
}
fn user_command(&mut self, command: &str, timeout: Duration) -> Result<Vec<u8>, RemoteError> {
self.run_user(command, timeout)
}
fn root_command(&mut self, command: &str, timeout: Duration) -> Result<Vec<u8>, RemoteError> {
match self.root_method() {
"direct" => self.run_user(command, timeout),
"rroot" => {
let wrapped = format!("/nvdata/rroot -c {}", shell_quote(command));
self.run_user(&wrapped, timeout)
}
"update-daemon" => self.daemon_capture(command, timeout),
_ => Err(RemoteError::NoRootMethod),
}
}
fn push(&mut self, local: &Path, remote: &str, timeout: Duration) -> Result<(), RemoteError> {
let remote = safe_remote_path(remote)?;
let mut command = self.ssh_command(&format!("cat > {remote}"));
command
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::piped());
let mut child = command.spawn()?;
let mut stdin = child.stdin.take().expect("piped stdin");
let path = local.to_path_buf();
let writer = thread::spawn(move || -> std::io::Result<()> {
let mut source = fs::File::open(path)?;
let mut buffer = [0_u8; 64 * 1024];
loop {
let read = source.read(&mut buffer)?;
if read == 0 {
break;
}
stdin.write_all(&buffer[..read])?;
}
stdin.flush()
});
let (stdout, stderr) = read_pipes(&mut child);
let status = wait_timeout(&mut child, timeout)?;
let _ = writer.join();
let _ = stdout.join();
let stderr = stderr.join().unwrap_or_default();
if !status.success() {
return Err(RemoteError::Command {
status: status.to_string(),
stderr: RemoteError::sanitize(&String::from_utf8_lossy(&stderr)),
});
}
Ok(())
}
fn pull(&mut self, remote: &str, local: &Path, timeout: Duration) -> Result<(), RemoteError> {
let remote = safe_remote_path(remote)?;
let data = self.run_user(&format!("cat {remote}"), timeout)?;
if data.len() > MAX_CAPTURE {
return Err(RemoteError::OutputTooLarge(MAX_CAPTURE));
}
fs::write(local, data)?;
Ok(())
}
fn reboot(&mut self) -> Result<(), RemoteError> {
match self.root_method() {
"update-daemon" => self.daemon_reboot(),
_ => {
// A successful sysrq reset drops the SSH connection mid-command.
let _ = self.run_user(
"sync; echo b > /proc/sysrq-trigger",
Duration::from_secs(15),
);
Ok(())
}
}
}
}
pub trait Remote {
fn channel(&self) -> &str;
fn root_method(&self) -> &'static str {
"network"
}
fn user_command(&mut self, command: &str, timeout: Duration) -> Result<Vec<u8>, RemoteError>;
fn root_command(&mut self, command: &str, timeout: Duration) -> Result<Vec<u8>, RemoteError>;
fn push(&mut self, local: &Path, remote: &str, timeout: Duration) -> Result<(), RemoteError>;
fn pull(&mut self, remote: &str, local: &Path, timeout: Duration) -> Result<(), RemoteError>;
fn reboot(&mut self) -> Result<(), RemoteError>;
}
pub fn shell_quote(text: &str) -> String {
format!("'{}'", text.replace('\'', "'\\''"))
}
pub fn safe_remote_path(path: &str) -> Result<&str, RemoteError> {
if !path.starts_with('/')
|| path.len() > 200
|| path.contains("..")
|| !path
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'/' | b'.' | b'_' | b'-'))
{
return Err(RemoteError::InvalidTarget(format!(
"unsafe remote path: {path}"
)));
}
Ok(path)
}
fn read_pipes(child: &mut Child) -> (thread::JoinHandle<Vec<u8>>, thread::JoinHandle<Vec<u8>>) {
let mut stdout = child.stdout.take().expect("piped stdout");
let mut stderr = child.stderr.take().expect("piped stderr");
let out = thread::spawn(move || {
let mut data = Vec::new();
let _ = stdout.read_to_end(&mut data);
data
});
let err = thread::spawn(move || {
let mut data = Vec::new();
let _ = stderr.read_to_end(&mut data);
data
});
(out, err)
}
fn wait_timeout(child: &mut Child, timeout: Duration) -> Result<ExitStatus, RemoteError> {
let deadline = Instant::now() + timeout;
loop {
if let Some(status) = child.try_wait()? {
return Ok(status);
}
if Instant::now() >= deadline {
let _ = child.kill();
let _ = child.wait();
return Err(RemoteError::Timeout(timeout));
}
thread::sleep(Duration::from_millis(20));
}
}
fn run_bounded(
mut command: Command,
timeout: Duration,
) -> Result<(Vec<u8>, Vec<u8>, ExitStatus), RemoteError> {
command
.stdin(Stdio::null())
.stdout(Stdio::piped())
.stderr(Stdio::piped());
let mut child = command.spawn()?;
let (stdout, stderr) = read_pipes(&mut child);
let status = wait_timeout(&mut child, timeout)?;
let stdout = stdout.join().unwrap_or_default();
let stderr = stderr.join().unwrap_or_default();
if stdout.len() > MAX_CAPTURE {
return Err(RemoteError::OutputTooLarge(MAX_CAPTURE));
}
Ok((stdout, stderr, status))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn quotes_shell_arguments_for_rroot() {
assert_eq!(shell_quote("id"), "'id'");
assert_eq!(shell_quote("echo 'x'"), "'echo '\\''x'\\'''");
}
#[test]
fn rejects_option_injection_and_unsafe_paths() {
let mut options = SshOptions {
host: "-oProxyCommand=bad".to_owned(),
user: "root".to_owned(),
..SshOptions::default()
};
assert!(options.validate().is_err());
options.host = "10.255.1.167".to_owned();
options.user = "root;id".to_owned();
assert!(options.validate().is_err());
assert!(safe_remote_path("/tmp/ok.img").is_ok());
assert!(safe_remote_path("relative").is_err());
assert!(safe_remote_path("/tmp/../etc/passwd").is_err());
assert!(safe_remote_path("/tmp/a;b").is_err());
}
#[test]
fn parses_root_methods() {
assert_eq!(RootMethod::parse("auto"), Some(RootMethod::Auto));
assert_eq!(
RootMethod::parse("update-daemon"),
Some(RootMethod::UpdateDaemon)
);
assert_eq!(RootMethod::parse("serial"), None);
}
}
+5
View File
@@ -11,6 +11,11 @@ path = "src/main.rs"
[dependencies]
alkane-core = { path = "../alkane-core" }
alkane-discovery = { path = "../alkane-discovery" }
# The self-contained stock <-> alkane engine (compiled-in method) and the .afw
# verify/fetch, so the GUI can install-from-stock and restore-to-stock and scan
# alkane-os releases through the same code paths the CLI uses.
alkane-flash = { path = "../alkane-flash" }
alkane-artifacts = { path = "../alkane-artifacts" }
# vendored + patched wx-rs (see vendor/wx-rs/patches/)
wx-rs = { path = "../../thirdparty/wx-rs/wx-rs-0.2.0-patched" }
asic-rs = "0.8.1"
+305
View File
@@ -0,0 +1,305 @@
//! Boards running Alkane OS on the network, and which alkane-os actions apply to
//! a scanned row.
//!
//! asic-rs recognises miners by their cgminer socket (:4028) or a vendor web UI.
//! A board running Alkane OS keeps its cgminer-compatible socket on loopback and
//! serves its own console, so asic-rs reports nothing at that address and the
//! board never appeared in the fleet. This probe finds it over plain HTTP:
//! - `GET /api/identity` (alkane-os 0.1.2 and later): os, os_version, board,
//! sdk_revision, hostname, mac, kernel;
//! - otherwise the cgminer-style `GET /api/summary`, whose STATUS Description
//! is "alkane-os" (earlier images: found, but the board family is unknown).
//!
//! Both endpoints are public and read-only on the board.
use crate::model::MinerRow;
use serde_json::{json, Value};
use std::net::IpAddr;
use std::time::Duration;
/// Firmware family shown for a board running Alkane OS.
pub const FIRMWARE: &str = "Alkane";
const CONNECT_TIMEOUT: Duration = Duration::from_secs(2);
const READ_TIMEOUT: Duration = Duration::from_secs(4);
const MAX_RESPONSE: usize = 64 * 1024;
/// Probe `ip` for Alkane OS. Returns a row for the fleet table, or None when the
/// address is not an Alkane board (or does not answer on :80).
pub async fn detect(ip: IpAddr) -> Option<MinerRow> {
if let Some(doc) = get_json(ip, "/api/identity").await {
if doc.get("os").and_then(Value::as_str) == Some("alkane-os") {
return Some(row_from_identity(ip, &doc));
}
}
let summary = get_json(ip, "/api/summary").await?;
if is_alkane_summary(&summary) {
return Some(row_from_identity(ip, &json!({})));
}
None
}
/// The cgminer-style summary an Alkane board serves names "alkane-os" in its
/// STATUS Description.
fn is_alkane_summary(doc: &Value) -> bool {
doc.get("STATUS")
.and_then(Value::as_array)
.and_then(|status| status.first())
.and_then(|entry| entry.get("Description"))
.and_then(Value::as_str)
== Some("alkane-os")
}
/// Control-board labels (cpu, code) for an Alkane board family, matching the
/// labels the scan gives the same board on stock firmware.
fn board_labels(board: &str) -> (&'static str, &'static str) {
match board {
"zynq-7010" => ("XIL", "C49"),
"am335x" => ("BBB", "C77"),
"cv1835" => ("CVI", "C88"),
"a113d" => ("AML", "C76"),
_ => ("", ""),
}
}
fn row_from_identity(ip: IpAddr, doc: &Value) -> MinerRow {
let text = |key: &str| {
doc.get(key)
.and_then(Value::as_str)
.unwrap_or("")
.trim()
.to_string()
};
let board = text("board");
let (cpu, code) = board_labels(&board);
let control_board = if cpu.is_empty() {
board.clone()
} else {
format!("{cpu} ({code})")
};
MinerRow {
ip: ip.to_string(),
// The Alkane-supported control boards are all Bitmain (Antminer) boards.
brand: if cpu.is_empty() {
String::new()
} else {
"Antminer".to_string()
},
firmware: FIRMWARE.to_string(),
fw_version: text("os_version"),
api_version: "alkane-os".to_string(),
mac: text("mac"),
hostname: text("hostname"),
control_board,
cpu: cpu.to_string(),
board_code: code.to_string(),
alkane_board: Some(board),
..Default::default()
}
}
/// HTTP/1.0 GET on :80 returning the JSON body of a 200 reply.
async fn get_json(ip: IpAddr, path: &str) -> Option<Value> {
use tokio::io::{AsyncReadExt, AsyncWriteExt};
let connect = tokio::net::TcpStream::connect((ip, 80));
let mut stream = tokio::time::timeout(CONNECT_TIMEOUT, connect)
.await
.ok()?
.ok()?;
let request = format!("GET {path} HTTP/1.0\r\nHost: {ip}\r\nConnection: close\r\n\r\n");
stream.write_all(request.as_bytes()).await.ok()?;
let mut raw = Vec::new();
let _ = tokio::time::timeout(READ_TIMEOUT, async {
let mut chunk = [0u8; 4096];
loop {
match stream.read(&mut chunk).await {
Ok(0) | Err(_) => break,
Ok(n) => {
raw.extend_from_slice(&chunk[..n]);
if raw.len() > MAX_RESPONSE {
break;
}
}
}
}
})
.await;
parse_http_json(&raw)
}
fn parse_http_json(raw: &[u8]) -> Option<Value> {
let text = std::str::from_utf8(raw).ok()?;
let (head, body) = text.split_once("\r\n\r\n")?;
let status = head.lines().next()?;
if status.split_whitespace().nth(1) != Some("200") {
return None;
}
serde_json::from_str(body.trim()).ok()
}
/// Whether the row is a board running Alkane OS (found by `detect`).
pub fn is_alkane(row: &MinerRow) -> bool {
row.alkane_board.is_some()
}
/// The alkane-os board family the row's control board is, when it can be told:
/// what an Alkane board reports, or for a stock Antminer the Zynq-7010 (S17/T17
/// era, "XIL (C49)") control board.
pub fn board_family(row: &MinerRow) -> Option<String> {
if let Some(board) = &row.alkane_board {
return (!board.is_empty()).then(|| board.clone());
}
if !row.brand.to_ascii_lowercase().contains("antminer") {
return None;
}
if row.cpu == "XIL" && row.board_code == "C49" {
return Some("zynq-7010".to_string());
}
// A stock S17 whose miner software is down (no hashboards attached: it
// restart-loops) reports its model but no control board. Its model then
// decides; a control board that IS reported always wins above.
if row.cpu.is_empty() && is_zynq_7010_model(&row.model) {
return Some("zynq-7010".to_string());
}
None
}
/// Stock models built only on the Zynq-7010 (XIL C49) control board.
fn is_zynq_7010_model(model: &str) -> bool {
matches!(model.trim(), "S17" | "S17 Pro" | "T17")
}
/// Whether alkane-os can be installed on the row's board: its control board is
/// one the toolkit supports.
pub fn install_supported(row: &MinerRow) -> bool {
board_family(row).is_some_and(|board| crate::stock_ops::is_supported_board(&board))
}
#[cfg(test)]
mod tests {
use super::*;
fn ip() -> IpAddr {
"10.0.0.5".parse().unwrap()
}
#[test]
fn parses_a_200_json_reply_only() {
let ok = b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\n\r\n{\"os\":\"alkane-os\"}";
assert_eq!(parse_http_json(ok).unwrap()["os"], "alkane-os");
let denied = b"HTTP/1.1 401 Unauthorized\r\n\r\n{\"os\":\"alkane-os\"}";
assert!(parse_http_json(denied).is_none());
let html = b"HTTP/1.1 200 OK\r\n\r\n<!DOCTYPE html><title>x</title>";
assert!(parse_http_json(html).is_none());
assert!(parse_http_json(b"garbage").is_none());
}
#[test]
fn recognises_the_alkane_summary() {
let alkane = json!({"STATUS":[{"Code":0,"Description":"alkane-os","STATUS":"S"}]});
assert!(is_alkane_summary(&alkane));
let cgminer = json!({"STATUS":[{"Description":"cgminer 4.11.1","STATUS":"S"}]});
assert!(!is_alkane_summary(&cgminer));
assert!(!is_alkane_summary(&json!({})));
}
#[test]
fn identity_becomes_a_supported_alkane_row() {
let doc = json!({
"os": "alkane-os", "os_version": "0.1.2", "board": "zynq-7010",
"sdk_revision": "6a9080ac82c1", "hostname": "alkane-zynq",
"mac": "26:4e:52:8b:e2:48", "kernel": "6.18.48",
});
let row = row_from_identity(ip(), &doc);
assert_eq!(row.ip, "10.0.0.5");
assert_eq!(row.firmware, "Alkane");
assert_eq!(row.fw_version, "0.1.2");
assert_eq!(row.control_board, "XIL (C49)");
assert_eq!(row.mac, "26:4e:52:8b:e2:48");
assert!(is_alkane(&row));
assert!(install_supported(&row));
}
#[test]
fn an_old_alkane_board_is_alkane_but_its_family_is_unknown() {
// Found via /api/summary only: uninstall applies, install cannot be
// confirmed as supported.
let row = row_from_identity(ip(), &json!({}));
assert!(is_alkane(&row));
assert_eq!(board_family(&row), None);
assert!(!install_supported(&row));
}
#[test]
fn stock_antminers_are_supported_only_on_the_zynq_7010_board() {
let stock = |cpu: &str, code: &str| MinerRow {
brand: "Antminer".into(),
firmware: "Stock".into(),
cpu: cpu.into(),
board_code: code.into(),
..Default::default()
};
let s17 = stock("XIL", "C49");
assert!(install_supported(&s17));
assert!(!is_alkane(&s17));
assert!(!install_supported(&stock("XIL", "C55"))); // S19-era Zynq
assert!(!install_supported(&stock("AML", "C76")));
assert!(!install_supported(&stock("", "")));
let whatsminer = MinerRow {
brand: "WhatsMiner".into(),
cpu: "XIL".into(),
board_code: "C49".into(),
..Default::default()
};
assert!(!install_supported(&whatsminer));
}
#[test]
fn a_stock_s17_without_a_reported_control_board_is_supported_by_model() {
// As seen live: stock S17, miner software down, control board blank.
let s17 = MinerRow {
brand: "Antminer".into(),
model: "S17".into(),
firmware: "Stock".into(),
..Default::default()
};
assert!(install_supported(&s17));
let other = |model: &str| MinerRow {
brand: "Antminer".into(),
model: model.into(),
..Default::default()
};
assert!(install_supported(&other("S17 Pro")));
assert!(install_supported(&other("T17")));
assert!(!install_supported(&other("S19")));
assert!(!install_supported(&other("S17+")));
assert!(!install_supported(&other("")));
// A reported control board overrides the model.
let s17_on_aml = MinerRow {
brand: "Antminer".into(),
model: "S17".into(),
cpu: "AML".into(),
board_code: "C76".into(),
..Default::default()
};
assert!(!install_supported(&s17_on_aml));
}
/// Live check against a real board:
/// `ALKANE_TEST_IP=10.255.1.111 cargo test -p alkane-gui live_detect -- --ignored --nocapture`
#[test]
#[ignore = "needs a board on the network (ALKANE_TEST_IP)"]
fn live_detect() {
let Ok(ip) = std::env::var("ALKANE_TEST_IP") else {
return;
};
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
.build()
.unwrap();
let row = rt.block_on(detect(ip.parse().unwrap()));
println!("{row:#?}");
let row = row.expect("an Alkane board at ALKANE_TEST_IP");
assert!(is_alkane(&row));
}
}
+2
View File
@@ -6,6 +6,7 @@
#![cfg_attr(windows, windows_subsystem = "windows")]
mod access_probe;
mod alkane_detect;
mod askpass;
mod bug_report;
mod credentials;
@@ -20,6 +21,7 @@ mod pool_prefs;
mod presets;
mod restore;
mod scan;
mod stock_ops;
mod ui;
fn main() {
+4
View File
@@ -527,6 +527,10 @@ pub struct MinerRow {
/// from whether any control capability is available: `None` = unknown,
/// `Some(true)` = locked, `Some(false)` = unlocked/writable.
pub write_locked: Option<bool>,
/// Set when the row is a board running Alkane OS (found by the toolkit's own
/// probe, `alkane_detect`, not asic-rs): the board family it reports
/// ("zynq-7010"), or an empty string for an older image that does not say.
pub alkane_board: Option<String>,
/// Structured error/event lines from the miner (severity + text), most
/// severe first. Empty means none. The Error column shows a summary; the
/// full list is the hover tooltip (added with the tooltip bridge support).
+62 -7
View File
@@ -531,7 +531,10 @@ pub fn start_scan(lines: Vec<String>, timeout_secs: u64) -> ScanHandle {
.ok();
(ip, row)
}
None => (ip, None),
// asic-rs does not recognise a board running Alkane
// OS (no cgminer socket or vendor web UI exposed);
// the toolkit's own probe finds it.
None => (ip, crate::alkane_detect::detect(ip).await),
}
}
})
@@ -1229,6 +1232,8 @@ async fn to_row(miner: &dyn Miner) -> MinerRow {
.unwrap_or_default(),
pic_present,
write_locked,
// asic-rs identified this miner, so it is not running Alkane OS.
alkane_board: None,
errors,
faults,
model,
@@ -1917,13 +1922,25 @@ pub fn start_refresh(ips: Vec<String>) -> RefreshHandle {
ok += 1;
RefreshMsg::Row(to_row(&*miner).await)
}
Ok(None) => RefreshMsg::Failed {
ip: ip_s,
detail: "offline".to_string(),
Ok(None) => match crate::alkane_detect::detect(ip).await {
Some(row) => {
ok += 1;
RefreshMsg::Row(row)
}
None => RefreshMsg::Failed {
ip: ip_s,
detail: "offline".to_string(),
},
},
Err(e) => RefreshMsg::Failed {
ip: ip_s,
detail: format!("{e}"),
Err(e) => match crate::alkane_detect::detect(ip).await {
Some(row) => {
ok += 1;
RefreshMsg::Row(row)
}
None => RefreshMsg::Failed {
ip: ip_s,
detail: format!("{e}"),
},
},
},
};
@@ -2615,3 +2632,41 @@ mod tests {
std::env::remove_var(FAKE_SCAN_ENV);
}
}
#[cfg(test)]
mod live_scan_tests {
/// Run the real fleet scan over a range and print, per row found, what the
/// alkane-os menu would offer:
/// `ALKANE_TEST_SCAN_RANGE=10.255.1.0/24 cargo test -p alkane-gui live_scan -- --ignored --nocapture`
#[test]
#[ignore = "needs a reachable miner network (ALKANE_TEST_SCAN_RANGE)"]
fn live_scan() {
let Ok(range) = std::env::var("ALKANE_TEST_SCAN_RANGE") else {
return;
};
let handle = super::start_scan(vec![range], 10);
let mut rows = std::collections::BTreeMap::new();
while let Ok(msg) = handle.rx.recv() {
match msg {
super::ScanMsg::Row(row) => {
rows.insert(row.ip.clone(), row);
}
super::ScanMsg::Done(_) | super::ScanMsg::Failed(_) => break,
_ => {}
}
}
for row in rows.values() {
println!(
"{:<15} brand={:<10} model={:<12} fw={:<8} {:<8} board={:<10} install={} uninstall={}",
row.ip,
row.brand,
row.model,
row.firmware,
row.fw_version,
row.control_board,
crate::alkane_detect::install_supported(row),
crate::alkane_detect::is_alkane(row),
);
}
}
}
+284
View File
@@ -0,0 +1,284 @@
//! Install alkane-os onto a board on stock, and restore an alkane board to
//! stock, from the GUI - using the toolkit's own self-contained, network-only
//! engine (`alkane_flash::stock`), the same code the CLI drives. There is no
//! external helper and no runtime dependency on any other tool: the
//! stock-crossing method is compiled into this binary. This module drives that
//! engine on a background thread and reports progress.
//!
//! Both operations are DESTRUCTIVE (they reflash the control board) and run on a
//! background thread so the reboot/flash latency never blocks the wx event loop.
//! Results stream back over a channel, drained by the UI timer tick exactly like
//! restore.rs. The UI gates each behind a typed-FLASH confirmation.
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{channel, Receiver};
use std::sync::Arc;
use alkane_artifacts::afw::{verify_afw, VerifyOptions};
use alkane_artifacts::fetch::{self, ReleaseSource};
use alkane_flash::stock::{self, RestoreImages};
use alkane_flash::stock_firmware;
use crate::scan::fake_scan_enabled;
/// Control boards alkane-os can be installed onto from stock (mirrors the CLI's
/// `SUPPORTED`). Only these are offered as install targets.
pub const SUPPORTED_BOARDS: &[(&str, &str)] =
&[("zynq-7010", "Antminer S17 (Xilinx Zynq-7010 control board)")];
/// The default install board when the user has not chosen another.
pub const DEFAULT_BOARD: &str = "zynq-7010";
pub fn is_supported_board(board: &str) -> bool {
SUPPORTED_BOARDS.iter().any(|(b, _)| *b == board)
}
/// The release asset to install: its filename and download URL, resolved to a
/// local path on the worker thread so the download never blocks the UI. (Local-
/// file install is a CLI feature; the GUI installs from scanned releases.)
pub struct AfwChoice {
pub name: String,
pub url: String,
}
/// Progress + results streamed from the background worker to the UI.
pub enum StockMsg {
Started,
/// A human-readable status line for the status bar (acquiring, verifying...).
Progress(String),
/// One board's outcome.
Result {
ip: String,
ok: bool,
detail: String,
},
Done,
}
pub struct StockHandle {
pub rx: Receiver<StockMsg>,
// Cancellation is honoured between boards; a UI stop control is not wired yet.
#[allow(dead_code)]
cancel: Arc<AtomicBool>,
}
impl StockHandle {
#[allow(dead_code)]
pub fn stop(&self) {
self.cancel.store(true, Ordering::Relaxed);
}
}
fn download_dir() -> PathBuf {
alkane_core::platform::config_path("downloads")
}
/// Install alkane-os onto the given boards (currently on stock), over the
/// network, via the compiled-in from-stock method. `board` is the target board
/// family (gates the `.afw`); `password`, if set, is passed in-process to the
/// method (never to the environment or an argument).
pub fn start_install(
ips: Vec<String>,
board: String,
source: AfwChoice,
allow_unsigned: bool,
password: Option<String>,
) -> StockHandle {
let (tx, rx) = channel();
let cancel = Arc::new(AtomicBool::new(false));
if fake_scan_enabled() {
let _ = tx.send(StockMsg::Started);
let _ = tx.send(StockMsg::Progress(
"install (demo): no hardware touched".into(),
));
for ip in ips {
let _ = tx.send(StockMsg::Result {
ip,
ok: true,
detail: "installed alkane-os (demo)".into(),
});
}
let _ = tx.send(StockMsg::Done);
return StockHandle { rx, cancel };
}
let tc = cancel.clone();
let err_tx = tx.clone();
let spawned = std::thread::Builder::new()
.name("install-from-stock".into())
.spawn(move || {
let _ = tx.send(StockMsg::Started);
// 1. Download the chosen release asset (on this worker thread).
let _ = tx.send(StockMsg::Progress("acquiring .afw...".into()));
let afw_path = match fetch::fetch_afw_url(
&ReleaseSource::alkane_os(),
&source.name,
&source.url,
&download_dir(),
) {
Ok(p) => p,
Err(e) => {
// One failure line per target so the UI clears its op-status.
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!("could not fetch .afw: {e}"),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
};
// 2. Verify + gate the bundle once (board/arch/bootloader + integrity).
let _ = tx.send(StockMsg::Progress("verifying .afw...".into()));
let verified = match verify_afw(
&afw_path,
&VerifyOptions {
allow_unsigned,
expect_board: Some(board.clone()),
},
) {
Ok(v) => v,
Err(e) => {
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!(".afw rejected: {e}"),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
};
if !is_supported_board(&verified.manifest.board) {
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!(
"{} is not a supported install target",
verified.manifest.board
),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
// 3. Install onto each board via the network-only from-stock method.
for ip in ips {
if tc.load(Ordering::Relaxed) {
break;
}
let _ = tx.send(StockMsg::Progress(format!(
"installing {} onto {ip} (from stock)...",
verified.manifest.board
)));
let (ok, detail) =
match stock::install_from_stock(&ip, &afw_path, &verified, password.as_deref())
{
Ok(()) => (
true,
"installed alkane-os (verify liveness over the network)".to_string(),
),
Err(e) => (false, format!("install failed: {e}")),
};
if tx.send(StockMsg::Result { ip, ok, detail }).is_err() {
return;
}
}
let _ = tx.send(StockMsg::Done);
});
if spawned.is_err() {
let _ = err_tx.send(StockMsg::Result {
ip: String::new(),
ok: false,
detail: "could not start the install worker thread".into(),
});
let _ = err_tx.send(StockMsg::Done);
}
StockHandle { rx, cancel }
}
/// Restore one board to genuine Bitmain stock using the user-supplied vendor
/// firmware package: parse it into the stock images and write them back over the
/// network. `password`, if given, is the board's alkane root credential.
fn restore_one(ip: &str, firmware: &Path, password: Option<&str>) -> (bool, String) {
let fw = match stock_firmware::parse(firmware) {
Ok(f) => f,
Err(e) => return (false, format!("firmware: {e}")),
};
// The device tree comes from the toolkit's per-board asset, not the package,
// so any genuine Bitmain firmware (OTA or SD) provides a usable kernel+rootfs.
let images = RestoreImages {
kernel: &fw.kernel,
rootfs: &fw.rootfs,
};
match stock::restore_to_stock(ip, &images, password) {
Ok(()) => (
true,
"restored to stock (verify independently it no longer answers as alkane)".to_string(),
),
Err(e) => (false, format!("restore failed: {e}")),
}
}
/// Restore the given alkane boards to genuine Bitmain stock, over the network,
/// by writing the stock images from `firmware` (a genuine vendor firmware
/// package) back to NAND. `password`, if set, is the board's alkane root
/// credential.
pub fn start_restore(ips: Vec<String>, firmware: PathBuf, password: Option<String>) -> StockHandle {
let (tx, rx) = channel();
let cancel = Arc::new(AtomicBool::new(false));
if fake_scan_enabled() {
let _ = tx.send(StockMsg::Started);
for ip in ips {
let _ = tx.send(StockMsg::Result {
ip,
ok: true,
detail: "restored to stock (demo)".into(),
});
}
let _ = tx.send(StockMsg::Done);
return StockHandle { rx, cancel };
}
let tc = cancel.clone();
let err_tx = tx.clone();
let spawned = std::thread::Builder::new()
.name("restore-to-stock".into())
.spawn(move || {
let _ = tx.send(StockMsg::Started);
for ip in ips {
if tc.load(Ordering::Relaxed) {
break;
}
let _ = tx.send(StockMsg::Progress(format!(
"restoring {ip} to stock (network-only)..."
)));
let (ok, detail) = restore_one(&ip, &firmware, password.as_deref());
if tx.send(StockMsg::Result { ip, ok, detail }).is_err() {
return;
}
}
let _ = tx.send(StockMsg::Done);
});
if spawned.is_err() {
let _ = err_tx.send(StockMsg::Result {
ip: String::new(),
ok: false,
detail: "could not start the restore worker thread".into(),
});
let _ = err_tx.send(StockMsg::Done);
}
StockHandle { rx, cancel }
}
+536 -9
View File
@@ -1,10 +1,13 @@
//! Primary view per docs/UI-SPEC.md: KPI header, scan-ranges editor,
//! Excel-style filter panel, columns panel, sortable/drag-reorderable table.
use crate::alkane_detect;
use crate::credentials;
use crate::model::*;
use crate::restore;
use crate::scan::{self, ScanMsg};
use crate::stock_ops::{self, AfwChoice, StockMsg};
use alkane_artifacts::fetch::{self, ReleaseInfo, ReleaseSource};
use asic_rs::core::data::firmware::FirmwareImage;
use std::cell::RefCell;
use std::collections::{HashMap, HashSet};
@@ -96,6 +99,17 @@ const ID_RESTORE_CANCEL: i32 = 787;
const ID_CTX_POOLS: i32 = 736;
const ID_POOLS_OK: i32 = 788;
const ID_POOLS_CANCEL: i32 = 789;
// Alkane-OS self-contained install/uninstall (stock_ops.rs): put our first image
// onto a board on stock, and return an alkane board to stock, both via the
// toolkit's own compiled-in network-only engine. Typed-FLASH confirmation.
const ID_CTX_INSTALL_ALKANE: i32 = 770;
const ID_CTX_UNINSTALL_ALKANE: i32 = 771;
const ID_CTX_UPDATE_ALKANE: i32 = 772;
const ID_INSTALL_OK: i32 = 1006;
const ID_INSTALL_CANCEL: i32 = 1007;
const ID_INSTALL_RELEASE_CHOICE: i32 = 1008;
const ID_UNINSTALL_OK: i32 = 1009;
const ID_UNINSTALL_CANCEL: i32 = 1010;
// Pool-preset manager dialog (round 18 #8b): edit the whole saved list at once.
// NB: 790-795 belong to the language menu (ID_LANG_BASE + Lang index), so these
// live in a separate high block to avoid an id collision (round 18 #12).
@@ -882,6 +896,23 @@ pub struct App {
restore: Option<restore::RestoreHandle>,
restore_dialog: Widget,
pending_restore: Vec<restore::RestoreTarget>,
// Alkane-OS self-contained install/uninstall (stock_ops.rs): one background job
// (either direction) + the two typed-confirm dialogs and the state captured
// when a dialog opens (the scanned release list, target IPs, target board).
stock_op: Option<stock_ops::StockHandle>,
install_dialog: Widget,
install_release_choice: Widget,
install_pass_input: Widget,
install_unsigned_check: Widget,
install_confirm_input: Widget,
install_releases: Vec<ReleaseInfo>,
install_ips: Vec<String>,
install_board: String,
uninstall_dialog: Widget,
uninstall_pass_input: Widget,
uninstall_firmware_input: Widget,
uninstall_confirm_input: Widget,
uninstall_ips: Vec<String>,
// Configure-pools dialog (round 14 #7, expanded round 15 #1): 3 pool rows x 4
// fields (address, account, worker, password) = 12 text controls, indexed
// row*4 + field. Plus the "+" dropdown menu state.
@@ -1256,6 +1287,20 @@ pub fn build(frame: Widget) -> App {
restore: None,
restore_dialog: frame,
pending_restore: Vec::new(),
stock_op: None,
install_dialog: frame,
install_release_choice: frame,
install_pass_input: frame,
install_unsigned_check: frame,
install_confirm_input: frame,
install_releases: Vec::new(),
install_ips: Vec::new(),
install_board: stock_ops::DEFAULT_BOARD.to_string(),
uninstall_dialog: frame,
uninstall_pass_input: frame,
uninstall_firmware_input: frame,
uninstall_confirm_input: frame,
uninstall_ips: Vec::new(),
pools_dialog: frame,
pool_fields: Vec::new(),
pool_menu_target: 0,
@@ -1748,10 +1793,10 @@ impl App {
format!("Open {n} miners in browser")
};
menu.menu_append(ID_CTX_OPEN, &open);
// While a firmware flash holds the exclusive lock, offer only the
// read-only "Open in browser" action; every network action is refused
// anyway, so don't dangle them in the menu.
if self.flashing {
// While a firmware flash or a stock install/restore holds the exclusive
// lock, offer only the read-only "Open in browser" action; every network
// action is refused anyway, so don't dangle them in the menu.
if self.flashing || self.stock_op.is_some() {
self.pending_popup = Some((t, menu));
return;
}
@@ -1842,6 +1887,37 @@ impl App {
// the vendor installers cover the current workflow. (ID_CTX_FLASH and the
// flash dialog remain in the code, just not surfaced here.)
let _ = ID_CTX_FLASH;
// Alkane OS install / update / uninstall via the toolkit's own
// self-contained, network-only engine. Each is offered only when it
// applies to every selected board:
// - Install: a supported board (alkane-os has an image for its control
// board) that is not running Alkane OS yet;
// - Update: a supported board already running Alkane OS (updated in
// place);
// - Uninstall: a board running Alkane OS (restored to stock).
// A mixed stock/Alkane selection gets neither Install nor Update. The
// engine still gates on compatibility and a typed FLASH confirmation.
let supported = selected.iter().all(|r| alkane_detect::install_supported(r));
let all_alkane = selected.iter().all(|r| alkane_detect::is_alkane(r));
let none_alkane = selected.iter().all(|r| !alkane_detect::is_alkane(r));
let install = supported && none_alkane;
let update = supported && all_alkane;
let uninstall = all_alkane;
if install || update || uninstall {
menu.menu_append_separator();
}
if install {
menu.menu_append(ID_CTX_INSTALL_ALKANE, "Install alkane OS...");
}
if update {
menu.menu_append(ID_CTX_UPDATE_ALKANE, "Update alkane OS...");
}
if uninstall {
menu.menu_append(
ID_CTX_UNINSTALL_ALKANE,
"Uninstall alkane OS (restore to stock)...",
);
}
self.pending_popup = Some((t, menu));
}
@@ -2109,8 +2185,10 @@ impl App {
// This path sets self.action directly, so it needs start_action's full
// exclusivity guard: don't write pools during a restore or a live scan
// (round 18 #12).
if self.restore.is_some() {
wx_rs::set_status_text("restore-to-stock in progress -- wait for it to finish");
if self.restore.is_some() || self.stock_op.is_some() {
wx_rs::set_status_text(
"a stock install/restore is in progress -- wait for it to finish",
);
return;
}
if self.scanning {
@@ -2206,8 +2284,10 @@ impl App {
}
// A restore-to-stock is reverting + rebooting miners; a config action mid-
// revert could hit a unit in an undefined state (round 18 #12).
if self.restore.is_some() {
wx_rs::set_status_text("restore-to-stock in progress -- wait for it to finish");
if self.restore.is_some() || self.stock_op.is_some() {
wx_rs::set_status_text(
"a stock install/restore is in progress -- wait for it to finish",
);
return;
}
// A scan is opening its own connections to these same miners; a mutating
@@ -2442,6 +2522,7 @@ impl App {
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
{
wx_rs::set_status_text(
"busy (scan/action/restore in progress) -- try again once it finishes",
@@ -2525,6 +2606,436 @@ impl App {
let _ = oks;
}
/// True when any hardware-touching job is in flight. A new install/uninstall
/// must not start while a scan, config action, refresh, flash, restore, or
/// another stock op is running (they would race on the same boards).
fn hardware_busy(&self) -> bool {
self.flashing
|| self.scanning
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
}
/// Build the "Install alkane OS" dialog (or, with `update`, the "Update
/// alkane OS" dialog for boards already running it): a scanned list of
/// alkane-os releases to pick from, an optional board credential, the
/// allow-unsigned (bench) toggle, and a typed FLASH confirmation. The install
/// runs over the network via the toolkit's own compiled-in from-stock engine.
fn build_install_dialog(&mut self, update: bool) -> Option<Widget> {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
return None;
}
let ips = self.selected_ip_list();
if ips.is_empty() {
wx_rs::set_status_text("select a board to install onto");
return None;
}
let board = self.install_board.clone();
// Scan alkane-os releases from Gitea (newest first), keeping those that
// carry an .afw for this board. One quick API call, done synchronously so
// the picker is populated when the dialog opens.
wx_rs::set_status_text("scanning alkane-os releases...");
let releases: Vec<ReleaseInfo> = match fetch::list_releases(&ReleaseSource::alkane_os()) {
Ok(list) => list
.into_iter()
.filter(|r| !r.draft && r.asset_for_board(&board).is_some())
.collect(),
Err(e) => {
wx_rs::set_status_text(&format!("could not list releases: {e}"));
Vec::new()
}
};
self.install_releases = releases;
self.install_ips = ips.clone();
let frame = Widget::main_frame();
let title = if update {
"Update alkane OS"
} else {
"Install alkane OS"
};
let dlg = Widget::dialog(frame, title);
let root = Widget::box_sizer(true);
let n = ips.len();
root.add(
Widget::static_text(
dlg,
&if update {
format!(
"Update alkane OS on {n} board(s) already running it (updated in place; BOOT.bin is never written):\n{}",
ips.join(", ")
)
} else {
format!(
"Install alkane OS onto {n} board(s) currently on stock:\n{}",
ips.join(", ")
)
},
),
0,
sf::BORDER_ALL,
12,
);
root.add(
Widget::static_text(dlg, &format!("Target board: {board}")),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT,
12,
);
root.add(
Widget::static_text(
dlg,
if update {
"Release to update to (newest first):"
} else {
"Release to install (newest first):"
},
),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let choice = Widget::choice(dlg, ID_INSTALL_RELEASE_CHOICE);
if self.install_releases.is_empty() {
choice.choice_append("(no release with an .afw for this board was found)");
} else {
for (i, r) in self.install_releases.iter().enumerate() {
let tag = if r.tag.is_empty() {
r.name.as_str()
} else {
r.tag.as_str()
};
let kind = if r.prerelease { " [pre-release]" } else { "" };
let latest = if i == 0 { " (latest)" } else { "" };
let date = r.published_at.split('T').next().unwrap_or("");
choice.choice_append(&format!("{tag}{kind} {date}{latest}"));
}
choice.choice_set_selection(0);
}
root.add(
choice,
0,
sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT,
12,
);
self.install_release_choice = choice;
root.add(
Widget::static_text(dlg, "Board password (optional):"),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let pass = Widget::text_ctrl(dlg, false);
root.add(pass, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.install_pass_input = pass;
// Current bench .afw files are unsigned (SHA-256 integrity, no Ed25519).
let unsigned = Widget::check_box(dlg, "Allow unsigned .afw (bench only)");
unsigned.set_checked(true);
root.add(unsigned, 0, sf::BORDER_ALL, 12);
self.install_unsigned_check = unsigned;
root.add(
Widget::static_text(
dlg,
"This reflashes the control board. Type FLASH to confirm:",
),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let confirm = Widget::text_ctrl(dlg, false);
root.add(
confirm,
0,
sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT,
12,
);
self.install_confirm_input = confirm;
let btns = Widget::box_sizer(false);
btns.add_stretch(1);
btns.add(
Widget::button(dlg, "Install", ID_INSTALL_OK),
0,
sf::BORDER_ALL,
6,
);
btns.add(
Widget::button(dlg, "Cancel", ID_INSTALL_CANCEL),
0,
sf::BORDER_ALL,
6,
);
root.add_sizer(btns, 0, sf::EXPAND | sf::BORDER_ALL, 6);
root.set_sizer_on(dlg);
dlg.set_min_size(540, 440);
dlg.fit(dlg);
self.install_dialog = dlg;
wx_rs::set_status_text(&format!(
"{} release(s) available for {board}",
self.install_releases.len()
));
Some(dlg)
}
/// Apply the install confirmation: validate the typed keyword, resolve the
/// chosen release asset, and start the network-only from-stock install.
fn apply_install_confirm(&mut self) {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
self.install_dialog.close(0);
return;
}
if !flash_confirmed(&self.install_confirm_input.get_value()) {
wx_rs::set_status_text("type FLASH to confirm the install");
return;
}
let idx = self.install_release_choice.choice_get_selection();
if idx < 0 || self.install_releases.is_empty() {
wx_rs::set_status_text("no release selected");
return;
}
let board = self.install_board.clone();
let Some(release) = self.install_releases.get(idx as usize) else {
wx_rs::set_status_text("no release selected");
return;
};
let Some(asset) = release.asset_for_board(&board) else {
wx_rs::set_status_text("the selected release has no .afw for this board");
return;
};
let source = AfwChoice {
name: asset.name.clone(),
url: asset.url.clone(),
};
let asset_name = asset.name.clone();
let allow_unsigned = self.install_unsigned_check.is_checked();
let password = {
let p = self.install_pass_input.get_value();
if p.is_empty() {
None
} else {
Some(p)
}
};
let ips = std::mem::take(&mut self.install_ips);
if ips.is_empty() {
self.install_dialog.close(0);
return;
}
self.install_dialog.close(1);
crate::logs::log(format!(
"install alkane OS onto {} board(s) from {}",
ips.len(),
asset_name
));
self.set_op_status(&ips, "installing...");
self.stock_op = Some(stock_ops::start_install(
ips,
board,
source,
allow_unsigned,
password,
));
}
/// Build the "Uninstall alkane OS (restore to stock)" dialog: the board's
/// alkane root credential and a typed FLASH confirmation.
fn build_uninstall_dialog(&mut self) -> Option<Widget> {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
return None;
}
let ips = self.selected_ip_list();
if ips.is_empty() {
wx_rs::set_status_text("select an alkane board to restore to stock");
return None;
}
self.uninstall_ips = ips.clone();
let frame = Widget::main_frame();
let dlg = Widget::dialog(frame, "Uninstall alkane OS (restore to stock)");
let root = Widget::box_sizer(true);
let n = ips.len();
root.add(
Widget::static_text(
dlg,
&format!(
"Restore {n} alkane board(s) to genuine stock:\n{}",
ips.join(", ")
),
),
0,
sf::BORDER_ALL,
12,
);
root.add(
Widget::static_text(
dlg,
"Genuine Bitmain stock firmware file for this board\n(an OTA update .tar.gz or an SD recovery .zip):",
),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let fw = Widget::text_ctrl(dlg, false);
root.add(fw, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.uninstall_firmware_input = fw;
root.add(
Widget::static_text(dlg, "Board (alkane root) password (optional):"),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let pass = Widget::text_ctrl(dlg, false);
root.add(pass, 0, sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT, 12);
self.uninstall_pass_input = pass;
root.add(
Widget::static_text(
dlg,
"This reflashes the board back to stock (BOOT.bin preserved).\nType FLASH to confirm:",
),
0,
sf::BORDER_LEFT | sf::BORDER_RIGHT | sf::BORDER_TOP,
12,
);
let confirm = Widget::text_ctrl(dlg, false);
root.add(
confirm,
0,
sf::EXPAND | sf::BORDER_LEFT | sf::BORDER_RIGHT,
12,
);
self.uninstall_confirm_input = confirm;
let btns = Widget::box_sizer(false);
btns.add_stretch(1);
btns.add(
Widget::button(dlg, "Restore to stock", ID_UNINSTALL_OK),
0,
sf::BORDER_ALL,
6,
);
btns.add(
Widget::button(dlg, "Cancel", ID_UNINSTALL_CANCEL),
0,
sf::BORDER_ALL,
6,
);
root.add_sizer(btns, 0, sf::EXPAND | sf::BORDER_ALL, 6);
root.set_sizer_on(dlg);
dlg.set_min_size(540, 440);
dlg.fit(dlg);
self.uninstall_dialog = dlg;
Some(dlg)
}
fn apply_uninstall_confirm(&mut self) {
if self.hardware_busy() {
wx_rs::set_status_text("busy -- try again once the current operation finishes");
self.uninstall_dialog.close(0);
return;
}
if !flash_confirmed(&self.uninstall_confirm_input.get_value()) {
wx_rs::set_status_text("type FLASH to confirm the restore");
return;
}
let firmware = self.uninstall_firmware_input.get_value();
let firmware = firmware.trim();
if firmware.is_empty() {
wx_rs::set_status_text("a genuine Bitmain stock firmware file is required");
return;
}
if !std::path::Path::new(firmware).is_file() {
wx_rs::set_status_text(&format!("firmware file not found: {firmware}"));
return;
}
let password = {
let p = self.uninstall_pass_input.get_value();
if p.is_empty() {
None
} else {
Some(p)
}
};
let ips = std::mem::take(&mut self.uninstall_ips);
if ips.is_empty() {
self.uninstall_dialog.close(0);
return;
}
self.uninstall_dialog.close(1);
crate::logs::log(format!("restore {} alkane board(s) to stock", ips.len()));
self.set_op_status(&ips, "restoring...");
self.stock_op = Some(stock_ops::start_restore(
ips,
std::path::PathBuf::from(firmware),
password,
));
}
/// Drain the alkane install/uninstall job: progress onto the status bar,
/// per-board results into the op-status, and finalisation on Done.
fn drain_stock_op(&mut self) {
let Some(h) = &self.stock_op else { return };
let mut done = false;
let mut oks = 0usize;
let mut fails: Vec<String> = Vec::new();
let mut op_clear: Vec<String> = Vec::new();
let mut progress: Option<String> = None;
loop {
match h.rx.try_recv() {
Ok(StockMsg::Started) => {}
Ok(StockMsg::Progress(s)) => progress = Some(s),
Ok(StockMsg::Result { ip, ok, detail }) => {
if !ip.is_empty() {
op_clear.push(ip.clone());
}
if ok {
oks += 1;
} else {
fails.push(format!("{ip}: {detail}"));
}
}
Ok(StockMsg::Done) => {
done = true;
break;
}
Err(std::sync::mpsc::TryRecvError::Empty) => break,
Err(std::sync::mpsc::TryRecvError::Disconnected) => {
done = true;
break;
}
}
}
for ip in &op_clear {
self.op_status.remove(ip);
}
if let Some(p) = progress {
wx_rs::set_status_text(&p);
}
if done {
self.stock_op = None;
self.op_status
.retain(|_, v| v != "installing..." && v != "restoring...");
}
if !op_clear.is_empty() || done {
self.fill_rows();
}
if done {
if !fails.is_empty() {
self.set_error_indicator(&format!("stock op: {} failed", fails.len()));
} else if oks > 0 {
wx_rs::set_status_text(&format!("stock op complete: {oks} ok"));
}
}
}
/// Start the access (lock-state) probe on the selected miners, using the
/// saved scan (web) credentials (defaulting to root/root if none are set).
fn start_access_probe(&mut self) {
@@ -2658,6 +3169,9 @@ impl App {
ID_CTX_ACCESS_PROBE => self.start_access_probe(),
ID_CTX_VIEW_LOG => self.start_log_fetch(),
ID_CTX_RESTORE_STOCK => return self.build_restore_confirm_dialog(),
ID_CTX_INSTALL_ALKANE => return self.build_install_dialog(false),
ID_CTX_UPDATE_ALKANE => return self.build_install_dialog(true),
ID_CTX_UNINSTALL_ALKANE => return self.build_uninstall_dialog(),
ID_CTX_POOLS => return self.build_pools_dialog(),
ID_CTX_FLASH => {
// A flash needs exclusive hardware access; don't even prompt if
@@ -2667,6 +3181,7 @@ impl App {
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
{
wx_rs::set_status_text(
"busy (scan/action in progress) -- try again once it finishes",
@@ -3155,6 +3670,7 @@ impl App {
|| self.action.is_some()
|| self.refresh.is_some()
|| self.restore.is_some()
|| self.stock_op.is_some()
{
wx_rs::set_status_text("busy (scan/action started) -- flash cancelled, try again");
return;
@@ -3735,6 +4251,7 @@ impl App {
self.drain_refresh();
self.drain_access_probe();
self.drain_restore();
self.drain_stock_op();
self.drain_report();
// A completed background log fetch yields a viewer dialog to show; return
// it so `dispatch` presents it modally after the App borrow is released
@@ -3806,7 +4323,7 @@ impl App {
// Symmetric to start_action's scan guard: don't start a scan (including an
// auto-rescan) while a config action or restore is writing to miners, so
// the two never race on the same unit (round 18 #12).
if self.action.is_some() || self.restore.is_some() {
if self.action.is_some() || self.restore.is_some() || self.stock_op.is_some() {
wx_rs::set_status_text("operation in progress -- scan deferred");
return false;
}
@@ -5261,6 +5778,16 @@ impl App {
self.pending_restore.clear();
self.restore_dialog.close(0);
}
ID_INSTALL_OK => self.apply_install_confirm(),
ID_INSTALL_CANCEL => {
self.install_ips.clear();
self.install_dialog.close(0);
}
ID_UNINSTALL_OK => self.apply_uninstall_confirm(),
ID_UNINSTALL_CANCEL => {
self.uninstall_ips.clear();
self.uninstall_dialog.close(0);
}
ID_POOLS_OK => self.apply_pools(),
ID_POOLS_CANCEL => self.pools_dialog.close(0),
// Pool-preset manager buttons (round 18 #8b).
+171
View File
@@ -0,0 +1,171 @@
# Installing and removing alkane-os
Two front-ends drive the same self-contained engine:
- The CLI (`alkane-cli afw ...`), documented below, is the scriptable path.
- The GUI (`alkane-toolkit`) can scan the fleet, then right-click a board to
install alkane-os onto it from stock or restore it to stock. See
"GUI (right-click install / uninstall)" at the end. (The GUI's older asic-rs
firmware-upload path stays disabled; these two actions use the compiled-in
network-only engine, the same one the CLI uses.)
## Compatible miners
```
alkane-cli afw compat
```
Lists the control boards alkane-os can be installed on. For now that is the
Antminer S17 (`zynq-7010`). The install/restore commands refuse any board whose
`.afw` is not one of these.
## Install
From a local bundle:
```
alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
--host <miner-ip> --confirm FLASH
```
From the latest release (pulled from Gitea, not GitHub, which is retired):
```
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> --confirm FLASH
# or fetch only:
alkane-cli afw fetch-latest --board zynq-7010 --output ./downloads
```
A private release repo needs a token, read from `ALKANE_RELEASE_TOKEN` (else
`GITEA_TOKEN`) at run time and passed to curl through a 0600 config file - never
on the command line, never stored by the toolkit.
### A board still on stock
Writing our first image onto a board that is still on genuine stock (past the
stock gates and getting root) is done by the toolkit itself, over the network.
The method is part of this binary; nothing else needs to be installed on your
machine. On first use it fetches a small set of per-board assets from our Gitea
(repo `blueflare/alkane-stock-assets`, release `zynq-7010-v1`) and caches them
locally, verifying each against a known SHA-256. That repo is public, so no token
is needed for the stock assets. The asset base URL can be overridden with
`ALKANE_STOCK_ASSETS_BASE`.
Add `--from-stock` (the token below is only to resolve `--latest` from the
private alkane-os release repo; a local `.afw` needs no token):
```
export ALKANE_RELEASE_TOKEN=<your-gitea-token>
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> \
--from-stock --confirm FLASH
```
The toolkit acquires and verifies the `.afw`, gates on compatibility, fetches
and verifies its assets, performs the network-only stock-side install, then you
verify the board came up as alkane:
```
alkane-cli afw verify-live --host <miner-ip> --timeout 300
```
On Zynq (S17/S19 class) pass the `.afw` (or `--board zynq-7010`) and the board's
alkane root credential; the check needs the web page to carry the image marker
and SSH to report alkane with the installed kernel, and prints the running kernel
command line (on a NAND boot it is the board's U-Boot env bootargs):
```
alkane-cli afw verify-live path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
--host <miner-ip> --password-file <alkane-root-pw> --timeout 300
```
For a bench image that is not signed, add `--allow-unsigned`.
Without `--from-stock`, `install` performs a tier-2 update of a board already on
alkane, in place, over the network:
```
alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
--host <miner-ip> --password-file <alkane-root-pw> --dry-run
alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
--host <miner-ip> --password-file <alkane-root-pw> --confirm FLASH
```
On Zynq (S17/S19 class) the update refuses a board that is not running alkane.
Alkane does not expose the NAND boot regions to Linux (only the small
`stock-cfg` and `alkane-cfg` partitions), so the toolkit re-registers them
first, the same way a restore does. It saves each boot slot to `--backup-dir`
(default: the toolkit's `backups` directory) before any erase, then writes the
rootfs (absolute NAND `0x2800000`), dtb (`0x1a00000`) and kernel (`0x2000000`),
with the kernel and rootfs wrapped as the legacy uImages the board's stock
U-Boot boots, and reads each back (md5) before rebooting. Nothing below
`0x1a00000` (BOOT.bin: FSBL, FPGA bitstream, U-Boot) is ever written.
`afw preflight` runs the same checks read-only. `--no-reboot` skips the reboot.
## Remove (back to stock)
```
alkane-cli afw restore-stock --host <miner-ip> \
--stock-firmware <genuine-Bitmain-firmware> \
--password-file <alkane-root-pw> --confirm FLASH
```
Returning an aftermarket board to genuine stock is done by the toolkit itself,
over the network. It writes the genuine Bitmain stock **kernel and rootfs** -
parsed from a vendor firmware file you supply with `--stock-firmware` (an OTA
update `.tar.gz` or an SD recovery `.zip` for the board) - back to NAND,
preserving BOOT.bin.
The one piece that is NOT in Bitmain's distributable firmware is the kernel
**device tree**: it is factory-provisioned and preserved by every vendor update,
so no OTA/SD package ships it. The toolkit supplies the correct per-board dtb
itself (fetched + verified from the public assets repo, so no token is needed)
and pairs it with the genuine kernel/rootfs. The board's alkane root credential
is given with `--password-file` (or
`ALKANE_BOARD_PASSWORD`/`ALKANE_BOARD_PASSWORD_FILE`).
After a restore the board returns to stock under its stock MAC and typically
takes a new DHCP lease, so it may not reappear on the same address; verify
independently that the board no longer answers as alkane and presents its stock
OS.
## GUI (right-click install / uninstall)
The GUI binary is `alkane-toolkit`. Launch it, let the scan list the fleet, then
right-click one or more boards. The scan finds boards running Alkane OS too
(Firmware column "Alkane"): they expose no cgminer socket or vendor web UI, so the
toolkit identifies them itself from the board's public read-only
`GET /api/identity` (alkane-os 0.1.2 and later; earlier images are found from
`/api/summary`). Each action below is offered only when it applies to every
selected board:
- "Install alkane OS..." - for a supported board (one alkane-os has an image
for; today the Zynq-7010 Antminer S17/S17 Pro/T17) that is not running Alkane
OS yet. Scans the alkane-os releases on Gitea, lets you pick one (newest first;
pre-releases are marked), optionally takes a board password and an "allow
unsigned .afw (bench)" toggle, and - after you type FLASH to confirm -
downloads/verifies the `.afw` and installs it onto each selected board over the
network, via the same compiled-in engine the CLI uses.
- "Update alkane OS..." - for a supported board already running Alkane OS: the
same release picker and confirmation; the board is updated in place (BOOT.bin
is never written).
- "Uninstall alkane OS (restore to stock)..." - for a board running Alkane OS:
takes the board's alkane root password, a genuine Bitmain firmware package and
a typed FLASH confirmation, then restores each selected board to genuine stock
over the network.
A stock board the scan identifies but cannot place on a supported control board
(or a mixed stock/Alkane selection) gets neither Install nor Update.
Progress and per-board results appear on the status bar; verify board state
independently afterwards (the GUI does not claim liveness on its own).
Release scanning reads the private `alkane-os` repo, so it needs a Gitea token.
A read-only token can be baked into the GUI at build time
(`ALKANE_EMBEDDED_TOKEN=<token>` when building), so the shipped binary scans
releases with no setup; otherwise set `ALKANE_RELEASE_TOKEN` (or `GITEA_TOKEN`)
in the environment before launching. The stock-asset fetch needs no token (that
repo is public), so install-from-stock and restore-to-stock work without one -
only the release picker needs it.
Runtime dependencies (Linux): the GUI links wxWidgets 3.2 (wxGTK) and GTK 3, so
the target machine needs `libwxgtk3.2-1` and `libgtk-3-0` installed.
@@ -0,0 +1,53 @@
Subject: [PATCH 0011] Build on wxWidgets 3.2: version-guard the 3.3 appearance API and link GTK libs
diff -ruN a/build.rs b/build.rs
--- a/build.rs
+++ b/build.rs
@@ -309,6 +309,25 @@
for f in gtk_cflags.split_whitespace() {
build.flag(f);
}
+ // ...and GTK's own shared libraries at link time. `wx-config --libs`
+ // lists only the wx libraries, not the GTK libraries the widget bridge
+ // calls directly (gtk_*, g_*), so without this the final link fails with
+ // undefined GTK symbols. Best-effort: empty if pkg-config/gtk3-dev is
+ // missing, in which case the GTK-only bridge code was also compiled out.
+ let gtk_libs = Command::new("pkg-config")
+ .args(["--libs", "gtk+-3.0"])
+ .output()
+ .ok()
+ .filter(|o| o.status.success())
+ .and_then(|o| String::from_utf8(o.stdout).ok())
+ .unwrap_or_default();
+ for f in gtk_libs.split_whitespace() {
+ if let Some(lib) = f.strip_prefix("-l") {
+ println!("cargo:rustc-link-lib={}", lib);
+ } else if let Some(path) = f.strip_prefix("-L") {
+ println!("cargo:rustc-link-search=native={}", path);
+ }
+ }
}
if is_windows() {
// Ship one self-contained .exe: link the C++ runtime statically rather
diff -ruN a/cpp_src/wxbridge.cpp b/cpp_src/wxbridge.cpp
--- a/cpp_src/wxbridge.cpp
+++ b/cpp_src/wxbridge.cpp
@@ -375,6 +375,10 @@
// then returns CannotChange). System follows the desktop: the GTK theme's
// colour scheme, or the Windows 10/11 "app mode" setting, which wxMSW
// otherwise ignores and stays light. ALKANE_APPEARANCE=light|dark forces one.
+ // The explicit appearance API (wxApp::Appearance / SetAppearance /
+ // MSWEnableDarkMode) only exists in wxWidgets >= 3.3. On 3.2.x the GTK/Win
+ // system theme is still followed; we just cannot force it via ALKANE_APPEARANCE.
+#if wxCHECK_VERSION(3, 3, 0)
{
wxString pref;
wxGetEnv("ALKANE_APPEARANCE", &pref);
@@ -394,6 +398,7 @@
wxTheApp->SetAppearance(appearance);
#endif
}
+#endif
wxTheApp->OnInit();
#ifdef __WINDOWS__
+19
View File
@@ -309,6 +309,25 @@ fn build_with_wx_config() -> Result<(), Box<dyn Error>> {
for f in gtk_cflags.split_whitespace() {
build.flag(f);
}
// ...and GTK's own shared libraries at link time. `wx-config --libs`
// lists only the wx libraries, not the GTK libraries the widget bridge
// calls directly (gtk_*, g_*), so without this the final link fails with
// undefined GTK symbols. Best-effort: empty if pkg-config/gtk3-dev is
// missing, in which case the GTK-only bridge code was also compiled out.
let gtk_libs = Command::new("pkg-config")
.args(["--libs", "gtk+-3.0"])
.output()
.ok()
.filter(|o| o.status.success())
.and_then(|o| String::from_utf8(o.stdout).ok())
.unwrap_or_default();
for f in gtk_libs.split_whitespace() {
if let Some(lib) = f.strip_prefix("-l") {
println!("cargo:rustc-link-lib={}", lib);
} else if let Some(path) = f.strip_prefix("-L") {
println!("cargo:rustc-link-search=native={}", path);
}
}
}
if is_windows() {
// Ship one self-contained .exe: link the C++ runtime statically rather
@@ -375,6 +375,10 @@ extern "C" {
// then returns CannotChange). System follows the desktop: the GTK theme's
// colour scheme, or the Windows 10/11 "app mode" setting, which wxMSW
// otherwise ignores and stays light. ALKANE_APPEARANCE=light|dark forces one.
// The explicit appearance API (wxApp::Appearance / SetAppearance /
// MSWEnableDarkMode) only exists in wxWidgets >= 3.3. On 3.2.x the GTK/Win
// system theme is still followed; we just cannot force it via ALKANE_APPEARANCE.
#if wxCHECK_VERSION(3, 3, 0)
{
wxString pref;
wxGetEnv("ALKANE_APPEARANCE", &pref);
@@ -394,6 +398,7 @@ extern "C" {
wxTheApp->SetAppearance(appearance);
#endif
}
#endif
wxTheApp->OnInit();
#ifdef __WINDOWS__