Compare commits

...
Author SHA1 Message Date
noahandClaude Opus 4.8 d574118314 fix(gui): offer alkane install for the stock A113D (AML C76) board
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 30m58s
verify / verify-windows (pull_request) Successful in 19m55s
The right-click "Install alkane OS..." item never appeared for a stock
Amlogic A113D (Antminer BHB42XXX). board_family(), which gates the menu
via install_supported(), recognized only the Xilinx/Zynq S17 control
board, so it returned None for the A113D and the menu offered nothing.

Two things combined to hide it, both visible in a live scan of the bench
board at 10.255.1.18:

    brand=Unknown  model="Unknown: ANTMINER BHB42XXX"  board=AML (C76)

asic-rs has no make for the BHB42XXX, so the brand is "Unknown" and
board_family() bailed at the `!brand.contains("antminer")` guard before
any board-code check; and there was no AML -> a113d mapping anyway. Yet
SUPPORTED_BOARDS, the from-stock install engine (stock::install_from_stock
dispatches a113d -> aml_ubi) and the CLI's SUPPORTED list all already
support a113d -- only this detection gate was stale.

Map the "AML (C76)" control board (the a113d identity; board_labels
already maps a113d -> ("AML","C76")) directly to "a113d", ahead of the
brand guard, since this board legitimately reports no brand. The "AML"
code is only ever derived for an Amlogic Antminer control board, so it is
specific on its own. CBE (140mm S19k/S21-class) is deliberately not
mapped.

Verified against the bench A113D: live scan now reports install=true, and
a headless stock->alkane->stock cycle through the GUI operation layer
(ALKANE_BENCH_SEQUENCE) on the released v0.1.0-a113d-bench1 image passes
(install -> dropbear_2026.93 -> flag-restore -> dropbear_2018.76).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-17 09:33:52 -06:00
noah 0873d2c79d Merge pull request 'a113d: headless-GUI bench driver + A113D GUI install/restore (full cycle passes on hardware)' (#53) from feat/a113d-headless-bench into main
build-test-release / windows (push) Successful in 19m20s
build-test-release / release (push) Successful in 34m7s
2026-11-16 22:50:51 -07:00
noahandClaude Opus 4.8 12a11edfd7 style: rustfmt the A113D GUI install + headless bench driver
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 13m48s
verify / verify-windows (pull_request) Successful in 10m44s
cargo fmt -p alkane-gui; no logic change. This branch's CI never ran before
(its verify was skipped), so the formatting was never enforced.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 22:46:43 -06:00
noahandClaude Opus 4.8 71ab5a957c fix(gui): bench driver uses the alkane root credential for the restore leg
The flag-restore reaches the running alkane board over SSH as root, which is a
different credential from the stock login used for install. Alkane bench images
bake root/alkane; pass that (overridable via ALKANE_ROOT_PASSWORD) to the
restore, and keep the saved board SSH credential for the install. The previous
single-credential handoff sent the stock login to the alkane root restore and
hit "Permission denied".

Hardware note (2026-11-16): the PHY-fixed afw installs and comes up REACHABLE on
alkane (both the image PHY fix and the driver's MAC rediscovery proven); the
in-band flag-restore still needs the alkane DTB to expose the `misc` MTD (it
currently exposes only nvdata), tracked separately.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 22:42:05 -06:00
noahandClaude Opus 4.8 f6c740bc24 fix(gui): headless bench driver re-finds the board by MAC across reboots
The A113D can take a different DHCP lease (or lose its v4 lease) across the
install/restore reboots, so assuming the board keeps its initial IP broke the
verify/restore steps. Resolve the board's MAC up front (on stock) and, after
each reboot, re-locate it in the neighbour table (sweeping the /24 when it is
not cached) so verify and the flag-restore target the board's CURRENT address.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 22:42:05 -06:00
noahandClaude Opus 4.8 968173095e feat(gui): A113D install support + flag-restore + headless bench driver
- stock_ops: add "a113d" to SUPPORTED_BOARDS so the GUI offers A113D install
  (it was zynq-7010 only); add start_restore_flag() - the A113D restore is the
  in-band ALAN flag flip (install overwrites no stock partition), which the GUI
  lacked a clean path for (start_restore needs a firmware file, which the A113D
  ignores).
- bench_sequence (new) + main.rs ALKANE_BENCH_SEQUENCE: a headless driver that
  drives the real GUI operation layer (start_install(AfwSource::Local) -> verify
  -> start_restore_flag) through the A113D network-only install<->restore cycle,
  no wx window. Classifies stock vs alkane by SSH dropbear version / HTTP.

Hardware status (bench A113D, 2026-11-16): the install leg is PROVEN on real
hardware via the GUI operation layer. The verify/restore legs are NOT yet
validated end-to-end because the 0.1.0 a113d alkane image does not fully boot on
the bench board (kernel+eth up, no DHCP/SSH) - an alkane-os image bringup issue,
tracked separately. Known limitation: the driver assumes the board keeps its IP
across reboots; it should re-discover the board (A113D can change/lose its lease
under alkane). Not released pending a working image + the discovery fix.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 22:42:05 -06:00
noah 63c603d919 Merge pull request #52: readable network-only stock<->alkane install/restore for a113d (and zynq)
build-test-release / windows (push) Successful in 9m46s
build-test-release / release (push) Successful in 21m55s
2026-11-16 21:40:11 -07:00
noahandClaude Opus 4.8 fdb9bedb03 fix(flash): compile the zynq_nand temp-file writer on non-unix targets
source / check (pull_request) Skipped
verify / verify (pull_request) Successful in 10m9s
verify / verify-windows (pull_request) Successful in 11m31s
The Windows-target clippy gate (verify-windows) failed: zynq_nand's
write_private was #[cfg(unix)] only, but TempFile::with calls it
unconditionally, so on x86_64-pc-windows-gnu it was E0425 (not found), and the
module-top `use std::io::Write as _` / `use std::path::Path` then read as
unused. aml_ubi already handles this with a #[cfg(not(unix))] std::fs::write
fallback; mirror that here, and move the Write import into the unix branch that
uses it (as aml_ubi does) so neither import is unused on Windows.

Verified: native clippy -D warnings clean, and the CI Windows command
`cargo clippy --workspace --exclude alkane-gui --exclude wx-rs --all-targets
--target x86_64-pc-windows-gnu -- -D warnings` now passes (exit 0).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 22:09:04 -06:00
noahandClaude Opus 4.8 4be4750aae test(report-relay): seed the label cache instead of a live in-test fetch
verify / verify-windows (pull_request) Failing after 5m42s
verify / verify (pull_request) Successful in 10m8s
source / check (pull_request) Skipped
v5/v6 still failed in CI on the labels assertion. Root cause pinned down: the
relay resolves labels with a second server-to-server GET made from inside its
own request thread (relay server thread -> mock server thread), and that GET
failed reliably under the CI runner while the issue-filing POST on the same
path succeeded. Gitea.label_ids() swallows the fetch error and falls back to
[], so the issue was filed with no labels ([] != [3, 9]). Priming via the same
live GET in setUp only moved the failing call, not removed it.

Fix: seed the relay client's label cache directly from a shared REPO_LABELS
fixture (also what the mock serves), so no label GET happens during a test. The
name->id mapping is still exercised and the issue-filing POST stays live.
Verified 20/20 locally.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 21:40:17 -06:00
noahandClaude Opus 4.8 165b11bda3 test(report-relay): prime the label cache so the asserted path never refetches
verify / verify (pull_request) Failing after 9m27s
verify / verify-windows (pull_request) Skipped
source / check (pull_request) Skipped
The first relay test was flaky in CI (labels [] != [3,9]). Root cause:
Gitea.label_ids() fetches lazily on the first report and silently falls back
to [] on any fetch error; under CI load that first live fetch -- happening
inside the asserted POST -- intermittently raced the mock server thread and
dropped the labels. The earlier readiness probe only proved reachability at
setUp, not during the POST.

Fix: fetch labels once in setUp, while the mock is known-reachable, with a
bounded retry. label_ids caches for 10 minutes, so every request handler now
resolves labels from cache and the live fetch is off the asserted path.
Verified 25/25 clean and 12/12 under 2x CPU oversubscription.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 21:19:46 -06:00
noahandClaude Opus 4.8 e83bb8d2f1 test(report-relay): wait for the mock Gitea to serve before probing
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 9m29s
verify / verify-windows (pull_request) Skipped
The report-relay test's mock server binds in __init__ but runs
serve_forever on a daemon thread. Under CI load that thread can be
starved past the relay's HTTP timeout, so the first test's label fetch
returns [] and test_files_an_issue_with_title_body_and_labels fails
(labels [] != [3,9]). It passes locally and only the first test flaked,
which is the classic server-thread startup race.

Add a readiness probe in FakeGitea.__init__: poll the labels endpoint
until the serve_forever thread actually answers (5s budget) before the
test issues any relay request. Deterministic now (5/5 local runs green);
no production relay change. This surfaced only because #52's verify is
the first time this gate ran on the alkane-ci pool.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 17:59:14 -06:00
noahandClaude Opus 4.8 c0a647237a fix(clippy): satisfy -D warnings on the a113d flash engine
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 9m21s
verify / verify-windows (pull_request) Skipped
#52's verify never ran before (offline runner), so clippy -D warnings was
never enforced. Fix the Claude-domain lints:
  - aml_ubi.rs: use u64::div_ceil for the base64 length
  - zynq_nand.rs: elide needless lifetime; is_multiple_of; RangeInclusive
    ::contains for the slot bounds
and allow clippy::question_mark on the sealed stock_method module (its
internal layout is DSH-owned and not restyled here; the module already
carries a targeted allow list). No behavioural change.

Verified locally: cargo clippy --workspace --exclude alkane-gui --exclude
wx-rs --all-targets -- -D warnings is clean, and the non-gui test suite
passes. stock_method.rs is byte-for-byte unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 17:33:23 -06:00
noahandClaude Opus 4.8 9c49fa91af style: rustfmt the a113d flash engine + CLI (cargo fmt)
verify / verify (pull_request) Canceled after 0s
verify / verify-windows (pull_request) Canceled after 0s
source / check (pull_request) Skipped
#52's verify never actually ran before (the alkane-verify runner was
offline), so cargo fmt --check was never enforced on this branch. Apply
rustfmt to the three flagged files (alkane-cli main.rs, alkane-flash
aml_ubi.rs and zynq_nand.rs) to match the toolkit's CI fmt gate. No
behavioural change; vendored thirdparty/ is untouched (CI only formats
the named crates).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 17:28:37 -06:00
noahandClaude Opus 4.8 fbeb6dc328 ci(merge): keep verify-windows on the PR gate (alkane-ci) per the workflow contract
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 3m23s
verify / verify-windows (pull_request) Skipped
The merge resolution initially took #52's verify.yml, which drops the
verify-windows job; but ci/test-pr-surface.py enforces that verify.yml
carries verify-windows, and #52 never updated that contract, so the
verify gate failed with KeyError: 'verify-windows'. Take main's verify.yml
instead: both verify and verify-windows run on alkane-ci, matching the
contract. #52's flash-engine changes are unaffected.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-16 16:15:53 -06:00
noah 8180f4ff80 Merge remote-tracking branch 'origin/main' into feat/readable-stock-install-a113d-rebase
verify / verify (pull_request) Failing after 3m19s
source / check (pull_request) Skipped
# Conflicts:
#	.gitea/workflows/verify.yml
2026-11-16 16:08:35 -06:00
noah 9155c55d4c ci: repoint toolkit verify/source/badge to alkane-ci; keep Pages on the trusted verifier (#54)
build-test-release / release (push) Skipped
build-test-release / windows (push) Failing after 35m1s
2026-11-16 15:07:14 -07:00
noahandClaude Opus 4.8 be2eab6262 feat(flash): readable network-only stock<->alkane install/restore for a113d (and zynq)
source / check (pull_request) Skipped
verify / verify (pull_request) Canceled after 0s
a113d (Amlogic AXG, Antminer BHB42XXX) - VALIDATED end-to-end on bench hardware:
- aml_ubi.rs: stage the OS files into the nvdata UBIFS volume and drive a
  one-byte boot FLAG in misc block 1. Stock U-Boot `checkalk` raw-reads the flag
  (no UBI) and only on a magic match runs `alkboot` (ubifsload alkane + booti),
  else `storeboot` -> genuine stock. Install sets flag=ALAN from stock and writes
  the boot env in-band via /dev/nand_env (CRC-correct 64 KiB blob, read back
  byte-exact before reboot). Restore erases the flag block in-band from the
  running alkane OS and reboots - no stock firmware file needed, boot regions
  mtd0-5 never written. The magic is tested byte-by-byte (this vendor U-Boot's
  `itest.l *<mem>` mis-compares; `itest.b` works).
- stock.rs: dispatch board==a113d to aml_ubi for install_from_stock /
  restore_to_stock; add restore_aml_flag() for the firmware-free A113D restore.
- CLI: a113d is a supported install target; `afw restore-stock` works with no
  --stock-firmware for a113d (flag flip).

zynq-7010 readable path (install validated; restore awaits the NAND-ECC match):
- zynq_nand.rs + uimage.rs: uImage-wrapped NAND install-from-stock over the DSH
  root primitive, on-board stock backup carve/restore. Install is confirmed to
  persist and boot; restore-to-stock still needs stock-compatible ECC and is NOT
  presented as done.

stock_method.rs carries DSH-authored a113d root-on-stock support (sealed; method
not described here). 92/92 alkane-flash tests pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-14 00:43:30 -06:00
DeepSeek Harness 15df9086c1 feat(flash): expose root command and file primitives for stock boards
Add StockMethod::root_exec and StockMethod::root_put, with public wrappers next to the existing stock methods. root_exec runs a /bin/sh command line as root and returns combined output; root_put writes a payload at mode 0644 with parent directories created and supports multi-megabyte data. Existing install and restore paths are unchanged. Test coverage adds compile-level signature checks plus local path, quoting, and streamed-input tests; no test uses the network.
2026-11-13 15:21:44 -06:00
noahandClaude Opus 4.8 d2d4c085ae fix(gui): per-target credentials for install and restore (#46, #51)
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 31m29s
"Install failed due to credentials" was the #46 change pulling one generic
saved SSH login for both directions. Install targets a stock board and restore
targets an alkane board, which need different logins. Add the alkane
control-board login to the shipped defaults ("Alkane" root/alkane) and a
`cred_for(firmware)` helper (saved per-firmware override, else shipped default).

Install now uses the selected stock board's firmware login (e.g. AntMiner
root/root); restore and the on-board-backup probe use the alkane login
(root/alkane). No password field; both overridable per-firmware in Settings.
Confirmed on the bench S17 at 10.255.1.111: its alkane login is root/alkane.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 14:08:28 -06:00
noahandClaude Opus 4.8 6e785275da feat(gui): two-choice restore, dialogs-during-scan, creds-from-settings
source / check (pull_request) Skipped
verify / verify (pull_request) Canceled after 12m59s
Restore-to-stock dialog overhaul (issues #46, #47, #48, #51): a two-source
restore -- the board's on-board stock backup (checkbox, auto-detected via the
merged alkane-flash onboard_stock_backup_present and greyed out with
set_enabled when absent) or a Bitmain stock firmware file picked with a Browse
button (OTA .tar.gz or SD .zip, any X17-series model). The alkane root login
comes from Settings (no per-dialog password field); on-board restore uses the
new stock_ops::start_restore_onboard over DSH's restore_from_onboard_backup.

Install dialog: password field removed too (#46); the login comes from Settings.

Dialogs during scan (#43): install/uninstall dialogs open and can be prepared
while a scan runs (new flash_busy gate); the scan is stopped only when the
operation actually starts (stop_scan_for_op) so the two never touch a board at
once.

Bug report (#50): the always-present "Open issue" button is gone; filing turns
it into a clickable "View issue #N" link.

wx-rs: add set_enabled (grey out a control); captured as patch 0013. Merges
DSH's alkane-flash on-board backup/restore method (sealed in stock_method.rs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 13:53:28 -06:00
noah 9d49c4b070 Merge commit 'bccfaae2faf60a61c262ee472609cfd9c587b582' into fix/gui-install-and-scan-1113 2026-11-13 13:40:31 -06:00
noahandClaude Opus 4.8 dd3cff19cb ci(verify): drop verify-windows from the PR gate (Windows builds at release)
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 13m56s
The Windows mingw+Wine cross-build roughly doubled PR wall-clock. Move it off
the PR gate: PRs now verify Linux (clippy, build, tests, self-test) fast, and
the Windows build is still produced and shipped by the main release run
(build-test-release / windows-native), so a Windows-only regression surfaces on
the merge to main.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 13:01:37 -06:00
noahandClaude Opus 4.8 25047a603a style(gui): rustfmt + clippy fixes for the review changes
source / check (pull_request) Skipped
verify / verify (pull_request) Canceled after 44m33s
verify / verify-windows (pull_request) Canceled after 0s
Apply cargo fmt to the edited gui sources and switch a board_status membership
check from iter().any() to contains() so `cargo fmt --check` and
`clippy -D warnings` (the verify CI gates) pass.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 12:15:41 -06:00
noahandClaude Opus 4.8 69dcedbd9c build(wx-rs): capture the word-wrap text-ctrl edit into the patch queue
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 8m11s
verify / verify-windows (pull_request) Skipped
The #37 wrap fix edited the vendored wx-rs tree (wxbr_text_ctrl_wrap in the C++
bridge + text_ctrl_wrapped in widgets.rs) but not the patch queue, so the
`wx_rs_patches.py check` CI gate failed. Capture the delta as patch 0012 so the
queue reproduces the patched tree again.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 12:02:38 -06:00
DeepSeek Harness bccfaae2fa flash: restore the Zynq from its on-board stock backup
A from-stock install now leaves a complete genuine-stock backup on the
board (stock device tree, kernel and ramdisk) in the reserved NAND region
after the alkane MAC area, clear of the stock configs UBI and all alkane
boot slots.

Add network-only StockMethod calls to check for that backup and restore
the board to genuine stock from it, with public wrappers and interface
tests. BOOT.bin is preserved.

Verified: cargo build -p alkane-flash; cargo test -p alkane-flash
(74 passed, 1 ignored).
2026-11-13 11:45:16 -06:00
noahandClaude Opus 4.8 7cd26aff56 fix(gui): address code-review findings on the install/scan changes
verify / verify (pull_request) Failing after 5m53s
verify / verify-windows (pull_request) Skipped
source / check (pull_request) Skipped
- #1 Update must not rewrite the bootloader: start_install refuses a tier-3
  (bootloader-writing) .afw when the dialog is an in-place Update, enforcing the
  "BOOT.bin is never written" guarantee.
- #2 post-install verify could stick forever when auto-scan is off: tick() now
  re-probes awaiting boards on a fixed 10 s cadence until they answer as alkane
  or the give-up window expires.
- #3 board-health no longer greys a genuinely-mining miner whose backend omits
  per-board active/working_chips: (None,None) reads green when the miner is
  hashing, grey only when idle (the bare S17 case).
- #5 install docs/comments no longer describe the removed typed-FLASH step.
- #6 the flash-plan checklist verifies against the install target board, so a
  file for another board surfaces as an error instead of a misleading plan.
- #7 install board is taken from the selected row's board_family, not a fixed
  default (correct once more boards are supported).
- #4 (verify on the UI thread) accepted: .afw bundles are ~7 MB, so the manifest
  read is a sub-100 ms hash, not a user-visible freeze.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 11:22:00 -06:00
noahandClaude Opus 4.8 4f59233064 feat(gui): live activity-log view toggled from the toolbar
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 7m4s
verify / verify-windows (pull_request) Skipped
A "Log" toolbar button replaces the fleet table with a live view of the
toolkit activity log (what it is currently doing); the button flips to "Table"
to switch back. The view tails the log, appending new lines and staying
scrolled to the newest entry. Verified under a virtual display.

Placed in the toolbar (top-right) rather than the status bar: the native wx
status bar that holds the zoom slider cannot host a wx button, and the content
sizer has no insert, so a true bottom-right button needs extra plumbing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 11:06:56 -06:00
noahandClaude Opus 4.8 7e0174fda1 feat(gui): progress bar in the Health cell during install/restore (#42)
source / check (pull_request) Skipped
verify / verify-windows (pull_request) Canceled after 0s
verify / verify (pull_request) Canceled after 4m10s
While a board installs or restores, its Health cell shows a phase-based ASCII
progress bar ("installing [#######---] 70%") instead of a static "installing".
Phases map to indicative, monotonic percents (acquire < verify < write). Adds
unit tests for the bar and the phase->percent mapping.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 11:01:23 -06:00
noahandClaude Opus 4.8 7d5f250254 feat(gui): install picker reads any repo with board-compat filtering
verify / verify-windows (pull_request) Canceled after 0s
source / check (pull_request) Skipped
verify / verify (pull_request) Canceled after 1m5s
The install dialog gains a "Release repo (owner/repo)" field (default
blueflare/alkane-os) and a Reload button. Releases are scanned from the chosen
repo via ReleaseSource::for_repo and filtered to those with an .afw compatible
with the target board (ReleaseInfo::is_compatible_with). Verified under a
virtual display: the picker populates with the alkane-os release unauthenticated
now that the repo is public, and the repo field + Reload render.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 10:59:10 -06:00
noahandClaude Opus 4.8 fbf44889ea feat(gui): post-install verify, flash-plan checklist; backend helpers
source / check (pull_request) Skipped
verify / verify (pull_request) Canceled after 2m0s
verify / verify-windows (pull_request) Canceled after 0s
Stock->alkane re-scan flicker: after a successful install the just-installed
boards are held in a "verifying alkane..." state and a stock re-scan row is
suppressed until the board answers as alkane, with a bounded give-up window.
Fixes the board re-scanning as stock before finally showing alkane.

Flash-plan checklist: picking a local .afw in the install dialog now detects
the flash tier and shows a [x]/[ ] checklist of what it overwrites (U-Boot /
Kernel / Userspace), read from the bundle manifest. Verified end-to-end under
a virtual display: a zynq-7010 .afw shows tier 2, U-Boot preserved, kernel and
userspace written.

Backend helpers (alkane-artifacts, additive, unit-tested):
- AfwManifest::flash_plan() -> FlashPlan { tier, writes_uboot, writes_kernel,
  writes_userspace }.
- ReleaseSource::for_repo(owner, repo) and ReleaseInfo::compatible_boards /
  is_compatible_with, for the upcoming any-repo picker with board-compat
  detection.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 10:56:04 -06:00
noahandClaude Opus 4.8 f9cd12b374 feat(gui): drop typed-FLASH step; raise report-relay rate limit
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 8m16s
verify / verify-windows (pull_request) Skipped
Issue #41: installing alkane OS and restoring to stock no longer require
typing FLASH. The dialog, the board list and the Install/Restore button are
the confirmation; the destructive-action warning stays visible. Removes the
now-unused confirm inputs from the install and uninstall dialogs.

Report relay: raise RATE_PER_IP 5 -> 100 and RATE_GLOBAL 60 -> 300 so bench
testing can file more reports without hitting the hourly cap. Applied live on
the Gitea host and recorded here.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 10:18:36 -06:00
noahandClaude Opus 4.8 aab9b63350 fix(gui): install feedback, local .afw picker, scan icons, report wrap
source / check (pull_request) Skipped
verify / verify (pull_request) Failing after 10m54s
verify / verify-windows (pull_request) Skipped
Addresses the bench bug reports filed from the toolkit (issues #37, #38, #39)
and the request for a local-file install source.

Install (issue #38): the install never reached the worker in the reported
case and aborts were only a status-bar line, so the operator saw nothing.
Abort reasons (missing FLASH keyword, no release/asset, no target) now raise
the visible error indicator and keep the dialog open; the actual per-board
failure detail is surfaced and logged instead of a bare count; a clear
"installing..." line and log entry mark the start.

Install source (requested): the install dialog gains a "Browse local .afw"
button beside the Gitea release picker, in the same window. A chosen file
takes precedence over the selected release. start_install takes an AfwSource
(Release or Local); a local file is used in place, a release is downloaded as
before. This brings the CLI's local-file install to the GUI.

Scan icons (issue #39): a hashboard the firmware lists with no active flag and
no working-chip count now reads grey (not detected) instead of green, and the
PSU bolt greens only on real delivery evidence (watts, PSU fan, or PSU output)
-- is_mining counts only when the miner is actually hashing. A stock S17
control board with no PSU or hashboards attached asserts a cgminer mining
status at zero watts, which previously showed green board and PSU icons.
Confirmed against the bench S17 at 10.255.1.111 (reports watts=0). Regression
tests added for both.

Bug report (issue #37): the report box word-wraps instead of running off the
edge (new wx text_ctrl_wrapped without wxTE_DONTWRAP). Sub-window movability
is window-manager behaviour (the dialog already has a caption and resize
border) and is not changed here.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
2026-11-13 09:45:46 -06:00
noah 224b3b37e8 Merge pull request 'main: find Alkane OS boards in the scan; install/update/uninstall only where they apply' (#36) from next into main
build-test-release / release (push) Successful in 21m54s
build-test-release / windows (push) Successful in 32m55s
2026-11-12 15:42:14 -07:00
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
28 changed files with 6153 additions and 343 deletions
+1 -1
View File
@@ -11,7 +11,7 @@ concurrency:
jobs:
publish:
runs-on: alkane-verify
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
permissions:
+1 -1
View File
@@ -7,7 +7,7 @@ on:
jobs:
publish:
runs-on: alkane-verify
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
permissions:
+1 -1
View File
@@ -11,7 +11,7 @@ concurrency:
jobs:
check:
runs-on: alkane-fast
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
env:
+2 -2
View File
@@ -11,7 +11,7 @@ concurrency:
jobs:
verify:
runs-on: alkane-verify
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
outputs:
@@ -202,7 +202,7 @@ jobs:
verify-windows:
needs: verify
if: needs.verify.outputs.surface == 'full'
runs-on: alkane-verify
runs-on: alkane-ci
container:
image: gitea.bluefla.re/blueflare/alkane-ci@sha256:4929b2979851f1f12fb8f92ef74236ae4c2ea735a41ead94a16af416a4f0a1a5
env:
+148
View File
@@ -155,6 +155,54 @@ pub struct AfwManifest {
pub notes: Option<String>,
}
/// What an `.afw` bundle overwrites on the target, derived from its manifest.
///
/// Tiers mirror the flash tiers: 1 = update (userspace / HAL only, no kernel or
/// bootloader write), 2 = kernel (kernel, dtb and boot images; bootloader
/// preserved), 3 = bootloader (U-Boot/SPL is rewritten as well).
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct FlashPlan {
pub tier: u8,
pub writes_uboot: bool,
pub writes_kernel: bool,
pub writes_userspace: bool,
}
impl AfwManifest {
/// Compute the flash tier and the regions this bundle overwrites. Pure
/// computation over the parsed manifest; no device or file access.
///
/// - `writes_uboot`: `bootloader_policy` is [`BootloaderPolicy::Include`]
/// (anything but `Preserve`), or an image with role `bootloader` exists.
/// - `writes_kernel`: an image with role `kernel`, `dtb` or `boot` exists.
/// - `writes_userspace`: an image with role `rootfs` exists.
/// - `tier`: 3 if `writes_uboot`, else 2 if `writes_kernel`, else 1.
pub fn flash_plan(&self) -> FlashPlan {
let has_role = |roles: &[&str]| {
self.images
.iter()
.any(|image| roles.contains(&image.role.as_str()))
};
let writes_uboot =
self.bootloader_policy != BootloaderPolicy::Preserve || has_role(&["bootloader"]);
let writes_kernel = has_role(&["kernel", "dtb", "boot"]);
let writes_userspace = has_role(&["rootfs"]);
let tier = if writes_uboot {
3
} else if writes_kernel {
2
} else {
1
};
FlashPlan {
tier,
writes_uboot,
writes_kernel,
writes_userspace,
}
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct AfwMember {
pub name: String,
@@ -1080,6 +1128,106 @@ mod tests {
));
}
/// Build a parsed manifest with the given bootloader policy and one image
/// per listed role (payload bytes are irrelevant to `flash_plan`).
fn plan_manifest(policy: &str, roles: &[&str]) -> AfwManifest {
let mut value = manifest(&[0_u8; 4]);
value["bootloader_policy"] = json!(policy);
value["images"] = json!(roles
.iter()
.enumerate()
.map(|(i, role)| json!({
"name": format!("img{i}"), "file": format!("payload/img{i}"),
"role": role, "format": "raw", "size": 4, "sha256": "0".repeat(64),
"partition": null, "install": false
}))
.collect::<Vec<_>>());
serde_json::from_value(value).unwrap()
}
#[test]
fn flash_plan_tier2_preserve_kernel_and_rootfs() {
let plan = plan_manifest("preserve", &["kernel", "dtb", "rootfs"]).flash_plan();
assert_eq!(plan.tier, 2);
assert!(plan.writes_kernel);
assert!(plan.writes_userspace);
assert!(!plan.writes_uboot);
}
#[test]
fn flash_plan_tier3_include_with_bootloader_image() {
let plan =
plan_manifest("include", &["bootloader", "kernel", "dtb", "rootfs"]).flash_plan();
assert_eq!(plan.tier, 3);
assert!(plan.writes_uboot);
assert!(plan.writes_kernel);
assert!(plan.writes_userspace);
}
#[test]
fn flash_plan_tier3_from_bootloader_image_alone() {
// A bootloader image forces tier 3 even if the policy says preserve
// (verification rejects that combination, but the plan stays safe).
let plan = plan_manifest("preserve", &["bootloader"]).flash_plan();
assert_eq!(plan.tier, 3);
assert!(plan.writes_uboot);
assert!(!plan.writes_kernel);
assert!(!plan.writes_userspace);
}
#[test]
fn flash_plan_tier3_from_include_policy_alone() {
let plan = plan_manifest("include", &["rootfs"]).flash_plan();
assert_eq!(plan.tier, 3);
assert!(plan.writes_uboot);
assert!(!plan.writes_kernel);
assert!(plan.writes_userspace);
}
#[test]
fn flash_plan_tier1_rootfs_only() {
let plan = plan_manifest("preserve", &["rootfs"]).flash_plan();
assert_eq!(plan.tier, 1);
assert!(plan.writes_userspace);
assert!(!plan.writes_kernel);
assert!(!plan.writes_uboot);
}
#[test]
fn flash_plan_boot_role_counts_as_kernel() {
let plan = plan_manifest("preserve", &["boot"]).flash_plan();
assert_eq!(plan.tier, 2);
assert!(plan.writes_kernel);
assert!(!plan.writes_userspace);
assert!(!plan.writes_uboot);
// The shared cv1835 fixture is a single "boot" FIT under preserve.
let fixture: AfwManifest = serde_json::from_value(manifest(&[0_u8; 4])).unwrap();
assert_eq!(fixture.flash_plan().tier, 2);
}
#[test]
fn flash_plan_component_only_is_tier1_with_no_regions() {
let plan = plan_manifest("preserve", &["component"]).flash_plan();
assert_eq!(plan.tier, 1);
assert!(!plan.writes_uboot);
assert!(!plan.writes_kernel);
assert!(!plan.writes_userspace);
}
#[test]
fn flash_plan_empty_images_preserve_is_tier1() {
let plan = plan_manifest("preserve", &[]).flash_plan();
assert_eq!(plan.tier, 1);
assert!(!plan.writes_uboot && !plan.writes_kernel && !plan.writes_userspace);
}
#[test]
fn flash_plan_tier3_dominates_kernel() {
let plan = plan_manifest("include", &["bootloader", "kernel"]).flash_plan();
assert_eq!(plan.tier, 3);
assert!(plan.writes_uboot && plan.writes_kernel);
}
#[test]
fn refuses_a_hash_mismatch() {
let p1 = p1_image(P1);
+126 -2
View File
@@ -60,6 +60,14 @@ 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 {
Self::for_repo("blueflare", "alkane-os")
}
/// A release source for an arbitrary Gitea `owner`/`repo`. The base URL
/// (`ALKANE_RELEASE_BASE`, else the self-hosted Gitea) and the token
/// (`ALKANE_RELEASE_TOKEN`, else `GITEA_TOKEN`, else the build-time embedded
/// token) are resolved exactly as for `alkane_os`.
pub fn for_repo(owner: &str, repo: &str) -> Self {
let base_url = std::env::var("ALKANE_RELEASE_BASE")
.ok()
.filter(|s| !s.is_empty())
@@ -71,8 +79,8 @@ impl ReleaseSource {
.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(),
owner: owner.to_string(),
repo: repo.to_string(),
token,
}
}
@@ -223,6 +231,18 @@ pub fn fetch_latest_afw(
Ok(dest)
}
/// Board tokens recognised in `.afw` asset names (the `-<board>-` filename
/// segment). Used by `ReleaseInfo::compatible_boards`.
pub const KNOWN_BOARDS: &[&str] = &[
"zynq-7010",
"am335x",
"cv1835",
"a113d",
"allwinner-h3",
"allwinner-h6",
"allwinner-h616",
];
/// One `.afw` asset in a release.
#[derive(Debug, Clone)]
pub struct AfwAsset {
@@ -249,6 +269,30 @@ impl ReleaseInfo {
let needle = format!("-{board}-");
self.afw_assets.iter().find(|a| a.name.contains(&needle))
}
/// The distinct board tokens (from `KNOWN_BOARDS`) this release carries an
/// `.afw` for, detected from the asset filenames (`-<board>-` segment, e.g.
/// `alkane-os-0.1.2-zynq-7010-armv7.afw` -> `zynq-7010`). Ordered by first
/// appearance across the assets; a release with no recognised board yields an
/// empty list.
pub fn compatible_boards(&self) -> Vec<String> {
let mut boards: Vec<String> = Vec::new();
for asset in &self.afw_assets {
for board in KNOWN_BOARDS {
let needle = format!("-{board}-");
if asset.name.contains(&needle) && !boards.iter().any(|b| b == board) {
boards.push((*board).to_string());
}
}
}
boards
}
/// Whether this release has an `.afw` for `board` (same match as
/// `asset_for_board`).
pub fn is_compatible_with(&self, board: &str) -> bool {
self.asset_for_board(board).is_some()
}
}
/// Parse a Gitea releases array (newest first) into `ReleaseInfo`s, keeping only
@@ -401,4 +445,84 @@ mod tests {
);
assert!(parsed[1].asset_for_board("zynq-7010").is_none());
}
#[test]
fn for_repo_builds_the_api_url_for_a_custom_repo() {
std::env::remove_var("ALKANE_RELEASE_BASE");
let src = ReleaseSource::for_repo("someorg", "some-firmware");
assert_eq!(src.owner, "someorg");
assert_eq!(src.repo, "some-firmware");
assert_eq!(
src.api_list(),
"https://gitea.bluefla.re/api/v1/repos/someorg/some-firmware/releases?limit=50"
);
// alkane_os() is for_repo("blueflare", "alkane-os").
let os = ReleaseSource::alkane_os();
assert_eq!(
(os.owner.as_str(), os.repo.as_str()),
("blueflare", "alkane-os")
);
}
fn release_with(names: &[&str]) -> ReleaseInfo {
ReleaseInfo {
tag: "v0.1.2".into(),
name: String::new(),
prerelease: false,
draft: false,
published_at: String::new(),
afw_assets: names
.iter()
.map(|n| AfwAsset {
name: (*n).to_string(),
url: format!("https://example.invalid/{n}"),
})
.collect(),
}
}
#[test]
fn compatible_boards_extracts_board_tokens_from_asset_names() {
let single = release_with(&["alkane-os-0.1.2-zynq-7010-armv7.afw"]);
assert_eq!(single.compatible_boards(), vec!["zynq-7010"]);
// Multi-board release: distinct boards in first-appearance order,
// duplicates (a second arch build of one board) collapse.
let multi = release_with(&[
"alkane-os-0.1.2-am335x-armv7.afw",
"alkane-os-0.1.2-zynq-7010-armv7.afw",
"alkane-os-0.1.2-allwinner-h616-aarch64.afw",
"alkane-os-0.1.2-am335x-arm.afw",
"alkane-os-0.1.2-cv1835-riscv64.afw",
]);
assert_eq!(
multi.compatible_boards(),
vec!["am335x", "zynq-7010", "allwinner-h616", "cv1835"]
);
// allwinner-h6 must not match an allwinner-h616 asset (and vice versa).
let h616 = release_with(&["alkane-os-0.1.2-allwinner-h616-aarch64.afw"]);
assert_eq!(h616.compatible_boards(), vec!["allwinner-h616"]);
let h6 = release_with(&["alkane-os-0.1.2-allwinner-h6-aarch64.afw"]);
assert_eq!(h6.compatible_boards(), vec!["allwinner-h6"]);
// No .afw assets, or an unrecognised board, yields nothing.
assert!(release_with(&[]).compatible_boards().is_empty());
assert!(release_with(&["alkane-os-0.1.2-mystery-board-arm.afw"])
.compatible_boards()
.is_empty());
}
#[test]
fn is_compatible_with_matches_asset_for_board() {
let rel = release_with(&[
"alkane-os-0.1.2-zynq-7010-armv7.afw",
"alkane-os-0.1.2-a113d-aarch64.afw",
]);
assert!(rel.is_compatible_with("zynq-7010"));
assert!(rel.is_compatible_with("a113d"));
assert!(!rel.is_compatible_with("am335x"));
assert!(!rel.is_compatible_with("allwinner-h6"));
assert!(!release_with(&[]).is_compatible_with("zynq-7010"));
}
}
+257 -7
View File
@@ -23,6 +23,7 @@ use alkane_flash::stock;
use alkane_flash::stock::{InPlaceOptions, InPlaceOutcome, RestoreImages};
use alkane_flash::stock_firmware;
use alkane_flash::transport::{Remote, RootMethod, SshOptions, SshTransport};
use alkane_flash::zynq_nand;
use std::collections::{BTreeMap, BTreeSet};
use std::fs;
use std::path::{Path, PathBuf};
@@ -1039,8 +1040,13 @@ fn latest_backup(dir: &Path) -> Option<PathBuf> {
/// Boards this toolkit can install alkane onto, with the miner each is the
/// control board for. The install/restore gate is the .afw's board matching one
/// of these; `compat` lists them so an operator knows what is supported.
const SUPPORTED: &[(&str, &str)] =
&[("zynq-7010", "Antminer S17 (Xilinx Zynq-7010 control board)")];
const SUPPORTED: &[(&str, &str)] = &[
("zynq-7010", "Antminer S17 (Xilinx Zynq-7010 control board)"),
(
"a113d",
"Antminer BHB42XXX / S19k Pro (Amlogic A113D/AXG control board)",
),
];
fn is_supported(board: &str) -> bool {
SUPPORTED.iter().any(|(b, _)| *b == board)
@@ -1112,14 +1118,48 @@ fn run_restore_stock(args: &[String]) -> Result<(), Box<dyn std::error::Error>>
&["dry-run"],
)?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let firmware = opts.value("stock-firmware").ok_or(
"--stock-firmware <genuine Bitmain firmware file> is required \
(an OTA update .tar.gz or an SD recovery .zip for this board)",
)?;
// Restore reaches the alkane board over SSH as root; the board credential is
// supplied via --password-file / ALKANE_BOARD_PASSWORD(_FILE).
let password = read_board_password(&opts)?;
// A113D restores with NO stock firmware file: it is a one-byte boot-flag flip
// in-band from the running alkane OS (the genuine stock in the untouched boot
// partition is booted via storeboot). Try that first when no firmware is
// given; if the board is not an alkane A113D, require --stock-firmware.
let firmware = match opts.value("stock-firmware") {
Some(f) => f,
None => {
if opts.flag("dry-run") {
println!("DRY RUN: would restore {host} to stock by flipping the A113D boot flag");
println!(
"(no stock firmware needed; the untouched stock boot partition is booted)."
);
println!("Re-run with --confirm FLASH.");
return Ok(());
}
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to restore without --confirm FLASH".into());
}
println!("restoring {host} to genuine stock (A113D flag flip, network-only)...");
match stock::restore_aml_flag(&host, password.as_deref()) {
Ok(()) => {
println!(
"restore reported success (boot flag cleared; stock boots via storeboot)."
);
println!("verify independently: the board should present genuine stock");
println!("(cgminer API on :4028, lighttpd 401 on :80, dropbear 2018.x).");
return Ok(());
}
Err(alkane_flash::stock::StockError::NotApplicable) => {
return Err("this board is not an alkane A113D; pass --stock-firmware \
<genuine Bitmain OTA .tar.gz or SD .zip> to restore it"
.into());
}
Err(e) => return Err(e.into()),
}
}
};
// Parse the genuine vendor package for the stock kernel + rootfs. The kernel
// device tree is not in distributable Bitmain firmware; the toolkit supplies
// the correct per-board dtb, so any genuine package (OTA or SD) works here.
@@ -1139,6 +1179,7 @@ fn run_restore_stock(args: &[String]) -> Result<(), Box<dyn std::error::Error>>
let images = RestoreImages {
kernel: &fw.kernel,
rootfs: &fw.rootfs,
dtb: fw.dtb.as_deref(),
};
stock::restore_to_stock(&host, &images, password.as_deref())?;
println!("restore-to-stock reported success (stock images written, BOOT.bin preserved).");
@@ -1147,9 +1188,209 @@ fn run_restore_stock(args: &[String]) -> Result<(), Box<dyn std::error::Error>>
Ok(())
}
/// Run a command as root on a stock board and print its output (drives the DSH
/// root-on-stock primitive; used to build and debug the flash operations).
fn run_root_run(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, ssh_values(), &[])?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let cmd = opts.positionals.join(" ");
if cmd.trim().is_empty() {
return Err("usage: alkane-cli afw root-run --host <ip> <command...>".into());
}
let password = read_board_password(&opts)?;
let out = stock::root_exec(&host, password.as_deref(), &cmd)?;
print!("{out}");
Ok(())
}
/// Readable zynq NAND install-from-stock: wrap the afw's zImage/rootfs as the
/// legacy uImages the stock U-Boot boots, carve the on-board genuine-stock
/// backup, write the boot slots and reboot. Drives the DSH root-on-stock
/// primitive; board must be on stock (credential root/root).
fn run_nand_install(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(
args,
&[ssh_values(), &["confirm"]].concat(),
&["allow-unsigned"],
)?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let afw_path = opts
.positionals
.first()
.ok_or("usage: alkane-cli afw nand-install <afw> --host <ip> --confirm FLASH")?;
let verified = load_afw(afw_path, &opts)?;
if !zynq::owns_board(&verified.manifest.board) {
return Err(format!(
"nand-install is zynq-7010 only, not {}",
verified.manifest.board
)
.into());
}
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to install without --confirm FLASH".into());
}
let kernel = verified
.image("kernel")
.ok_or("afw missing kernel image")?
.1;
let dtb = verified.image("dtb").ok_or("afw missing dtb image")?.1;
let rootfs = verified
.image("rootfs")
.ok_or("afw missing rootfs image")?
.1;
let password = read_board_password(&opts)?;
println!(
"installing {} onto stock board {host} (readable NAND path)...",
verified.manifest.board
);
zynq_nand::install_from_stock(&host, kernel, dtb, rootfs, password.as_deref())?;
println!(
"install reported success (on-board stock backup carved; boot slots written; rebooting)."
);
print!("{}", zynq_verify_hint(&host));
Ok(())
}
/// Readable zynq restore-to-stock: write the vendor stock kernel/dtb/rootfs
/// back to the boot slots over SSH (board on alkane). Needs the alkane image
/// that exposes the boot partitions.
fn run_nand_restore_stock(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(
args,
&[ssh_values(), &["confirm", "stock-firmware"]].concat(),
&["dry-run"],
)?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let firmware = opts
.value("stock-firmware")
.ok_or("--stock-firmware <file> is required")?;
let fw = stock_firmware::parse(Path::new(firmware))?;
println!("stock firmware: {}", fw.summary());
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to restore without --confirm FLASH".into());
}
let password = read_board_password(&opts)?;
println!("restoring {host} to genuine stock (readable NAND path)...");
zynq_nand::restore_to_stock(
&host,
&fw.kernel,
&fw.rootfs,
fw.dtb.as_deref(),
password.as_deref(),
)?;
println!(
"restore-to-stock reported success (stock kernel/dtb/rootfs written, BOOT.bin preserved)."
);
Ok(())
}
/// Readable zynq on-board backup check: report whether a restorable genuine-
/// stock backup is present (board on alkane). Read-only.
fn run_nand_backup_check(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, ssh_values(), &[])?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let password = read_board_password(&opts)?;
if zynq_nand::onboard_backup_present(&host, password.as_deref())? {
println!("on-board stock backup: PRESENT (restorable with nand-restore-onboard)");
} else {
println!("on-board stock backup: ABSENT");
}
Ok(())
}
/// Readable zynq restore-from-on-board-backup: copy the saved stock images back
/// to the boot slots (board on alkane), no vendor file needed.
fn run_nand_restore_onboard(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, &[ssh_values(), &["confirm"]].concat(), &[])?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to restore without --confirm FLASH".into());
}
let password = read_board_password(&opts)?;
println!("restoring {host} to stock from its on-board backup (readable NAND path)...");
zynq_nand::restore_from_onboard(&host, password.as_deref())?;
println!("restore-from-onboard reported success (stock images written, rebooting).");
Ok(())
}
/// Run a command as root on an alkane board over SSH and print its output
/// (the alkane-side analog of root-run; used to drive and debug the
/// alkane-side NAND operations: restore-to-stock and on-board backup/restore).
fn run_ssh_run(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, ssh_values(), &[])?;
let cmd = opts.positionals.join(" ");
if cmd.trim().is_empty() {
return Err("usage: alkane-cli afw ssh-run --host <ip> <command...>".into());
}
let (ssh, _secret) = ssh_options(&opts, "root")?;
let mut transport = SshTransport::connect(ssh, true)?;
let out = transport.root_command(&cmd, std::time::Duration::from_secs(120))?;
print!("{}", String::from_utf8_lossy(&out));
Ok(())
}
/// Stream a local file to a stock board as root (drives the DSH root-on-stock
/// primitive; used to stage kernel/rootfs images for the flash operations).
fn run_root_put(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, &[ssh_values(), &["remote"]].concat(), &[])?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let remote = opts
.value("remote")
.ok_or("--remote <path> is required")?
.to_owned();
let local = opts
.positionals
.first()
.ok_or("usage: alkane-cli afw root-put --host <ip> --remote <path> <local-file>")?;
let data = std::fs::read(local)?;
let password = read_board_password(&opts)?;
stock::root_put(&host, password.as_deref(), &data, &remote)?;
println!("put {} bytes -> {remote}", data.len());
Ok(())
}
/// Report whether an alkane board holds a restorable on-board stock backup.
/// Read-only (no FLASH confirmation).
fn run_backup_check(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, ssh_values(), &[])?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let password = read_board_password(&opts)?;
let present = stock::onboard_stock_backup_present(&host, password.as_deref())?;
println!("on-board stock backup present: {present}");
Ok(())
}
/// Restore an alkane board to genuine stock from its on-board backup (no vendor
/// firmware file). Destructive; gated by --confirm FLASH.
fn run_restore_onboard(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(args, &[ssh_values(), &["confirm"]].concat(), &["dry-run"])?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let password = read_board_password(&opts)?;
if opts.flag("dry-run") {
println!(
"DRY RUN: would restore {host} to stock from its on-board backup \
(BOOT.bin preserved). Re-run with --confirm FLASH."
);
return Ok(());
}
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to restore without --confirm FLASH".into());
}
println!("restoring {host} to stock from its on-board backup (network-only)...");
stock::restore_from_onboard_backup(
&host,
password.as_deref(),
std::time::Duration::from_secs(300),
)?;
println!(
"restore-from-onboard reported success. Verify independently the board answers as stock."
);
Ok(())
}
fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let subcommand = args.first().ok_or(
"usage: alkane-cli afw <compat|fetch-latest|verify|inspect|plan|preflight|install|verify-live|restore|restore-stock>",
"usage: alkane-cli afw <compat|fetch-latest|verify|inspect|plan|preflight|install|verify-live|restore|restore-stock|backup-check|restore-onboard>",
)?;
let rest = &args[1..];
match subcommand.as_str() {
@@ -1163,6 +1404,15 @@ fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
"verify-live" => run_verify_live(rest),
"restore" => run_restore(rest),
"restore-stock" => run_restore_stock(rest),
"backup-check" => run_backup_check(rest),
"restore-onboard" => run_restore_onboard(rest),
"root-run" => run_root_run(rest),
"root-put" => run_root_put(rest),
"ssh-run" => run_ssh_run(rest),
"nand-install" => run_nand_install(rest),
"nand-restore-stock" => run_nand_restore_stock(rest),
"nand-backup-check" => run_nand_backup_check(rest),
"nand-restore-onboard" => run_nand_restore_onboard(rest),
other => Err(format!("unknown afw subcommand {other}").into()),
}
}
+660
View File
@@ -0,0 +1,660 @@
// SPDX-License-Identifier: MIT
//! Readable Amlogic A113D (Amlogic AXG, Antminer BHB42XXX) install/restore over
//! the FLAG-BASED boot chain. This is the Claude-domain counterpart of
//! `zynq_nand`: it drives the DSH root-on-stock primitive (`stock::root_exec` /
//! `stock::root_put`) for the from-stock install, and the alkane SSH transport
//! for the in-band restore, with the stock-access method never read here.
//!
//! Mechanism (CONFIRMED live 2026-11-13, see alkane-sdk-construction
//! alkane-a113d-image-bringup):
//!
//! - The OS files `alkane/{vmlinux.bin,devicetree.dtb,uramdisk.image.gz}` are
//! staged into the nvdata UBI volume (UBIFS), exactly as the alkane boot chain
//! reads them (`ubifsload`). Zero raw writes to the brick-sensitive regions.
//! - A one-byte-magic FLAG lives in the `misc` partition (the Android BCB block,
//! abs NAND 0x1000000) at erase-block 1 (offset 0x20000, abs 0x1020000). Block
//! 0 (the BCB) is never touched. The flag is the four bytes "ALAN".
//! - Stock U-Boot's `bootcmd` is set (once, in-band via /dev/nand_env from stock)
//! to `run checkalk; run storeboot`, where `checkalk` RAW-reads the flag page
//! (`nand read`, NO UBI) and, only if the magic matches, runs `alkboot` (which
//! mounts the nvdata UBIFS and boots alkane). When the flag is absent the stock
//! path is a pure raw read + `storeboot`, which boots genuine stock STABLY (a
//! ubi/ubifs op in the stock boot path instead makes stock's firstboot
//! supervisor reboot-loop - that is why the flag read must be raw).
//! - INSTALL (stock -> alkane): stage the files, write the env, set flag=ALAN.
//! - RESTORE (alkane -> stock): erase the flag block in-band from the running
//! alkane OS (which exposes `misc` as an MTD). One raw NAND erase, `reboot -f`,
//! and stock boots via `storeboot`. Fully network-only; the alkane payload and
//! the env are left in place, so re-install is just re-writing the flag.
//!
//! itest note: this vendor U-Boot's `itest.l *<mem>` does NOT compare correctly,
//! but `itest.b *<mem>` does, so `checkalk` tests the four magic bytes with
//! nested `itest.b`. CONFIRMED live 2026-11-13.
use crate::stock::StockError;
use crate::transport::{Remote, SshOptions, SshTransport};
use crate::uimage::crc32;
use std::path::{Path, PathBuf};
use std::time::Duration;
pub const BOARD: &str = "a113d";
/// U-Boot env blob size on this board (CONFIRMED: `/dev/nand_env` is 64 KiB, a
/// standard U-Boot env = 4-byte little-endian CRC32 + NUL-separated key=value,
/// double-NUL terminated, 0x00-padded).
const ENV_SIZE: usize = 65536;
/// Flag: four magic bytes "ALAN" at misc (abs 0x1000000) erase-block 1.
const FLAG_ABS_OFFSET: u64 = 0x1020000; // misc base 0x1000000 + block 1 (0x20000)
const FLAG_BLOCK_IN_MISC: u64 = 0x20000; // offset of the flag block within the misc MTD
const FLAG_MAGIC: [u8; 4] = *b"ALAN";
/// Boot load addresses (CONFIRMED live) and the alkane console bootargs.
const KRNADDR: &str = "0x1200000";
const FDTADDR: &str = "0x8000000";
const RDADDR: &str = "0x8100000";
const ALK_BOOTARGS: &str = "console=ttyAML0,115200 earlycon=meson,0xff803000 no_console_suspend";
/// The on-board basenames inside the nvdata UBI volume's `alkane/` directory.
const ALKANE_DIR: &str = "alkane";
// ---------------------------------------------------------------------------
// Shell abstraction: StockShell drives the DSH root primitive; AlkaneShell the
// alkane SSH transport. (Mirrors zynq_nand.)
// ---------------------------------------------------------------------------
trait Shell {
fn exec(&mut self, cmd: &str) -> Result<String, StockError>;
fn exec_long(&mut self, cmd: &str) -> Result<String, StockError>;
fn put(&mut self, data: &[u8], remote_path: &str) -> Result<(), StockError>;
}
struct StockShell {
host: String,
password: Option<String>,
}
impl Shell for StockShell {
fn exec(&mut self, cmd: &str) -> Result<String, StockError> {
crate::stock::root_exec(&self.host, self.password.as_deref(), cmd)
}
fn exec_long(&mut self, cmd: &str) -> Result<String, StockError> {
// root_exec already carries a generous timeout in the method.
crate::stock::root_exec(&self.host, self.password.as_deref(), cmd)
}
fn put(&mut self, data: &[u8], remote_path: &str) -> Result<(), StockError> {
crate::stock::root_put(&self.host, self.password.as_deref(), data, remote_path)
}
}
struct AlkaneShell {
transport: SshTransport,
_secret: TempFile,
}
impl AlkaneShell {
fn connect(host: &str, password: Option<&str>) -> Result<Self, StockError> {
// Password in a 0600 temp file; a throwaway empty known_hosts (the host
// key legitimately changes across stock<->alkane). Same stance as zynq.
let secret = TempFile::with(password.unwrap_or("alkane").as_bytes(), "pw")?;
let known = temp_path("kh");
let _ = std::fs::File::create(&known);
let options = SshOptions {
host: host.to_owned(),
port: 22,
user: "root".to_owned(),
identity_file: None,
password_file: Some(secret.0.clone()),
known_hosts: Some(known),
root_method: crate::transport::RootMethod::Auto,
update_daemon_port: None,
};
let transport =
SshTransport::connect(options, true).map_err(|e| StockError::Network(e.to_string()))?;
Ok(AlkaneShell {
transport,
_secret: secret,
})
}
}
impl Shell for AlkaneShell {
fn exec(&mut self, cmd: &str) -> Result<String, StockError> {
self.transport
.root_command(cmd, Duration::from_secs(120))
.map(|o| String::from_utf8_lossy(&o).into_owned())
.map_err(|e| StockError::Method(e.to_string()))
}
fn exec_long(&mut self, cmd: &str) -> Result<String, StockError> {
self.transport
.root_command(cmd, Duration::from_secs(900))
.map(|o| String::from_utf8_lossy(&o).into_owned())
.map_err(|e| StockError::Method(e.to_string()))
}
fn put(&mut self, data: &[u8], remote_path: &str) -> Result<(), StockError> {
let tmp = TempFile::with(data, "put")?;
self.transport
.push(&tmp.0, remote_path, Duration::from_secs(900))
.map_err(|e| StockError::Method(e.to_string()))
}
}
static TEMP_SEQ: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
fn temp_path(tag: &str) -> PathBuf {
let n = TEMP_SEQ.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
std::env::temp_dir().join(format!("alkane-aml-{}-{}-{}", std::process::id(), tag, n))
}
/// A 0600 temp file removed on drop.
struct TempFile(PathBuf);
impl TempFile {
fn with(contents: &[u8], tag: &str) -> Result<Self, StockError> {
let path = temp_path(tag);
write_private(&path, contents).map_err(|e| StockError::Io(e.to_string()))?;
Ok(TempFile(path))
}
}
impl Drop for TempFile {
fn drop(&mut self) {
let _ = std::fs::remove_file(&self.0);
}
}
#[cfg(unix)]
fn write_private(path: &Path, contents: &[u8]) -> std::io::Result<()> {
use std::io::Write as _;
use std::os::unix::fs::OpenOptionsExt;
let mut f = std::fs::OpenOptions::new()
.create(true)
.truncate(true)
.write(true)
.mode(0o600)
.open(path)?;
f.write_all(contents)?;
f.flush()
}
#[cfg(not(unix))]
fn write_private(path: &Path, contents: &[u8]) -> std::io::Result<()> {
std::fs::write(path, contents)
}
// ---------------------------------------------------------------------------
// base64 (busybox-safe: decode a possibly line-wrapped stream).
// ---------------------------------------------------------------------------
fn b64_decode(s: &str) -> Option<Vec<u8>> {
const INV: u8 = 0xFF;
fn val(c: u8) -> u8 {
match c {
b'A'..=b'Z' => c - b'A',
b'a'..=b'z' => c - b'a' + 26,
b'0'..=b'9' => c - b'0' + 52,
b'+' => 62,
b'/' => 63,
_ => INV,
}
}
let mut out = Vec::new();
let mut acc = 0u32;
let mut bits = 0u32;
for &c in s.as_bytes() {
if c == b'=' {
break;
}
let v = val(c);
if v == INV {
continue; // skip whitespace / newlines
}
acc = (acc << 6) | v as u32;
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((acc >> bits) as u8);
}
}
Some(out)
}
fn b64_encode(data: &[u8]) -> String {
const T: &[u8; 64] = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
let mut out = String::with_capacity(data.len().div_ceil(3) * 4);
for chunk in data.chunks(3) {
let b = [
chunk[0],
*chunk.get(1).unwrap_or(&0),
*chunk.get(2).unwrap_or(&0),
];
let n = ((b[0] as u32) << 16) | ((b[1] as u32) << 8) | b[2] as u32;
out.push(T[((n >> 18) & 63) as usize] as char);
out.push(T[((n >> 12) & 63) as usize] as char);
out.push(if chunk.len() > 1 {
T[((n >> 6) & 63) as usize] as char
} else {
'='
});
out.push(if chunk.len() > 2 {
T[(n & 63) as usize] as char
} else {
'='
});
}
out
}
// ---------------------------------------------------------------------------
// U-Boot environment (standard format) read / parse / build / write.
// ---------------------------------------------------------------------------
/// Read the 64 KiB U-Boot env blob from /dev/nand_env (stock only).
fn read_env(sh: &mut dyn Shell) -> Result<Vec<u8>, StockError> {
let out = sh.exec(
"echo B64START; dd if=/dev/nand_env bs=65536 count=1 2>/dev/null | base64; echo B64END",
)?;
let start = out
.find("B64START")
.ok_or_else(|| StockError::Method("env read: no marker".into()))?;
let end = out
.find("B64END")
.ok_or_else(|| StockError::Method("env read: no end marker".into()))?;
let b64 = &out[start + "B64START".len()..end];
let blob = b64_decode(b64).ok_or_else(|| StockError::Method("env read: bad base64".into()))?;
if blob.len() != ENV_SIZE {
return Err(StockError::Method(format!(
"env read: {} bytes (expected {ENV_SIZE})",
blob.len()
)));
}
let stored = u32::from_le_bytes([blob[0], blob[1], blob[2], blob[3]]);
if crc32(&blob[4..]) != stored {
return Err(StockError::Method("env read: CRC mismatch".into()));
}
Ok(blob)
}
/// Parse the env body into ordered (key, value) pairs (up to the double-NUL).
fn parse_env(blob: &[u8]) -> Vec<(String, String)> {
let body = &blob[4..];
let end = body
.windows(2)
.position(|w| w == [0, 0])
.unwrap_or(body.len());
let mut vars = Vec::new();
for kv in body[..end].split(|&b| b == 0) {
if kv.is_empty() {
continue;
}
if let Some(eq) = kv.iter().position(|&b| b == b'=') {
let k = String::from_utf8_lossy(&kv[..eq]).into_owned();
let v = String::from_utf8_lossy(&kv[eq + 1..]).into_owned();
vars.push((k, v));
}
}
vars
}
/// Build a 64 KiB env blob from ordered (key,value) pairs: CRC32 + body +
/// double-NUL + 0x00 padding (what a clean `saveenv` produces).
fn build_env(vars: &[(String, String)]) -> Result<Vec<u8>, StockError> {
let mut body = Vec::with_capacity(ENV_SIZE);
for (k, v) in vars {
body.extend_from_slice(k.as_bytes());
body.push(b'=');
body.extend_from_slice(v.as_bytes());
body.push(0);
}
body.push(0); // terminating double-NUL (last var's NUL + this one)
if body.len() > ENV_SIZE - 4 {
return Err(StockError::Method("env too large".into()));
}
body.resize(ENV_SIZE - 4, 0);
let crc = crc32(&body);
let mut blob = Vec::with_capacity(ENV_SIZE);
blob.extend_from_slice(&crc.to_le_bytes());
blob.extend_from_slice(&body);
Ok(blob)
}
/// Set (or insert, preserving order) a variable.
fn set_var(vars: &mut Vec<(String, String)>, key: &str, value: &str) {
if let Some(slot) = vars.iter_mut().find(|(k, _)| k == key) {
slot.1 = value.to_owned();
} else {
vars.push((key.to_owned(), value.to_owned()));
}
}
/// Write the env blob to /dev/nand_env and read it back byte-exact BEFORE any
/// reboot (the env is only consumed at next boot, so a verified read-back cannot
/// brick). On a read-back mismatch the caller must restore the previous env.
fn write_env(sh: &mut dyn Shell, blob: &[u8]) -> Result<(), StockError> {
let b64 = b64_encode(blob);
// Stream the blob to a temp file, then dd it to /dev/nand_env in one write.
sh.put(b64.as_bytes(), "/tmp/.alkenv.b64")?;
let out = sh.exec(
"base64 -d /tmp/.alkenv.b64 > /tmp/.alkenv.bin 2>/dev/null; \
dd if=/tmp/.alkenv.bin of=/dev/nand_env bs=65536 count=1 2>/dev/null; sync; \
echo RB=$(dd if=/dev/nand_env bs=65536 count=1 2>/dev/null | md5sum | cut -d' ' -f1); \
rm -f /tmp/.alkenv.b64 /tmp/.alkenv.bin",
)?;
let want = md5_hex(blob);
let got = out
.split("RB=")
.nth(1)
.map(|s| s.trim().to_owned())
.unwrap_or_default();
if got != want {
return Err(StockError::Method(format!(
"env write read-back mismatch: wrote {want}, read {got}"
)));
}
Ok(())
}
fn md5_hex(data: &[u8]) -> String {
crate::md5::md5_hex(data)
}
// ---------------------------------------------------------------------------
// MTD / flag helpers.
// ---------------------------------------------------------------------------
/// Find the /dev/mtdN whose /proc/mtd label matches `name`.
fn find_mtd(sh: &mut dyn Shell, name: &str) -> Result<String, StockError> {
let out = sh.exec("cat /proc/mtd")?;
for line in out.lines() {
if line.contains(&format!("\"{name}\"")) {
if let Some((dev, _)) = line.split_once(':') {
return Ok(format!("/dev/{}", dev.trim()));
}
}
}
Err(StockError::Method(format!("no '{name}' MTD on this board")))
}
/// Discover the nvdata UBI volume's name (never assumed: vendor histories leave
/// different names). Looks for an already-attached ubi volume on the nvdata MTD.
fn discover_nvdata_volume(sh: &mut dyn Shell) -> Result<(String, String), StockError> {
// Returns (mountpoint, volume_name). On stock the vendor mounts nvdata (e.g.
// at /tmp/miner); find the ubifs mount whose volume sits on the nvdata MTD.
let mounts = sh.exec("cat /proc/mounts")?;
for line in mounts.lines() {
// e.g. "/dev/ubi2_0 /tmp/miner ubifs rw,..."
let mut it = line.split_whitespace();
let dev = it.next().unwrap_or("");
let mnt = it.next().unwrap_or("");
let fs = it.next().unwrap_or("");
if fs == "ubifs" && dev.contains("ubi") {
// read the volume name from sysfs: /sys/class/ubi/<ubiX_0>/name
let base = dev.trim_start_matches("/dev/");
let name = sh
.exec(&format!("cat /sys/class/ubi/{base}/name 2>/dev/null"))?
.trim()
.to_owned();
// Only accept the nvdata volume (skip the small config_data volume).
// nvdata is the large one; confirm by its mount not being /config.
if !name.is_empty() && mnt != "/config" {
return Ok((mnt.to_owned(), name));
}
}
}
Err(StockError::Method(
"could not find the mounted nvdata UBI volume".into(),
))
}
/// Write the ALAN flag into misc block 1 (flag=alkane). `misc_dev` is the misc
/// MTD device on the running OS (stock: /dev/mtd2; alkane: whatever /proc/mtd
/// shows for "misc").
fn set_flag_alkane(sh: &mut dyn Shell, misc_dev: &str) -> Result<(), StockError> {
// one page: magic + 0xFF pad
let mut page = FLAG_MAGIC.to_vec();
page.resize(2048, 0xFF);
sh.put(&page, "/tmp/.alkflag")?;
let out = sh.exec(&format!(
"flash_erase {misc_dev} 0x{FLAG_BLOCK_IN_MISC:x} 1 >/dev/null 2>&1; \
nandwrite -s 0x{FLAG_BLOCK_IN_MISC:x} -p {misc_dev} /tmp/.alkflag >/dev/null 2>&1; sync; \
echo RB=$(dd if={misc_dev} bs=2048 skip={blk} count=1 2>/dev/null | md5sum | cut -d' ' -f1); \
rm -f /tmp/.alkflag",
blk = FLAG_BLOCK_IN_MISC / 2048
))?;
let want = md5_hex(&page);
let got = out
.split("RB=")
.nth(1)
.map(|s| s.trim().to_owned())
.unwrap_or_default();
if got != want {
return Err(StockError::Method("flag write read-back mismatch".into()));
}
Ok(())
}
/// Erase the flag block (flag=stock).
fn clear_flag(sh: &mut dyn Shell, misc_dev: &str) -> Result<(), StockError> {
sh.exec(&format!(
"flash_erase {misc_dev} 0x{FLAG_BLOCK_IN_MISC:x} 1 >/dev/null 2>&1; sync; echo CLEARED"
))?;
Ok(())
}
// ---------------------------------------------------------------------------
// The flag-based boot-chain env vars.
// ---------------------------------------------------------------------------
/// checkalk raw-reads the flag page and tests the four magic bytes with nested
/// `itest.b` (this vendor U-Boot mis-compares `itest.l *<mem>`); only on a match
/// does it run alkboot. No ubi/ubifs here - that keeps the stock path raw.
fn checkalk_value() -> String {
format!(
"nand read 0x08000000 0x{FLAG_ABS_OFFSET:x} 0x800; \
if itest.b *0x08000000 == 0x{a:02x}; then \
if itest.b *0x08000001 == 0x{l:02x}; then \
if itest.b *0x08000002 == 0x{a2:02x}; then \
if itest.b *0x08000003 == 0x{n:02x}; then run alkboot; fi; fi; fi; fi",
a = FLAG_MAGIC[0],
l = FLAG_MAGIC[1],
a2 = FLAG_MAGIC[2],
n = FLAG_MAGIC[3],
)
}
/// alkboot mounts the nvdata UBIFS and boots alkane from `alkane/`.
fn alkboot_value(volume: &str) -> String {
format!(
"setenv bootargs ${{alkbootargs}}; ubi part nvdata; ubifsmount ubi0:{volume}; \
ubifsload ${{krnaddr}} {ALKANE_DIR}/vmlinux.bin; \
ubifsload ${{fdtaddr}} {ALKANE_DIR}/devicetree.dtb; \
ubifsload ${{rdaddr}} {ALKANE_DIR}/uramdisk.image.gz; \
booti ${{krnaddr}} ${{rdaddr}} ${{fdtaddr}}"
)
}
/// Install the flag-based boot env (preserving all existing stock vars). Leaves
/// bootcmd = "run checkalk; run storeboot".
fn install_boot_env(sh: &mut dyn Shell, volume: &str) -> Result<(), StockError> {
let blob = read_env(sh)?;
let mut vars = parse_env(&blob);
set_var(&mut vars, "krnaddr", KRNADDR);
set_var(&mut vars, "fdtaddr", FDTADDR);
set_var(&mut vars, "rdaddr", RDADDR);
set_var(&mut vars, "alkbootargs", ALK_BOOTARGS);
set_var(&mut vars, "alkboot", &alkboot_value(volume));
set_var(&mut vars, "checkalk", &checkalk_value());
set_var(&mut vars, "bootcmd", "run checkalk; run storeboot");
let new_blob = build_env(&vars)?;
write_env(sh, &new_blob)
}
fn reboot_stock(sh: &mut dyn Shell) {
let _ = sh.exec("sync; reboot");
}
fn reboot_alkane(sh: &mut dyn Shell) {
// plain `reboot` no-ops on the minimal init; `reboot -f` triggers PSCI reset.
let _ = sh.exec("sync; reboot -f");
}
// ---------------------------------------------------------------------------
// Public API (dispatched from stock.rs for board == a113d).
// ---------------------------------------------------------------------------
/// Install alkane onto an A113D running genuine stock, network-only, over the
/// DSH root-on-stock primitive. Stages the OS files into the nvdata UBI volume,
/// installs the flag-based boot env, and sets flag=alkane; the next boot runs
/// alkane. Zero raw writes outside the flag block in `misc`.
pub fn install_from_stock(
host: &str,
kernel_image: &[u8],
dtb: &[u8],
uramdisk: &[u8],
password: Option<&str>,
) -> Result<(), StockError> {
let mut sh = StockShell {
host: host.to_owned(),
password: password.map(|s| s.to_owned()),
};
// Guard: this board must be A113D stock (has a 'misc' MTD and a mounted
// nvdata UBI). If not, defer to the compiled-in method.
let proc_mtd = sh.exec("cat /proc/mtd 2>/dev/null").unwrap_or_default();
if !proc_mtd.contains("\"nvdata\"") || !proc_mtd.contains("\"misc\"") {
return Err(StockError::NotApplicable);
}
let misc = find_mtd(&mut sh, "misc")?;
let (mount, volume) = discover_nvdata_volume(&mut sh)?;
// Stage the three files into <mount>/alkane/ and read-back verify.
let dir = format!("{mount}/{ALKANE_DIR}");
sh.exec(&format!("mkdir -p {dir}"))?;
// rootfs -> dtb -> kernel (kernel lands last).
stage_file(&mut sh, uramdisk, &format!("{dir}/uramdisk.image.gz"))?;
stage_file(&mut sh, dtb, &format!("{dir}/devicetree.dtb"))?;
stage_file(&mut sh, kernel_image, &format!("{dir}/vmlinux.bin"))?;
sh.exec("sync")?;
// Install the flag-based boot env (read-back verified before reboot).
install_boot_env(&mut sh, &volume)?;
// Set flag=alkane, then reboot into alkane.
set_flag_alkane(&mut sh, &misc)?;
reboot_stock(&mut sh);
Ok(())
}
/// Stage one file to a UBIFS path and prove its read-back md5 before continuing.
fn stage_file(sh: &mut dyn Shell, data: &[u8], dest: &str) -> Result<(), StockError> {
let tmp = "/tmp/.alkstage";
sh.put(data, tmp)?;
let out = sh.exec_long(&format!(
"cp -f {tmp} {dest} && sync; echo RB=$(md5sum {dest} | cut -d' ' -f1); rm -f {tmp}"
))?;
let want = md5_hex(data);
let got = out
.split("RB=")
.nth(1)
.map(|s| s.trim().to_owned())
.unwrap_or_default();
if got != want {
return Err(StockError::Method(format!(
"staged {dest} md5 mismatch: want {want}, got {got}"
)));
}
Ok(())
}
/// Restore an A113D running alkane back to genuine stock, network-only, in-band
/// from the running alkane OS: erase the flag block (flag=stock) and reboot.
/// Stock boots via `storeboot` from the untouched `boot` MTD; the alkane payload
/// and env are left in place, so a re-install is just re-writing the flag.
pub fn restore_to_stock(host: &str, password: Option<&str>) -> Result<(), StockError> {
let mut sh = AlkaneShell::connect(host, password)?;
// Guard: must be the alkane a113d image (exposes 'misc' and 'nvdata' MTDs,
// mainline 6.18.48). If 'misc' is absent this is not applicable.
let proc_mtd = sh.exec("cat /proc/mtd 2>/dev/null").unwrap_or_default();
if !proc_mtd.contains("\"misc\"") {
return Err(StockError::NotApplicable);
}
let misc = find_mtd(&mut sh, "misc")?;
clear_flag(&mut sh, &misc)?;
reboot_alkane(&mut sh);
Ok(())
}
/// The on-board stock backup is structural on this board: `storeboot` always
/// boots genuine stock from the `boot` MTD (mtd4), which this install never
/// writes. So a complete backup is present whenever the board is an A113D.
pub fn onboard_backup_present(host: &str, password: Option<&str>) -> Result<bool, StockError> {
// Best-effort confirm over alkane that the flag chain is in place; if we
// cannot reach alkane, report not-applicable so the caller falls through.
let mut sh = AlkaneShell::connect(host, password)?;
let proc_mtd = sh.exec("cat /proc/mtd 2>/dev/null").unwrap_or_default();
if proc_mtd.contains("\"misc\"") {
Ok(true)
} else {
Err(StockError::NotApplicable)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn env_roundtrips_with_crc() {
let vars = vec![
(
"bootcmd".to_owned(),
"run checkalk; run storeboot".to_owned(),
),
("bootdelay".to_owned(), "1".to_owned()),
("checkalk".to_owned(), checkalk_value()),
];
let blob = build_env(&vars).unwrap();
assert_eq!(blob.len(), ENV_SIZE);
let stored = u32::from_le_bytes([blob[0], blob[1], blob[2], blob[3]]);
assert_eq!(crc32(&blob[4..]), stored);
let parsed = parse_env(&blob);
assert_eq!(
parsed.iter().find(|(k, _)| k == "bootcmd").unwrap().1,
"run checkalk; run storeboot"
);
assert!(parsed.iter().any(|(k, _)| k == "checkalk"));
}
#[test]
fn b64_roundtrip() {
for n in [0usize, 1, 2, 3, 64, 2048, 65536] {
let data: Vec<u8> = (0..n).map(|i| (i * 7 + 3) as u8).collect();
let enc = b64_encode(&data);
let dec = b64_decode(&enc).unwrap();
assert_eq!(dec, data, "n={n}");
}
// wrapped base64 decodes the same
let data: Vec<u8> = (0..100).map(|i| i as u8).collect();
let mut wrapped = b64_encode(&data);
wrapped.insert(20, '\n');
wrapped.insert(50, '\n');
assert_eq!(b64_decode(&wrapped).unwrap(), data);
}
#[test]
fn checkalk_is_raw_and_byte_tested() {
let c = checkalk_value();
assert!(c.starts_with("nand read 0x08000000"));
assert!(c.contains("itest.b *0x08000000 == 0x41"));
assert!(!c.contains("ubi")); // the stock path must never touch UBI
assert!(c.contains("run alkboot"));
}
#[test]
fn alkboot_loads_from_alkane_dir() {
let a = alkboot_value("nvdata_log");
assert!(a.contains("ubifsmount ubi0:nvdata_log"));
assert!(a.contains("alkane/vmlinux.bin"));
assert!(a.contains("booti ${krnaddr} ${rdaddr} ${fdtaddr}"));
}
}
+5 -1
View File
@@ -11,12 +11,15 @@
// choices for this crate rather than defects.
#![allow(clippy::type_complexity, clippy::too_many_arguments)]
pub mod aml_ubi;
pub mod boards;
pub mod install;
pub mod md5;
pub mod preflight;
pub mod stock;
pub mod stock_firmware;
pub mod uimage;
pub mod zynq_nand;
// 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
@@ -27,7 +30,8 @@ pub mod stock_firmware;
clippy::too_many_arguments,
clippy::manual_repeat_n,
clippy::manual_is_multiple_of,
clippy::unnecessary_map_or
clippy::unnecessary_map_or,
clippy::question_mark
)]
mod stock_method;
pub mod transport;
+256 -1
View File
@@ -12,6 +12,11 @@
//! (`StockMethod`, `StockError`) plus the toolkit-side orchestration and
//! verification around the method. The method is plain Rust and must be
//! network-only.
//!
//! A from-stock install also leaves a complete genuine-stock backup on the
//! board: the stock device tree, kernel and ramdisk, in the reserved NAND
//! region after the alkane MAC area. The two on-board backup calls below check
//! and restore that copy over the network, with no vendor firmware file.
use alkane_artifacts::afw::VerifiedAfw;
use std::path::{Path, PathBuf};
@@ -29,6 +34,8 @@ pub enum StockError {
Method(String),
#[error("io: {0}")]
Io(String),
#[error("not applicable to this board; use the compiled-in method")]
NotApplicable,
}
/// The genuine Bitmain stock kernel and rootfs to write back when restoring to
@@ -41,6 +48,10 @@ pub enum StockError {
pub struct RestoreImages<'a> {
pub kernel: &'a [u8],
pub rootfs: &'a [u8],
/// The genuine per-board device tree from the vendor package, when present
/// (SD recovery images ship one; OTA packages omit it). When `None`, the
/// zynq readable path takes the stock dtb from the on-board backup.
pub dtb: Option<&'a [u8]>,
}
/// Options for updating a board that already runs alkane, in place.
@@ -144,6 +155,31 @@ pub trait StockMethod {
password: Option<&str>,
) -> Result<(), StockError>;
/// Run `cmd` as root on a board running stock, over the network only, and
/// return its combined standard output and standard error. `cmd` is a
/// `/bin/sh` command line. A non-zero exit is an `Err` whose message is that
/// combined output. `password` is the board's stock login password; `None`
/// falls back to the configured board credential.
fn root_exec(
&self,
host: &str,
password: Option<&str>,
cmd: &str,
) -> Result<String, StockError>;
/// Write `data` to `remote_path` as root on a board running stock, over the
/// network only. Missing parent directories are created and the file is
/// left mode 0644. The payload may be many megabytes; it is sent as a
/// stream, not on a command line. `password` is the board's stock login
/// password; `None` falls back to the configured board credential.
fn root_put(
&self,
host: &str,
password: Option<&str>,
data: &[u8],
remote_path: &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
@@ -157,6 +193,26 @@ pub trait StockMethod {
password: Option<&str>,
options: &InPlaceOptions,
) -> Result<InPlaceOutcome, StockError>;
/// Report, over the network only, whether the board holds a complete
/// on-board stock backup that can be restored without a vendor firmware
/// file. False means absent or incomplete; it is not an error.
fn onboard_stock_backup_present(
&self,
host: &str,
password: Option<&str>,
) -> Result<bool, StockError>;
/// Return an alkane board to genuine stock, over the network only, using
/// the on-board stock backup. The backup must be present and complete; call
/// `onboard_stock_backup_present` first. `timeout` bounds the wait for the
/// restored board to answer as stock after the reboot.
fn restore_from_onboard_backup(
&self,
host: &str,
password: Option<&str>,
timeout: std::time::Duration,
) -> Result<(), StockError>;
}
/// The compiled-in method implementation.
@@ -164,6 +220,35 @@ pub fn method() -> &'static dyn StockMethod {
crate::stock_method::method()
}
/// Report, over the network only, whether the board holds a complete on-board
/// stock backup that can be restored without a vendor firmware file. Zynq uses
/// the readable boot-slot path; other boards use the compiled-in method.
pub fn onboard_stock_backup_present(
host: &str,
password: Option<&str>,
) -> Result<bool, StockError> {
match crate::zynq_nand::onboard_backup_present(host, password) {
Err(StockError::NotApplicable) => method().onboard_stock_backup_present(host, password),
other => other,
}
}
/// Return an alkane board to genuine stock (network-only) using its on-board
/// stock backup, via the compiled-in method. The backup must be present and
/// complete; check it first with [`onboard_stock_backup_present`].
pub fn restore_from_onboard_backup(
host: &str,
password: Option<&str>,
timeout: std::time::Duration,
) -> Result<(), StockError> {
match crate::zynq_nand::restore_from_onboard(host, password) {
Err(StockError::NotApplicable) => {
method().restore_from_onboard_backup(host, password, timeout)
}
other => other,
}
}
/// Install alkane onto a board on stock (network-only), via the compiled-in method.
pub fn install_from_stock(
host: &str,
@@ -171,6 +256,38 @@ pub fn install_from_stock(
afw: &VerifiedAfw,
password: Option<&str>,
) -> Result<(), StockError> {
// Zynq-7010 uses the readable NAND path (uImage-wrap + flash_erase/nandwrite
// over the DSH root primitive, with an on-board stock backup carved first);
// other boards use the compiled-in method.
if afw.manifest.board == crate::boards::zynq::BOARD {
let img = |role: &str| {
afw.image(role)
.map(|(_, data)| data)
.ok_or_else(|| StockError::Method(format!("afw missing {role} image")))
};
return crate::zynq_nand::install_from_stock(
host,
img("kernel")?,
img("dtb")?,
img("rootfs")?,
password,
);
}
// A113D (Amlogic AXG) uses the readable UBI-stage + flag-based boot chain.
if afw.manifest.board == crate::aml_ubi::BOARD {
let img = |role: &str| {
afw.image(role)
.map(|(_, data)| data)
.ok_or_else(|| StockError::Method(format!("afw missing {role} image")))
};
return crate::aml_ubi::install_from_stock(
host,
img("kernel")?,
img("dtb")?,
img("rootfs")?,
password,
);
}
method().install_from_stock(host, afw_path, afw, password)
}
@@ -181,7 +298,50 @@ pub fn restore_to_stock(
images: &RestoreImages,
password: Option<&str>,
) -> Result<(), StockError> {
method().restore_to_stock(host, images, password)
match crate::zynq_nand::restore_to_stock(
host,
images.kernel,
images.rootfs,
images.dtb,
password,
) {
Err(StockError::NotApplicable) => {
// A113D restore is a one-byte flag flip in-band from alkane; it needs
// no stock images. Try it, then fall through to the compiled-in method.
match crate::aml_ubi::restore_to_stock(host, password) {
Err(StockError::NotApplicable) => method().restore_to_stock(host, images, password),
other => other,
}
}
other => other,
}
}
/// Restore an alkane A113D to stock with no stock firmware file: a one-byte flag
/// flip in-band from the running alkane OS (network-only). Returns
/// `NotApplicable` if the board is not an alkane A113D.
pub fn restore_aml_flag(host: &str, password: Option<&str>) -> Result<(), StockError> {
crate::aml_ubi::restore_to_stock(host, password)
}
/// Run `cmd` as root on a board running stock (network-only), via the
/// compiled-in method. `cmd` is a `/bin/sh` command line; the returned string
/// is its combined output. A non-zero exit is an error whose message is that
/// output.
pub fn root_exec(host: &str, password: Option<&str>, cmd: &str) -> Result<String, StockError> {
method().root_exec(host, password, cmd)
}
/// Write `data` to `remote_path` as root on a board running stock
/// (network-only), via the compiled-in method. Missing parent directories are
/// created and the file is left mode 0644. Large payloads are streamed.
pub fn root_put(
host: &str,
password: Option<&str>,
data: &[u8],
remote_path: &str,
) -> Result<(), StockError> {
method().root_put(host, password, data, remote_path)
}
/// Check, over the network, that a Zynq board is up on alkane: the web page
@@ -215,8 +375,103 @@ mod tests {
// 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 public_signatures_are_wired() {
let _: fn(&str, Option<&str>) -> Result<bool, StockError> = onboard_stock_backup_present;
let _: fn(&str, Option<&str>, std::time::Duration) -> Result<(), StockError> =
restore_from_onboard_backup;
let _: fn(&str, Option<&str>, &str) -> Result<String, StockError> = root_exec;
let _: fn(&str, Option<&str>, &[u8], &str) -> Result<(), StockError> = root_put;
}
struct FakeMethod {
present: bool,
}
impl StockMethod for FakeMethod {
fn install_from_stock(
&self,
_: &str,
_: &Path,
_: &VerifiedAfw,
_: Option<&str>,
) -> Result<(), StockError> {
Err(StockError::NotImplemented)
}
fn restore_to_stock(
&self,
_: &str,
_: &RestoreImages,
_: Option<&str>,
) -> Result<(), StockError> {
Err(StockError::NotImplemented)
}
fn root_exec(&self, _: &str, _: Option<&str>, _: &str) -> Result<String, StockError> {
Err(StockError::NotImplemented)
}
fn root_put(&self, _: &str, _: Option<&str>, _: &[u8], _: &str) -> Result<(), StockError> {
Err(StockError::NotImplemented)
}
fn update_in_place(
&self,
_: &str,
_: &VerifiedAfw,
_: Option<&str>,
_: &InPlaceOptions,
) -> Result<InPlaceOutcome, StockError> {
Err(StockError::NotImplemented)
}
fn onboard_stock_backup_present(
&self,
_: &str,
_: Option<&str>,
) -> Result<bool, StockError> {
Ok(self.present)
}
fn restore_from_onboard_backup(
&self,
_: &str,
_: Option<&str>,
_: std::time::Duration,
) -> Result<(), StockError> {
if self.present {
Ok(())
} else {
Err(StockError::Method(
"no complete on-board stock backup".into(),
))
}
}
}
#[test]
fn a_method_is_compiled_in() {
let _m: &dyn StockMethod = method();
}
#[test]
fn onboard_backup_methods_report_present_or_absent() {
let present = FakeMethod { present: true };
assert!(present
.onboard_stock_backup_present("192.0.2.10", Some("secret"))
.unwrap());
assert!(present
.restore_from_onboard_backup("192.0.2.10", Some("secret"), std::time::Duration::ZERO)
.is_ok());
let absent = FakeMethod { present: false };
assert!(!absent
.onboard_stock_backup_present("192.0.2.10", None)
.unwrap());
assert!(matches!(
absent.restore_from_onboard_backup("192.0.2.10", None, std::time::Duration::ZERO),
Err(StockError::Method(_))
));
}
}
File diff suppressed because it is too large Load Diff
+152
View File
@@ -0,0 +1,152 @@
// SPDX-License-Identifier: MIT
//! Legacy U-Boot image (`uImage`) header builder.
//!
//! The Zynq (Antminer S17/S19-class) stock U-Boot boots a legacy uImage: a
//! 64-byte big-endian header (magic `0x27051956`) in front of the payload. We
//! wrap the kernel (a raw ARM `zImage`) and the ramdisk (a gzipped cpio) in this
//! header so the board's own U-Boot boots them unchanged. The device tree is
//! written raw (no header).
//!
//! The header parameters below were read directly off a genuine stock S17 NAND
//! (kernel: type Kernel, uncompressed, load/entry `0x8000`; ramdisk: type
//! RAMDisk, gzip, load/entry `0`), so the images we write match exactly what the
//! stock boot chain already boots.
/// Legacy uImage magic (big-endian).
pub const IH_MAGIC: u32 = 0x2705_1956;
/// Header length in bytes.
pub const HEADER_LEN: usize = 64;
// ih_os
const IH_OS_LINUX: u8 = 5;
// ih_arch
const IH_ARCH_ARM: u8 = 2;
// ih_type
const IH_TYPE_KERNEL: u8 = 2;
const IH_TYPE_RAMDISK: u8 = 3;
// ih_comp
const IH_COMP_NONE: u8 = 0;
const IH_COMP_GZIP: u8 = 1;
/// A CRC-32 (IEEE 802.3, the variant U-Boot uses) over `data`.
pub fn crc32(data: &[u8]) -> u32 {
let mut crc: u32 = 0xFFFF_FFFF;
for &byte in data {
crc ^= byte as u32;
for _ in 0..8 {
let mask = (crc & 1).wrapping_neg();
crc = (crc >> 1) ^ (0xEDB8_8320 & mask);
}
}
!crc
}
/// Which kind of uImage to build.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Kind {
/// ARM Linux kernel, uncompressed, load/entry 0x8000 (what the stock S17
/// kernel uImage uses).
Kernel,
/// ARM Linux ramdisk, gzip, load/entry 0 (what the stock S17 ramdisk uImage
/// uses).
Ramdisk,
}
impl Kind {
fn ih_type(self) -> u8 {
match self {
Kind::Kernel => IH_TYPE_KERNEL,
Kind::Ramdisk => IH_TYPE_RAMDISK,
}
}
fn ih_comp(self) -> u8 {
match self {
Kind::Kernel => IH_COMP_NONE,
Kind::Ramdisk => IH_COMP_GZIP,
}
}
fn load_entry(self) -> u32 {
match self {
Kind::Kernel => 0x8000,
Kind::Ramdisk => 0,
}
}
}
/// Wrap `payload` in a legacy uImage header of the given `kind` and return the
/// full image (header followed by payload). `time` is the header timestamp; pass
/// a fixed value for a reproducible image. `name` is truncated to 31 bytes.
pub fn wrap(kind: Kind, payload: &[u8], time: u32, name: &str) -> Vec<u8> {
let mut hdr = [0u8; HEADER_LEN];
hdr[0..4].copy_from_slice(&IH_MAGIC.to_be_bytes());
// hdr[4..8] header CRC: filled in last, over the header with this field zero.
hdr[8..12].copy_from_slice(&time.to_be_bytes());
hdr[12..16].copy_from_slice(&(payload.len() as u32).to_be_bytes());
hdr[16..20].copy_from_slice(&kind.load_entry().to_be_bytes());
hdr[20..24].copy_from_slice(&kind.load_entry().to_be_bytes());
hdr[24..28].copy_from_slice(&crc32(payload).to_be_bytes());
hdr[28] = IH_OS_LINUX;
hdr[29] = IH_ARCH_ARM;
hdr[30] = kind.ih_type();
hdr[31] = kind.ih_comp();
let name_bytes = name.as_bytes();
let n = name_bytes.len().min(31);
hdr[32..32 + n].copy_from_slice(&name_bytes[..n]);
// Header CRC over the 64-byte header with the hcrc field (4..8) zeroed.
let hcrc = crc32(&hdr);
hdr[4..8].copy_from_slice(&hcrc.to_be_bytes());
let mut out = Vec::with_capacity(HEADER_LEN + payload.len());
out.extend_from_slice(&hdr);
out.extend_from_slice(payload);
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn crc32_known_vector() {
// CRC-32/ISO-HDLC of "123456789" is 0xCBF43926.
assert_eq!(crc32(b"123456789"), 0xCBF4_3926);
assert_eq!(crc32(b""), 0);
}
#[test]
fn header_shape_and_fields() {
let img = wrap(Kind::Kernel, b"payload-bytes", 0, "alkane");
assert_eq!(img.len(), HEADER_LEN + 13);
assert_eq!(&img[0..4], &IH_MAGIC.to_be_bytes());
assert_eq!(u32::from_be_bytes([img[12], img[13], img[14], img[15]]), 13);
// kernel: load/entry 0x8000, type kernel, comp none
assert_eq!(&img[16..20], &0x8000u32.to_be_bytes());
assert_eq!(&img[20..24], &0x8000u32.to_be_bytes());
assert_eq!(img[28], IH_OS_LINUX);
assert_eq!(img[29], IH_ARCH_ARM);
assert_eq!(img[30], IH_TYPE_KERNEL);
assert_eq!(img[31], IH_COMP_NONE);
assert_eq!(&img[64..], b"payload-bytes");
}
#[test]
fn ramdisk_fields() {
let img = wrap(Kind::Ramdisk, b"rd", 0, "rd");
assert_eq!(&img[16..20], &0u32.to_be_bytes());
assert_eq!(img[30], IH_TYPE_RAMDISK);
assert_eq!(img[31], IH_COMP_GZIP);
}
#[test]
fn header_crc_validates() {
let img = wrap(Kind::Kernel, b"abc", 0x1234, "n");
let mut hdr = [0u8; HEADER_LEN];
hdr.copy_from_slice(&img[..HEADER_LEN]);
let stored = u32::from_be_bytes([hdr[4], hdr[5], hdr[6], hdr[7]]);
hdr[4..8].copy_from_slice(&[0, 0, 0, 0]);
assert_eq!(crc32(&hdr), stored);
// data CRC over payload
let dcrc = u32::from_be_bytes([img[24], img[25], img[26], img[27]]);
assert_eq!(crc32(b"abc"), dcrc);
}
}
+809
View File
@@ -0,0 +1,809 @@
// SPDX-License-Identifier: MIT
//! Readable Zynq-7010 NAND install / restore / on-board-backup, driven entirely
//! over the network through two small root shells:
//!
//! * a board on **stock** is reached with the DSH root-on-stock primitives
//! (`crate::stock::root_exec` / `root_put`): this is the only compartmentalised
//! piece, and it is used only to get a root shell;
//! * a board on **alkane** is reached with ordinary SSH (`crate::transport`).
//!
//! Everything else -- what to write, where, in what form, and the read-back
//! verification -- lives here in plain, auditable Rust. The NAND writes
//! themselves are the same `flash_erase` + `nandwrite` MTD operations on both
//! sides; only the way we obtain the root shell differs.
//!
//! Absolute NAND map (Micron MT29F2G08, 256 MiB, 128 KiB erase, 2 KiB page),
//! confirmed on a genuine stock S17 and mirrored by the alkane board DT:
//! ```text
//! 0x00000000 BOOT.bin (FSBL + bitstream + stock U-Boot + env) NEVER written
//! 0x01a00000 device tree (raw fdt)
//! 0x02000000 kernel (legacy uImage)
//! 0x02800000 rootfs (legacy uImage ramdisk)
//! 0x04800000 stock `configs` (UBI) exposed read-only on alkane
//! 0x05000000 alkane-cfg (persisted MAC)
//! 0x06000000 on-board genuine-stock backup (stock `ramfs-bak` region)
//! 0x08000000 stock `reserve1` / nvdata (UBI) left untouched
//! ```
//! On a board running alkane the boot slots are exposed as the named partitions
//! `boot-dtb` / `boot-kernel` / `boot-rootfs` / `stock-backup` (see the board
//! DT); on stock they fall inside `mtd0` / `mtd1` / `ramfs-bak`. Because we map
//! an absolute offset to whichever MTD partition contains it, the same code
//! writes the same physical NAND on both sides.
use crate::md5::md5_hex;
use crate::stock::StockError;
use crate::transport::{Remote, SshOptions, SshTransport};
use crate::uimage::{self, Kind};
use std::path::Path;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::Duration;
/// NAND erase-block size (128 KiB).
const ERASE: u64 = 0x20000;
/// NAND page size (2 KiB); `nandwrite -p` pads the final page with 0xFF.
const PAGE: u64 = 0x800;
/// Absolute boot-slot offsets (see the module map).
const OFF_DTB: u64 = 0x1a00000;
const OFF_KERNEL: u64 = 0x2000000;
const OFF_ROOTFS: u64 = 0x2800000;
const OFF_STOCK_BACKUP: u64 = 0x6000000;
/// BOOT.bin occupies 0x0..0x1a00000 and is never written.
const BOOTBIN_PRESERVE: u64 = 0x1a00000;
/// Slot ceilings (so a too-large image is refused before any erase).
const SLOT_DTB: u64 = 0x600000;
const SLOT_KERNEL: u64 = 0x800000;
const SLOT_ROOTFS: u64 = 0x2000000;
const SLOT_STOCK_BACKUP: u64 = 0x2000000;
/// Where the backup data lives inside the 32 MiB stock-backup region: the first
/// erase block holds the manifest, the images follow, each erase-block aligned.
const BK_MANIFEST: u64 = OFF_STOCK_BACKUP; // 0x6000000
const BK_MAGIC: &[u8; 8] = b"ALKSTKB1";
fn round_up(value: u64, to: u64) -> u64 {
value.div_ceil(to) * to
}
// ---------------------------------------------------------------------------
// Root shells
// ---------------------------------------------------------------------------
/// A root shell on the target board: run a `/bin/sh` command as root and stream
/// a byte payload to a file as root. Both sides implement this; the NAND code
/// below is written once against it.
trait Shell {
fn exec(&mut self, cmd: &str) -> Result<String, StockError>;
fn put(&mut self, data: &[u8], remote_path: &str) -> Result<(), StockError>;
/// Longer-running command (large nandwrite / nanddump).
fn exec_long(&mut self, cmd: &str) -> Result<String, StockError>;
}
/// Stock board: root obtained through the compartmentalised DSH primitive.
struct StockShell {
host: String,
password: Option<String>,
}
impl Shell for StockShell {
fn exec(&mut self, cmd: &str) -> Result<String, StockError> {
crate::stock::root_exec(&self.host, self.password.as_deref(), cmd)
}
fn exec_long(&mut self, cmd: &str) -> Result<String, StockError> {
crate::stock::root_exec(&self.host, self.password.as_deref(), cmd)
}
fn put(&mut self, data: &[u8], remote_path: &str) -> Result<(), StockError> {
crate::stock::root_put(&self.host, self.password.as_deref(), data, remote_path)
}
}
/// Alkane board: root over ordinary SSH. A throwaway known-hosts file is used
/// so a board whose SSH host key legitimately changed across an install still
/// connects (accept-new), which is the norm on the bench.
struct AlkaneShell {
transport: SshTransport,
_secret: TempFile,
}
static TEMP_SEQ: AtomicU64 = AtomicU64::new(0);
fn temp_path(tag: &str) -> std::path::PathBuf {
let n = TEMP_SEQ.fetch_add(1, Ordering::Relaxed);
std::env::temp_dir().join(format!("alkane-{}-{}-{}", std::process::id(), tag, n))
}
/// A 0600 temp file removed on drop.
struct TempFile(std::path::PathBuf);
impl TempFile {
fn with(contents: &[u8], tag: &str) -> Result<Self, StockError> {
let path = temp_path(tag);
write_private(&path, contents).map_err(|e| StockError::Io(e.to_string()))?;
Ok(TempFile(path))
}
}
impl Drop for TempFile {
fn drop(&mut self) {
let _ = std::fs::remove_file(&self.0);
}
}
#[cfg(unix)]
fn write_private(path: &Path, contents: &[u8]) -> std::io::Result<()> {
use std::io::Write as _;
use std::os::unix::fs::OpenOptionsExt;
let mut f = std::fs::OpenOptions::new()
.create(true)
.truncate(true)
.write(true)
.mode(0o600)
.open(path)?;
f.write_all(contents)?;
f.flush()
}
#[cfg(not(unix))]
fn write_private(path: &Path, contents: &[u8]) -> std::io::Result<()> {
std::fs::write(path, contents)
}
impl AlkaneShell {
fn connect(host: &str, password: Option<&str>) -> Result<Self, StockError> {
let secret = TempFile::with(password.unwrap_or("alkane").as_bytes(), "pw")?;
let known = temp_path("kh");
let _ = std::fs::File::create(&known); // empty -> accept-new always accepts
let options = SshOptions {
host: host.to_owned(),
port: 22,
user: "root".to_owned(),
identity_file: None,
password_file: Some(secret.0.clone()),
known_hosts: Some(known),
root_method: crate::transport::RootMethod::Auto,
update_daemon_port: None,
};
let transport =
SshTransport::connect(options, true).map_err(|e| StockError::Network(e.to_string()))?;
Ok(AlkaneShell {
transport,
_secret: secret,
})
}
}
impl Shell for AlkaneShell {
fn exec(&mut self, cmd: &str) -> Result<String, StockError> {
self.transport
.root_command(cmd, Duration::from_secs(120))
.map(|o| String::from_utf8_lossy(&o).into_owned())
.map_err(|e| StockError::Method(e.to_string()))
}
fn exec_long(&mut self, cmd: &str) -> Result<String, StockError> {
self.transport
.root_command(cmd, Duration::from_secs(900))
.map(|o| String::from_utf8_lossy(&o).into_owned())
.map_err(|e| StockError::Method(e.to_string()))
}
fn put(&mut self, data: &[u8], remote_path: &str) -> Result<(), StockError> {
let tmp = TempFile::with(data, "put")?;
self.transport
.push(&tmp.0, remote_path, Duration::from_secs(900))
.map_err(|e| StockError::Method(e.to_string()))
}
}
// ---------------------------------------------------------------------------
// MTD table: map an absolute NAND offset to (device, relative offset)
// ---------------------------------------------------------------------------
#[derive(Clone, Debug)]
struct Mtd {
dev: String, // e.g. "mtd2"
base: u64, // absolute NAND offset of the partition start
size: u64,
#[allow(dead_code)]
name: String,
}
/// Read the MTD partition table. Each partition's absolute base comes from
/// `/sys/class/mtd/<dev>/offset` when present (alkane, where partitions are not
/// contiguous), falling back to the cumulative sum of sizes in `/proc/mtd`
/// order (stock, where they are contiguous from 0).
fn read_mtd_table(sh: &mut dyn Shell) -> Result<Vec<Mtd>, StockError> {
// name + size from /proc/mtd (always present); offset from sysfs if present.
let proc = sh.exec("cat /proc/mtd")?;
let mut out = Vec::new();
let mut cursor = 0u64;
for line in proc.lines() {
let line = line.trim();
if !line.starts_with("mtd") {
continue;
}
// "mtd0: 02800000 00020000 \"name\""
let (dev, rest) = match line.split_once(':') {
Some(v) => v,
None => continue,
};
let mut it = rest.split_whitespace();
let size = it
.next()
.and_then(|h| u64::from_str_radix(h, 16).ok())
.ok_or_else(|| StockError::Method(format!("bad /proc/mtd line: {line}")))?;
let _erase = it.next();
let name = line.split('"').nth(1).unwrap_or("").to_owned();
let base = match sysfs_offset(sh, dev) {
Some(off) => off,
None => cursor,
};
cursor = cursor.max(base) + size;
out.push(Mtd {
dev: dev.to_owned(),
base,
size,
name,
});
}
if out.is_empty() {
return Err(StockError::Method("no MTD partitions found".into()));
}
Ok(out)
}
fn sysfs_offset(sh: &mut dyn Shell, dev: &str) -> Option<u64> {
let out = sh
.exec(&format!("cat /sys/class/mtd/{dev}/offset 2>/dev/null"))
.ok()?;
out.trim().parse::<u64>().ok()
}
/// Find the partition that contains `abs` and holding at least `len` bytes from
/// there; return (device, relative offset).
fn locate(table: &[Mtd], abs: u64, len: u64) -> Result<(&str, u64), StockError> {
for m in table {
if abs >= m.base && abs < m.base + m.size {
let rel = abs - m.base;
if rel + len > m.size {
return Err(StockError::Method(format!(
"write of {len} B at abs 0x{abs:x} overruns {} (rel 0x{rel:x}, size 0x{:x})",
m.dev, m.size
)));
}
return Ok((&m.dev, rel));
}
}
Err(StockError::Method(format!(
"no MTD partition exposes absolute offset 0x{abs:x} (is the boot region mapped?)"
)))
}
// ---------------------------------------------------------------------------
// NAND primitives
// ---------------------------------------------------------------------------
/// MD5 of `data` padded with 0xFF up to the next page boundary -- what a
/// `nandwrite -p` of `data` leaves on flash and what `nanddump -l <rounded>`
/// reads back.
fn padded_md5(data: &[u8]) -> String {
let rounded = round_up(data.len() as u64, PAGE) as usize;
let mut buf = data.to_vec();
buf.resize(rounded, 0xFF);
md5_hex(&buf)
}
/// Write `data` to absolute NAND offset `abs`, staging it in `/tmp/alk`, erasing
/// the covering erase blocks, writing with `nandwrite -p`, and verifying the
/// read-back against the padded MD5. `abs` must be erase-block aligned.
fn write_abs(
sh: &mut dyn Shell,
table: &[Mtd],
abs: u64,
data: &[u8],
label: &str,
) -> Result<(), StockError> {
if abs < BOOTBIN_PRESERVE {
return Err(StockError::Method(format!(
"refusing to write {label} at 0x{abs:x}: inside preserved BOOT.bin"
)));
}
if !abs.is_multiple_of(ERASE) {
return Err(StockError::Method(format!(
"{label} offset 0x{abs:x} is not erase-block aligned"
)));
}
let (dev, rel) = locate(table, abs, data.len() as u64)?;
let dev = dev.to_owned();
let blocks = round_up(data.len() as u64, ERASE) / ERASE;
let remote = format!("/tmp/alk/{label}.img");
sh.exec("mkdir -p /tmp/alk")?;
sh.put(data, &remote)?;
// Confirm the staged payload arrived intact before we erase anything.
let put_md5 = first_token(&sh.exec(&format!("md5sum {remote}"))?);
if put_md5 != md5_hex(data) {
return Err(StockError::Method(format!(
"{label}: staged copy md5 {put_md5} != {} (transfer corrupted)",
md5_hex(data)
)));
}
sh.exec_long(&format!(
"flash_erase /dev/{dev} 0x{rel:x} {blocks} >/dev/null 2>&1 && \
nandwrite -p -s 0x{rel:x} /dev/{dev} {remote} >/dev/null 2>&1 && echo WROTE"
))
.and_then(|o| {
if o.contains("WROTE") {
Ok(())
} else {
Err(StockError::Method(format!(
"{label}: erase/write failed: {o}"
)))
}
})?;
let readlen = round_up(data.len() as u64, PAGE);
let back = first_token(&sh.exec_long(&format!(
"nanddump -s 0x{rel:x} -l {readlen} /dev/{dev} 2>/dev/null | md5sum"
))?);
let want = padded_md5(data);
if back != want {
return Err(StockError::Method(format!(
"{label}: read-back md5 {back} != {want} at /dev/{dev} rel 0x{rel:x} \
(write did not persist)"
)));
}
sh.exec(&format!("rm -f {remote}"))?;
Ok(())
}
/// Copy `len` bytes already on NAND from absolute `src` to absolute `dst`
/// (used when carving the on-board stock backup). `dst` must be erase aligned.
fn copy_abs(
sh: &mut dyn Shell,
table: &[Mtd],
src: u64,
dst: u64,
len: u64,
label: &str,
) -> Result<(), StockError> {
let (sdev, srel) = locate(table, src, len)?;
let sdev = sdev.to_owned();
let (ddev, drel) = locate(table, dst, len)?;
let ddev = ddev.to_owned();
let blocks = round_up(len, ERASE) / ERASE;
let tmp = format!("/tmp/alk/{label}.bak");
sh.exec("mkdir -p /tmp/alk")?;
let out = sh.exec_long(&format!(
"nanddump -s 0x{srel:x} -l {len} /dev/{sdev} -f {tmp} >/dev/null 2>&1 && \
flash_erase /dev/{ddev} 0x{drel:x} {blocks} >/dev/null 2>&1 && \
nandwrite -p -s 0x{drel:x} /dev/{ddev} {tmp} >/dev/null 2>&1 && \
rm -f {tmp} && echo COPIED"
))?;
if !out.contains("COPIED") {
return Err(StockError::Method(format!(
"{label}: backup copy failed: {out}"
)));
}
Ok(())
}
/// Read `len` (even) bytes from NAND at (dev, rel) as raw bytes, via
/// `od -v -x`, which is the only `od` form the stock busybox understands (no
/// `-A`/`-t`). The leading octal address column and trailing byte-count line are
/// discarded by [`parse_od`].
fn read_small(sh: &mut dyn Shell, dev: &str, rel: u64, len: u64) -> Result<Vec<u8>, StockError> {
let out = sh.exec(&format!(
"nanddump -s 0x{rel:x} -l {len} /dev/{dev} 2>/dev/null | od -v -x"
))?;
Ok(parse_od(&out))
}
/// Read a big-endian u32 at byte `field_off` within the image whose header
/// starts at the (page-aligned) absolute NAND offset `region_abs`. `nanddump`
/// needs a page-aligned `-s`, so we read the first 64 bytes of the region and
/// slice the field in Rust (used to size the genuine stock images from their
/// uImage / fdt headers before backing up).
fn read_header_u32_be(
sh: &mut dyn Shell,
table: &[Mtd],
region_abs: u64,
field_off: usize,
) -> Result<u32, StockError> {
let (dev, rel) = locate(table, region_abs, 64)?;
let dev = dev.to_owned();
let b = read_small(sh, &dev, rel, 64)?;
if b.len() < field_off + 4 {
return Err(StockError::Method(format!(
"short header read at 0x{region_abs:x} ({} bytes)",
b.len()
)));
}
Ok(u32::from_be_bytes([
b[field_off],
b[field_off + 1],
b[field_off + 2],
b[field_off + 3],
]))
}
fn first_token(s: &str) -> String {
s.split_whitespace().next().unwrap_or("").to_owned()
}
// ---------------------------------------------------------------------------
// On-board stock backup manifest
// ---------------------------------------------------------------------------
#[derive(Clone, Debug)]
struct BackupManifest {
kernel_abs: u64,
kernel_len: u64,
dtb_abs: u64,
dtb_len: u64,
rootfs_abs: u64,
rootfs_len: u64,
}
impl BackupManifest {
fn encode(&self) -> Vec<u8> {
let mut v = Vec::with_capacity(64);
v.extend_from_slice(BK_MAGIC);
for n in [
self.kernel_abs,
self.kernel_len,
self.dtb_abs,
self.dtb_len,
self.rootfs_abs,
self.rootfs_len,
] {
v.extend_from_slice(&n.to_be_bytes());
}
v
}
fn decode(b: &[u8]) -> Option<Self> {
if b.len() < 8 + 6 * 8 || &b[..8] != BK_MAGIC {
return None;
}
let g = |i: usize| {
let mut a = [0u8; 8];
a.copy_from_slice(&b[8 + i * 8..8 + i * 8 + 8]);
u64::from_be_bytes(a)
};
Some(BackupManifest {
kernel_abs: g(0),
kernel_len: g(1),
dtb_abs: g(2),
dtb_len: g(3),
rootfs_abs: g(4),
rootfs_len: g(5),
})
}
}
/// Carve the genuine stock kernel + dtb + ramdisk (still on NAND) into the
/// stock-backup region, with a manifest in its first block, so the board can be
/// returned to its own factory stock later with no vendor file. Called on the
/// stock side during a from-stock install, before the boot slots are overwritten.
fn carve_backup(sh: &mut dyn Shell, table: &[Mtd]) -> Result<BackupManifest, StockError> {
// Size the genuine images from their on-NAND headers (uImage data size at
// header offset 12; fdt totalsize at offset 4).
let kernel_len = 64 + read_header_u32_be(sh, table, OFF_KERNEL, 12)? as u64;
let dtb_len = read_header_u32_be(sh, table, OFF_DTB, 4)? as u64;
let rootfs_len = 64 + read_header_u32_be(sh, table, OFF_ROOTFS, 12)? as u64;
// Sanity: headers must look like a uImage/fdt, sizes within slots.
if !(64..=SLOT_KERNEL).contains(&kernel_len) || !(64..=SLOT_ROOTFS).contains(&rootfs_len) {
return Err(StockError::Method(format!(
"stock image sizes implausible (kernel {kernel_len}, rootfs {rootfs_len}); \
refusing to back up"
)));
}
let k_dst = BK_MANIFEST + ERASE; // images follow the manifest block
let d_dst = k_dst + round_up(kernel_len, ERASE);
let r_dst = d_dst + round_up(dtb_len, ERASE);
if r_dst + round_up(rootfs_len, ERASE) > OFF_STOCK_BACKUP + SLOT_STOCK_BACKUP {
return Err(StockError::Method(
"stock backup does not fit in the 32 MiB backup region".into(),
));
}
copy_abs(sh, table, OFF_KERNEL, k_dst, kernel_len, "stock-kernel")?;
copy_abs(sh, table, OFF_DTB, d_dst, dtb_len, "stock-dtb")?;
copy_abs(sh, table, OFF_ROOTFS, r_dst, rootfs_len, "stock-rootfs")?;
let manifest = BackupManifest {
kernel_abs: k_dst,
kernel_len,
dtb_abs: d_dst,
dtb_len,
rootfs_abs: r_dst,
rootfs_len,
};
write_abs(
sh,
table,
BK_MANIFEST,
&manifest.encode(),
"stock-backup-manifest",
)?;
Ok(manifest)
}
/// Read and validate the on-board backup manifest, if present.
fn read_backup_manifest(
sh: &mut dyn Shell,
table: &[Mtd],
) -> Result<Option<BackupManifest>, StockError> {
let (dev, rel) = match locate(table, BK_MANIFEST, 64) {
Ok(v) => v,
Err(_) => return Ok(None), // region not mapped -> treat as absent
};
let dev = dev.to_owned();
// Pull the 64-byte manifest off NAND via `od -v -x` (busybox-safe) and parse.
let bytes = read_small(sh, &dev, rel, 64)?;
Ok(BackupManifest::decode(&bytes))
}
/// Parse `od` hex output into bytes. Accepts both `-tx1` (byte hex) and `-x`
/// (little-endian 16-bit words).
fn parse_od(s: &str) -> Vec<u8> {
let toks: Vec<&str> = s.split_whitespace().collect();
// Heuristic: 2-char tokens are bytes (-tx1); 4-char tokens are LE words (-x).
let mut out = Vec::new();
for t in &toks {
match t.len() {
2 => {
if let Ok(b) = u8::from_str_radix(t, 16) {
out.push(b);
}
}
4 => {
if let Ok(w) = u16::from_str_radix(t, 16) {
out.push((w & 0xff) as u8);
out.push((w >> 8) as u8);
}
}
_ => {}
}
}
out
}
// ---------------------------------------------------------------------------
// Operations
// ---------------------------------------------------------------------------
/// What to write to the three boot slots (already in the exact on-NAND form:
/// kernel and rootfs as legacy uImages, dtb as a raw fdt).
struct BootImages {
kernel_uimage: Vec<u8>,
dtb: Vec<u8>,
rootfs_uimage: Vec<u8>,
}
fn write_boot_slots(sh: &mut dyn Shell, table: &[Mtd], img: &BootImages) -> Result<(), StockError> {
// rootfs, dtb, kernel order: an interrupted run never leaves a new rootfs
// under an old kernel.
if img.rootfs_uimage.len() as u64 > SLOT_ROOTFS {
return Err(StockError::Method("rootfs over slot ceiling".into()));
}
if img.dtb.len() as u64 > SLOT_DTB {
return Err(StockError::Method("dtb over slot ceiling".into()));
}
if img.kernel_uimage.len() as u64 > SLOT_KERNEL {
return Err(StockError::Method("kernel over slot ceiling".into()));
}
write_abs(sh, table, OFF_ROOTFS, &img.rootfs_uimage, "rootfs")?;
write_abs(sh, table, OFF_DTB, &img.dtb, "dtb")?;
write_abs(sh, table, OFF_KERNEL, &img.kernel_uimage, "kernel")?;
Ok(())
}
/// Whether the connected board is a Zynq, so the readable boot-slot path
/// applies. Other boards fall back to the compiled-in method.
fn shell_is_zynq(sh: &mut dyn Shell) -> bool {
sh.exec(
"(grep -qi zynq /proc/cpuinfo 2>/dev/null || \
grep -qai zynq /proc/device-tree/compatible 2>/dev/null) && echo yes || true",
)
.map(|o| o.contains("yes"))
.unwrap_or(false)
}
fn reboot(sh: &mut dyn Shell) {
// Best-effort: the reboot drops the shell, so ignore the result.
let _ = sh.exec("sync; (sleep 1; reboot) >/dev/null 2>&1 &");
}
/// Install alkane onto a board currently on stock, over the network. The afw
/// ships a raw `zImage`, a raw fdt and a gzipped cpio rootfs; we wrap the kernel
/// and rootfs as the legacy uImages the preserved stock U-Boot boots, carve the
/// genuine stock backup first, then write the boot slots and reboot.
pub fn install_from_stock(
host: &str,
kernel_zimage: &[u8],
dtb: &[u8],
rootfs_cpio_gz: &[u8],
password: Option<&str>,
) -> Result<(), StockError> {
let mut sh = StockShell {
host: host.to_owned(),
password: password.map(str::to_owned),
};
if first_token(&sh.exec("id -u")?) != "0" {
return Err(StockError::Auth(
"did not obtain root on the stock board".into(),
));
}
let table = read_mtd_table(&mut sh)?;
// Carve the genuine-stock backup from the live stock NAND before any write.
carve_backup(&mut sh, &table)?;
let img = BootImages {
kernel_uimage: uimage::wrap(Kind::Kernel, kernel_zimage, 0, "alkane-kernel"),
dtb: dtb.to_vec(),
rootfs_uimage: uimage::wrap(Kind::Ramdisk, rootfs_cpio_gz, 0, "alkane-rootfs"),
};
write_boot_slots(&mut sh, &table, &img)?;
reboot(&mut sh);
Ok(())
}
/// Return an alkane board to genuine stock by writing the vendor images back to
/// the boot slots over SSH. `dtb` is the genuine per-board device tree (from the
/// vendor package); if `None`, the stock dtb saved in the on-board backup is
/// used. `kernel`/`rootfs` are the vendor legacy uImages, written as-is.
pub fn restore_to_stock(
host: &str,
kernel_uimage: &[u8],
rootfs_uimage: &[u8],
dtb: Option<&[u8]>,
password: Option<&str>,
) -> Result<(), StockError> {
let mut sh = AlkaneShell::connect(host, password)?;
if !shell_is_zynq(&mut sh) {
return Err(StockError::NotApplicable);
}
let table = read_mtd_table(&mut sh)?;
if rootfs_uimage.len() as u64 > SLOT_ROOTFS || kernel_uimage.len() as u64 > SLOT_KERNEL {
return Err(StockError::Method("vendor image over slot ceiling".into()));
}
// rootfs, dtb, kernel order (same safety ordering as install).
write_abs(&mut sh, &table, OFF_ROOTFS, rootfs_uimage, "rootfs")?;
match dtb {
Some(d) => {
if d.len() as u64 > SLOT_DTB {
return Err(StockError::Method("dtb over slot ceiling".into()));
}
write_abs(&mut sh, &table, OFF_DTB, d, "dtb")?;
}
None => {
// No vendor dtb (an OTA package omits it): restore the genuine
// per-board dtb from the on-board backup by copying within NAND.
let manifest = read_backup_manifest(&mut sh, &table)?.ok_or_else(|| {
StockError::Method(
"no stock dtb supplied and no on-board backup to take one from".into(),
)
})?;
copy_abs(
&mut sh,
&table,
manifest.dtb_abs,
OFF_DTB,
manifest.dtb_len,
"dtb",
)?;
}
}
write_abs(&mut sh, &table, OFF_KERNEL, kernel_uimage, "kernel")?;
reboot(&mut sh);
Ok(())
}
/// Whether the board holds a complete, restorable on-board stock backup.
pub fn onboard_backup_present(host: &str, password: Option<&str>) -> Result<bool, StockError> {
let mut sh = AlkaneShell::connect(host, password)?;
if !shell_is_zynq(&mut sh) {
return Err(StockError::NotApplicable);
}
let table = read_mtd_table(&mut sh)?;
Ok(read_backup_manifest(&mut sh, &table)?.is_some())
}
/// Return an alkane board to stock using only the on-board backup (no vendor
/// file): copy the saved stock kernel, dtb and rootfs back to the boot slots.
pub fn restore_from_onboard(host: &str, password: Option<&str>) -> Result<(), StockError> {
let mut sh = AlkaneShell::connect(host, password)?;
if !shell_is_zynq(&mut sh) {
return Err(StockError::NotApplicable);
}
let table = read_mtd_table(&mut sh)?;
let manifest = read_backup_manifest(&mut sh, &table)?
.ok_or_else(|| StockError::Method("no complete on-board stock backup".into()))?;
// Copy within NAND: backup region -> boot slots.
copy_abs(
&mut sh,
&table,
manifest.rootfs_abs,
OFF_ROOTFS,
manifest.rootfs_len,
"rootfs",
)?;
copy_abs(
&mut sh,
&table,
manifest.dtb_abs,
OFF_DTB,
manifest.dtb_len,
"dtb",
)?;
copy_abs(
&mut sh,
&table,
manifest.kernel_abs,
OFF_KERNEL,
manifest.kernel_len,
"kernel",
)?;
reboot(&mut sh);
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn round_up_works() {
assert_eq!(round_up(1, PAGE), PAGE);
assert_eq!(round_up(PAGE, PAGE), PAGE);
assert_eq!(round_up(PAGE + 1, PAGE), 2 * PAGE);
assert_eq!(round_up(0, ERASE), 0);
}
#[test]
fn padded_md5_matches_manual_pad() {
let data = b"hello";
let mut padded = data.to_vec();
padded.resize(PAGE as usize, 0xFF);
assert_eq!(padded_md5(data), md5_hex(&padded));
}
#[test]
fn manifest_roundtrips() {
let m = BackupManifest {
kernel_abs: 0x6020000,
kernel_len: 4006832,
dtb_abs: 0x6420000,
dtb_len: 7650,
rootfs_abs: 0x6440000,
rootfs_len: 26620582,
};
let enc = m.encode();
let dec = BackupManifest::decode(&enc).unwrap();
assert_eq!(dec.kernel_abs, m.kernel_abs);
assert_eq!(dec.rootfs_len, m.rootfs_len);
assert!(BackupManifest::decode(b"nope").is_none());
}
#[test]
fn locate_maps_absolute_to_partition() {
let table = vec![
Mtd {
dev: "mtd0".into(),
base: 0x0,
size: 0x2800000,
name: "x".into(),
},
Mtd {
dev: "mtd1".into(),
base: 0x2800000,
size: 0x2000000,
name: "y".into(),
},
];
assert_eq!(locate(&table, 0x2000000, 100).unwrap(), ("mtd0", 0x2000000));
assert_eq!(locate(&table, 0x2800000, 100).unwrap(), ("mtd1", 0));
assert!(locate(&table, 0x9000000, 1).is_err());
}
#[test]
fn parse_od_both_forms() {
// -tx1 byte form
assert_eq!(parse_od("41 42 43"), vec![0x41, 0x42, 0x43]);
// -x little-endian word form -> bytes
assert_eq!(parse_od("4241"), vec![0x41, 0x42]);
}
}
+340
View File
@@ -0,0 +1,340 @@
//! 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, the stock Antminer Zynq-7010 (S17/T17 era,
/// "XIL (C49)") control board, or the stock Amlogic A113D ("AML (C76)") control
/// board.
pub fn board_family(row: &MinerRow) -> Option<String> {
if let Some(board) = &row.alkane_board {
return (!board.is_empty()).then(|| board.clone());
}
// A stock A113D (Amlogic AXG) control board -- the "a113d" install target
// (board_labels maps a113d -> "AML (C76)"). Decided on the control-board
// code, not the brand: asic-rs has no make for the Antminer BHB42XXX and
// reports its brand as "Unknown" (model "Unknown: ANTMINER BHB42XXX"), so
// the generic brand guard below would otherwise reject it. The "AML" code is
// only ever derived for an Amlogic Antminer control board, so this is
// specific on its own.
if row.cpu == "AML" && row.board_code == "C76" {
return Some("a113d".to_string());
}
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
// The Amlogic A113D control board is the "a113d" install target.
assert!(install_supported(&stock("AML", "C76")));
assert_eq!(board_family(&stock("AML", "C76")).as_deref(), Some("a113d"));
assert!(!install_supported(&stock("AML", "CBE"))); // 140mm S19k/S21-class, not a target
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: an "S17" model on an
// Amlogic A113D control board resolves to a113d (the control board),
// not zynq (the model).
let s17_on_aml = MinerRow {
brand: "Antminer".into(),
model: "S17".into(),
cpu: "AML".into(),
board_code: "C76".into(),
..Default::default()
};
assert_eq!(board_family(&s17_on_aml).as_deref(), Some("a113d"));
}
#[test]
fn a_stock_a113d_bhb42xxx_is_an_install_target_despite_unknown_brand() {
// Exactly as the live scan reports the bench A113D at 10.255.1.18:
// asic-rs cannot pin a make, so brand is "Unknown" and the model is
// "Unknown: ANTMINER BHB42XXX", but the control board classifies as
// "AML (C76)". Install must still be offered.
let bhb = MinerRow {
brand: "Unknown".into(),
model: "Unknown: ANTMINER BHB42XXX".into(),
firmware: "Stock".into(),
cpu: "AML".into(),
board_code: "C76".into(),
..Default::default()
};
assert_eq!(board_family(&bhb).as_deref(), Some("a113d"));
assert!(install_supported(&bhb));
assert!(!is_alkane(&bhb));
}
/// 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));
}
}
+332
View File
@@ -0,0 +1,332 @@
//! Headless bench automation (`ALKANE_BENCH_SEQUENCE`): drive the GUI's real
//! install/restore operation layer (`stock_ops`) through the A113D network-only
//! install <-> flag-restore cycle, with no window. This exercises the GUI
//! operator flow end-to-end against real hardware, for bench proofs, without the
//! wx event loop (the worker functions stream progress over a channel, exactly
//! as the UI drains them).
//!
//! Spec: `ALKANE_BENCH_SEQUENCE="<host> <local.afw> [iterations]"`.
//! The alkane root credential is read from the saved SSH credentials file.
//!
//! On the A113D, "restore to stock" is the one-byte flag flip (the install
//! overwrites no stock partition), so the cycle is: install (stock -> alkane) ->
//! verify alkane -> restore (flag flip -> stock) -> verify stock.
use std::io::Read;
use std::net::TcpStream;
use std::path::PathBuf;
use std::process::Command;
use std::time::{Duration, Instant};
use crate::credentials;
use crate::stock_ops::{self, AfwSource, StockHandle, StockMsg};
/// Drain a `StockHandle` to completion, printing progress; returns true iff
/// every board reported ok and at least one `Result` arrived.
fn drive(label: &str, handle: StockHandle) -> bool {
let mut ok = true;
let mut saw = false;
loop {
match handle.rx.recv() {
Ok(StockMsg::Started) => println!(" [{label}] started"),
Ok(StockMsg::Progress(s)) => println!(" [{label}] {s}"),
Ok(StockMsg::Result { ip, ok: r, detail }) => {
saw = true;
ok = ok && r;
println!(
" [{label}] {ip}: {} - {detail}",
if r { "OK" } else { "FAIL" }
);
}
Ok(StockMsg::Done) => break,
Err(_) => {
println!(" [{label}] channel closed early");
ok = false;
break;
}
}
}
ok && saw
}
/// Read the SSH identification banner (no auth), e.g. `SSH-2.0-dropbear_2026.93`.
fn ssh_banner(host: &str) -> Option<String> {
let addr: std::net::SocketAddr = format!("{host}:22").parse().ok()?;
let mut stream = TcpStream::connect_timeout(&addr, Duration::from_secs(5)).ok()?;
stream.set_read_timeout(Some(Duration::from_secs(5))).ok()?;
let mut buf = [0u8; 256];
let n = stream.read(&mut buf).ok()?;
if n == 0 {
return None;
}
Some(
String::from_utf8_lossy(&buf[..n])
.lines()
.next()
.unwrap_or("")
.trim()
.to_string(),
)
}
/// HTTP server header probe (stock serves lighttpd / an antMiner realm).
fn http_is_stock(host: &str) -> Option<bool> {
let out = Command::new("curl")
.args([
"-sS",
"-m",
"6",
"-o",
"/dev/null",
"-D",
"-",
&format!("http://{host}/"),
])
.output()
.ok()?;
let h = String::from_utf8_lossy(&out.stdout).to_lowercase();
if h.is_empty() {
None
} else if h.contains("lighttpd") || h.contains("antminer configuration") {
Some(true)
} else {
Some(false)
}
}
/// Classify the board: `Some(true)` = looks like genuine stock, `Some(false)` =
/// looks like alkane, `None` = no decisive answer (e.g. mid-reboot).
///
/// Primary signal is the SSH banner: stock A113D is `dropbear_2018.76`; alkane
/// ships a much newer dropbear. HTTP (lighttpd) is a stock fallback.
fn classify(host: &str) -> (String, Option<bool>) {
let banner = ssh_banner(host);
if let Some(b) = &banner {
let lb = b.to_lowercase();
if lb.contains("dropbear_2018") || lb.contains("dropbear_2019") {
return (format!("ssh \"{b}\" -> stock"), Some(true));
}
if lb.contains("dropbear") || lb.contains("openssh") {
return (format!("ssh \"{b}\" -> alkane"), Some(false));
}
}
match http_is_stock(host) {
Some(true) => ("http lighttpd/antMiner -> stock".to_string(), Some(true)),
Some(false) => ("http non-stock -> alkane".to_string(), Some(false)),
None => (
banner
.map(|b| format!("ssh \"{b}\" (unclassified), no http"))
.unwrap_or_else(|| "no ssh, no http (mid-reboot?)".to_string()),
None,
),
}
}
/// The MAC (lladdr) the kernel has cached for `host` (pings first to populate).
fn mac_of(host: &str) -> Option<String> {
let _ = Command::new("ping")
.args(["-c", "1", "-W", "1", host])
.output();
let out = Command::new("ip")
.args(["neigh", "show", host])
.output()
.ok()?;
let s = String::from_utf8_lossy(&out.stdout);
let mut it = s.split_whitespace();
while let Some(t) = it.next() {
if t == "lladdr" {
return it.next().map(|m| m.to_lowercase());
}
}
None
}
/// Populate the neighbour table by parallel-pinging the /24 of `sample` (a bench
/// board can take a different DHCP lease across a reboot, so we must re-find it).
fn sweep_subnet(sample: &str) {
let base = match sample.rsplit_once('.') {
Some((net, _)) => net.to_string(),
None => return,
};
let mut kids = Vec::new();
for h in 2..=254 {
if let Ok(c) = Command::new("ping")
.args(["-c", "1", "-W", "1", &format!("{base}.{h}")])
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::null())
.spawn()
{
kids.push(c);
}
}
for mut c in kids {
let _ = c.wait();
}
}
/// Current IPv4 for `mac` from the neighbour table, if present.
fn ip_for_mac(mac: &str) -> Option<String> {
let out = Command::new("ip").args(["neigh"]).output().ok()?;
let s = String::from_utf8_lossy(&out.stdout);
let mac = mac.to_lowercase();
for line in s.lines() {
if line.to_lowercase().contains(&mac) {
if let Some(ip) = line.split_whitespace().next() {
if ip.contains('.') {
return Some(ip.to_string());
}
}
}
}
None
}
/// Poll until the board (located by MAC, so a changed DHCP lease is followed)
/// reaches the wanted stock-ness, or `timeout` elapses. Returns the board's
/// current IP, a description, and whether the target state was reached.
fn wait_for(
mac: Option<&str>,
fallback: &str,
want_stock: bool,
timeout: Duration,
) -> (String, String, bool) {
let deadline = Instant::now() + timeout;
let mut ip = fallback.to_string();
let mut swept = Instant::now() - Duration::from_secs(60);
loop {
// Re-locate by MAC; sweep the subnet at most every ~25s to catch a new lease.
if let Some(m) = mac {
if ip_for_mac(m).is_none() && swept.elapsed() >= Duration::from_secs(25) {
sweep_subnet(fallback);
swept = Instant::now();
}
if let Some(found) = ip_for_mac(m) {
ip = found;
}
}
let (desc, is_stock) = classify(&ip);
let line = format!("[{ip}] {desc}");
if is_stock == Some(want_stock) {
return (ip, line, true);
}
if Instant::now() >= deadline {
return (ip, line, false);
}
std::thread::sleep(Duration::from_secs(5));
}
}
pub fn run(spec: &str) -> i32 {
let mut it = spec.split_whitespace();
let host = match it.next() {
Some(h) => h.to_string(),
None => {
eprintln!("ALKANE_BENCH_SEQUENCE=\"<host> <local.afw> [iterations]\"");
return 2;
}
};
let afw = match it.next() {
Some(a) => PathBuf::from(a),
None => {
eprintln!("missing local .afw path");
return 2;
}
};
let iterations: u32 = it.next().and_then(|s| s.parse().ok()).unwrap_or(1);
let board = "a113d".to_string();
// Install reaches STOCK via the compiled-in from-stock method; pass the saved
// board SSH credential through to it.
let stock_password = credentials::load_ssh_credentials().map(|(_, p)| p);
// The flag-restore reaches the running ALKANE board over SSH as `root` - a
// DIFFERENT credential from the stock login. Alkane bench images bake
// root/alkane; allow an override via ALKANE_ROOT_PASSWORD.
let alkane_password = std::env::var("ALKANE_ROOT_PASSWORD")
.ok()
.or_else(|| Some("alkane".to_string()));
println!("== A113D headless GUI bench sequence (network-only install <-> flag-restore) ==");
println!(
"host={host} afw={} board={board} iterations={iterations} stock_cred={} alkane_cred={}",
afw.display(),
if stock_password.is_some() { "loaded" } else { "none" },
if alkane_password.is_some() { "set" } else { "none" }
);
if !afw.exists() {
eprintln!("afw not found: {}", afw.display());
return 2;
}
// Resolve the board's MAC now (on stock) so we can re-find it after each
// reboot even if its DHCP lease changes under alkane.
let mac = mac_of(&host);
println!(
"board MAC: {}",
mac.as_deref()
.unwrap_or("unknown (will use the fixed host)")
);
let boot_timeout = Duration::from_secs(300);
let mut all_ok = true;
for i in 1..=iterations {
println!("\n-- iteration {i}/{iterations} --");
// 1. install (stock -> alkane) through the GUI operation layer
println!("[1/4] install: stock -> alkane");
let h = stock_ops::start_install(
vec![host.clone()],
board.clone(),
AfwSource::Local(afw.clone()),
true, // allow unsigned (bench image)
stock_password.clone(),
false, // not an in-place update
);
if !drive("install", h) {
all_ok = false;
println!("[1/4] install FAILED; aborting");
break;
}
// 2. verify alkane is live (board reboots into alkane)
println!(
"[2/4] verify alkane (awaiting reboot, up to {}s)...",
boot_timeout.as_secs()
);
let (alkane_ip, desc, ok) = wait_for(mac.as_deref(), &host, false, boot_timeout);
println!(
" {desc} => {}",
if ok { "ALKANE" } else { "NOT ALKANE (fail)" }
);
all_ok = all_ok && ok;
// 3. restore (alkane -> stock) flag-flip at the board's CURRENT address
println!("[3/4] restore: alkane -> stock (flag flip) at {alkane_ip}");
let h = stock_ops::start_restore_flag(vec![alkane_ip.clone()], alkane_password.clone());
if !drive("restore", h) {
all_ok = false;
println!("[3/4] restore FAILED");
}
// 4. verify stock is back
println!(
"[4/4] verify stock (awaiting reboot, up to {}s)...",
boot_timeout.as_secs()
);
let (_stock_ip, desc, ok) = wait_for(mac.as_deref(), &host, true, boot_timeout);
println!(
" {desc} => {}",
if ok { "STOCK" } else { "NOT STOCK (fail)" }
);
all_ok = all_ok && ok;
}
println!(
"\n== BENCH RESULT: {} ==",
if all_ok { "PASS" } else { "FAIL" }
);
if all_ok {
0
} else {
1
}
}
+15
View File
@@ -106,6 +106,9 @@ pub fn clear_credentials() -> std::io::Result<()> {
/// duplicated here; a firmware absent from this table defaults to blank.
pub fn firmware_default_creds() -> &'static [(&'static str, &'static str, &'static str)] {
&[
// Alkane OS ships with this control-board login, so restore-to-stock on
// an alkane board authenticates with no operator setup (issue #51).
("Alkane", "root", "alkane"),
("AntMiner Stock", "root", "root"),
("WhatsMiner Stock", "admin", "admin"),
("Braiins", "root", "root"),
@@ -134,6 +137,18 @@ pub fn firmware_default_for(name: &str) -> (String, String) {
.unwrap_or_default()
}
/// The login to use for a board running `firmware`: the operator's saved
/// per-firmware override if any, else the shipped default. This is how install
/// (a stock target) and restore (an alkane target) each pick the right login
/// automatically, without a password field in the dialog (issues #46, #51).
pub fn cred_for(firmware: &str) -> (String, String) {
load_firmware_credentials()
.get(firmware)
.cloned()
.filter(|(_, p)| !p.is_empty())
.unwrap_or_else(|| firmware_default_for(firmware))
}
/// Load the operator's per-firmware credential overrides, keyed by firmware
/// Display name. Malformed lines are skipped.
pub fn load_firmware_credentials() -> HashMap<String, (String, String)> {
+17 -3
View File
@@ -6,7 +6,9 @@
#![cfg_attr(windows, windows_subsystem = "windows")]
mod access_probe;
mod alkane_detect;
mod askpass;
mod bench_sequence;
mod bug_report;
mod credentials;
mod export;
@@ -40,6 +42,13 @@ fn main() {
std::process::exit(run_selftest());
}
// Headless bench automation: drive the real install/restore operation layer
// (stock_ops) through the A113D network-only install <-> flag-restore cycle
// against real hardware, with no window. See bench_sequence.rs.
if let Some(spec) = std::env::var_os("ALKANE_BENCH_SEQUENCE") {
std::process::exit(bench_sequence::run(&spec.to_string_lossy()));
}
// Headless access-probe check: `ALKANE_ACCESS_PROBE="<ip> <make>"` prints the
// lock state the real access probe computes (no GUI, no wx), so the WhatsMiner
// :4028 token check and the Antminer digest check can be verified directly.
@@ -122,9 +131,14 @@ fn run_selftest() -> i32 {
/// True when the process runs one of the headless check modes instead of the GUI.
fn headless_mode() -> bool {
["ALKANE_SELFTEST", "ALKANE_ACCESS_PROBE", "ALKANE_LOG_SCAN"]
.iter()
.any(|v| std::env::var_os(v).is_some())
[
"ALKANE_SELFTEST",
"ALKANE_ACCESS_PROBE",
"ALKANE_LOG_SCAN",
"ALKANE_BENCH_SEQUENCE",
]
.iter()
.any(|v| std::env::var_os(v).is_some())
}
/// A Windows GUI-subsystem process has no console, so output from the headless
+62 -3
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).
@@ -688,9 +692,18 @@ impl MinerRow {
/// live); grey (unknown) otherwise -- asic-rs has no direct PSU-fault flag, so
/// a missing wattage reading is treated as unknown, never a false "down".
pub fn power_health(&self) -> CompHealth {
// A miner drawing power / spinning its PSU fan / actively mining has a live
// PSU regardless of any warning flag.
let delivering = self.power_w > 0.0 || self.psu_fan_rpm > 0.0 || self.is_mining;
// A live PSU shows real evidence: measured draw, a spinning PSU fan, or
// reported PSU output. A stock control board can assert a cgminer "mining"
// status with no PSU and no hashboards attached (issue #39: a bare S17
// control board showed a green PSU), so is_mining counts only when the
// miner is actually hashing (hashrate, or at least one healthy board).
let actually_hashing =
self.hashrate_ths > 0.0 || self.board_status.contains(&BoardHealth::Ok);
let delivering = self.power_w > 0.0
|| self.psu_fan_rpm > 0.0
|| self.psu_out_voltage_v.is_some()
|| self.psu_out_current_a.is_some()
|| (self.is_mining && actually_hashing);
// A reported PSU fault while the miner is actually mining is a warning, not
// a failure -- yellow, not red (round 18 #2: some WhatsMiners flag a PSU
// error while running fine). A fault on a miner that is not mining is a real
@@ -2472,6 +2485,52 @@ mod tests {
);
}
#[test]
fn stock_board_with_nothing_attached_shows_grey_psu() {
// Issue #39: a stock S17 control board with no PSU and no hashboards
// attached asserts a cgminer "mining" status (is_mining = true) while
// reporting zero watts, no PSU fan, and no PSU output. That is not
// evidence of a live PSU, so the bolt must read grey (Unreachable).
let bare = MinerRow {
is_mining: true,
power_w: 0.0,
psu_fan_rpm: 0.0,
hashrate_ths: 0.0,
board_status: vec![BoardHealth::Missing, BoardHealth::Missing],
..Default::default()
};
assert_eq!(bare.power_health(), CompHealth::Unreachable);
// A genuinely-running miner still greens: is_mining with real hashing is
// evidence enough even when the firmware reports no watts.
let hashing = MinerRow {
is_mining: true,
power_w: 0.0,
psu_fan_rpm: 0.0,
hashrate_ths: 90.0,
board_status: vec![BoardHealth::Ok, BoardHealth::Ok],
..Default::default()
};
assert_eq!(hashing.power_health(), CompHealth::Ok);
// Measured draw alone is always enough.
let drawing = MinerRow {
is_mining: false,
power_w: 19.0,
..Default::default()
};
assert_eq!(drawing.power_health(), CompHealth::Ok);
// Reported PSU output alone is enough even with zero measured watts.
let psu_out = MinerRow {
is_mining: false,
power_w: 0.0,
psu_out_voltage_v: Some(12.0),
..Default::default()
};
assert_eq!(psu_out.power_health(), CompHealth::Ok);
}
#[test]
fn warning_fault_degrades_board_to_yellow_not_red() {
// Round 21 #1: a board still mining near full hashrate with some failed/
+119 -19
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),
}
}
})
@@ -671,6 +674,62 @@ fn messages_to_faults(
.collect()
}
/// A hashboard's health dot from its reported activity. `active` is the firmware's
/// active flag; `working_chips` its working-chip count. Green needs positive
/// evidence (active, or a nonzero chip count); a board with neither flag nor count
/// reads grey ("not detected") rather than green (issue #39: an S17 control board
/// with no hashboards attached showed its boards green). A board that is present
/// but idle or has zero working chips reads as a fault (red).
fn board_health(
active: Option<bool>,
working_chips: Option<u16>,
miner_active: bool,
) -> crate::model::BoardHealth {
use crate::model::BoardHealth;
match (active, working_chips) {
(Some(true), _) => BoardHealth::Ok,
(Some(false), _) => BoardHealth::Fault,
(None, Some(c)) if c > 0 => BoardHealth::Ok,
(None, Some(_)) => BoardHealth::Fault,
// No per-board evidence. If the miner shows overall activity (hashing),
// the board is clearly present and working -> green; only an idle miner
// with no board telemetry reads grey (issue #39: bare S17; review #3: do
// not grey a genuinely-mining miner whose backend omits per-board fields).
(None, None) => {
if miner_active {
BoardHealth::Ok
} else {
BoardHealth::Missing
}
}
}
}
#[cfg(test)]
mod board_health_tests {
use super::board_health;
use crate::model::BoardHealth;
#[test]
fn no_activity_evidence_reads_grey_not_green() {
// Issue #39: the firmware lists a board but reports no active flag and no
// working-chip count -> not detected (grey), not green.
// Idle miner, no per-board evidence -> not detected (grey).
assert_eq!(board_health(None, None, false), BoardHealth::Missing);
// Mining miner, no per-board evidence -> still green (review #3).
assert_eq!(board_health(None, None, true), BoardHealth::Ok);
// Positive evidence still greens regardless of miner activity.
assert_eq!(board_health(Some(true), None, false), BoardHealth::Ok);
assert_eq!(board_health(None, Some(63), false), BoardHealth::Ok);
// Present but idle / zero working chips -> fault (red).
assert_eq!(
board_health(Some(false), Some(63), false),
BoardHealth::Fault
);
assert_eq!(board_health(None, Some(0), false), BoardHealth::Fault);
}
}
#[cfg(test)]
mod board_index_tests {
use super::board_index_from_text;
@@ -1186,18 +1245,7 @@ async fn to_row(miner: &dyn Miner) -> MinerRow {
let mut board_status: Vec<crate::model::BoardHealth> = data
.hashboards
.iter()
.map(|b| {
let ok = match (b.active, b.working_chips) {
(Some(a), _) => a,
(None, Some(c)) => c > 0,
(None, None) => true,
};
if ok {
crate::model::BoardHealth::Ok
} else {
crate::model::BoardHealth::Fault
}
})
.map(|b| board_health(b.active, b.working_chips, is_mining || hashrate_ths > 0.0))
.collect();
if let Some(exp) = data.expected_hashboards {
while board_status.len() < exp as usize {
@@ -1229,6 +1277,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 +1967,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 +2677,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),
);
}
}
}
+221 -28
View File
@@ -24,8 +24,13 @@ 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)")];
pub const SUPPORTED_BOARDS: &[(&str, &str)] = &[
("zynq-7010", "Antminer S17 (Xilinx Zynq-7010 control board)"),
(
"a113d",
"Antminer S19j Pro (Amlogic A113D/AXG control board)",
),
];
/// The default install board when the user has not chosen another.
pub const DEFAULT_BOARD: &str = "zynq-7010";
@@ -34,12 +39,26 @@ 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,
/// Where the `.afw` to install comes from. `Release` is a scanned Gitea asset
/// (its filename and download URL), fetched on the worker thread so the download
/// never blocks the UI. `Local` is a file the operator picked with the Browse
/// button -- the same local-file install the CLI offers, now in the GUI too.
pub enum AfwSource {
Release { name: String, url: String },
Local(PathBuf),
}
impl AfwSource {
/// A short human label for the status line (the filename in both cases).
fn label(&self) -> String {
match self {
AfwSource::Release { name, .. } => name.clone(),
AfwSource::Local(p) => p
.file_name()
.map(|n| n.to_string_lossy().into_owned())
.unwrap_or_else(|| p.to_string_lossy().into_owned()),
}
}
}
/// Progress + results streamed from the background worker to the UI.
@@ -81,9 +100,10 @@ fn download_dir() -> PathBuf {
pub fn start_install(
ips: Vec<String>,
board: String,
source: AfwChoice,
source: AfwSource,
allow_unsigned: bool,
password: Option<String>,
is_update: bool,
) -> StockHandle {
let (tx, rx) = channel();
let cancel = Arc::new(AtomicBool::new(false));
@@ -111,26 +131,49 @@ pub fn start_install(
.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}"),
});
// 1. Acquire the .afw: a local file is used in place; a release asset
// is downloaded on this worker thread (never blocking the UI).
let afw_path = match source {
AfwSource::Local(path) => {
let _ = tx.send(StockMsg::Progress(format!(
"using local {}...",
AfwSource::Local(path.clone()).label()
)));
if !path.is_file() {
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: format!("local .afw not found: {}", path.display()),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
path
}
AfwSource::Release { name, url } => {
let _ = tx.send(StockMsg::Progress("acquiring .afw...".into()));
match fetch::fetch_afw_url(
&ReleaseSource::alkane_os(),
&name,
&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;
}
}
let _ = tx.send(StockMsg::Done);
return;
}
};
@@ -170,6 +213,22 @@ pub fn start_install(
let _ = tx.send(StockMsg::Done);
return;
}
// An in-place Update must never rewrite the bootloader (review #1):
// refuse a tier-3 (bootloader-writing) bundle so the "BOOT.bin is
// never written" guarantee holds for an already-alkane board.
if is_update && verified.manifest.flash_plan().writes_uboot {
for ip in &ips {
let _ = tx.send(StockMsg::Result {
ip: ip.clone(),
ok: false,
detail: "update refused: this release reflashes the bootloader (tier 3); \
pick a tier-1/2 release or use Install"
.to_string(),
});
}
let _ = tx.send(StockMsg::Done);
return;
}
// 3. Install onto each board via the network-only from-stock method.
for ip in ips {
@@ -220,6 +279,7 @@ fn restore_one(ip: &str, firmware: &Path, password: Option<&str>) -> (bool, Stri
let images = RestoreImages {
kernel: &fw.kernel,
rootfs: &fw.rootfs,
dtb: fw.dtb.as_deref(),
};
match stock::restore_to_stock(ip, &images, password) {
Ok(()) => (
@@ -282,3 +342,136 @@ pub fn start_restore(ips: Vec<String>, firmware: PathBuf, password: Option<Strin
}
StockHandle { rx, cancel }
}
/// Whether a board holds a restorable on-board stock backup (network probe). A
/// quick, synchronous check the restore dialog uses to grey out the on-board
/// option when no backup is present. Any error reads as "not present".
pub fn onboard_backup_present(ip: &str, password: Option<&str>) -> bool {
if fake_scan_enabled() {
return true;
}
stock::onboard_stock_backup_present(ip, password).unwrap_or(false)
}
/// Restore the given alkane boards to genuine stock, over the network, from each
/// board's own on-board stock backup (no vendor firmware file). `password`, if
/// set, is the board's alkane root credential.
pub fn start_restore_onboard(ips: Vec<String>, 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 from on-board backup (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-onboard".into())
.spawn(move || {
let _ = tx.send(StockMsg::Started);
let timeout = std::time::Duration::from_secs(300);
for ip in ips {
if tc.load(Ordering::Relaxed) {
break;
}
let _ = tx.send(StockMsg::Progress(format!(
"restoring {ip} to stock from its on-board backup..."
)));
let (ok, detail) =
match stock::restore_from_onboard_backup(&ip, password.as_deref(), timeout) {
Ok(()) => (
true,
"restored to stock from on-board backup (verify over the network)"
.to_string(),
),
Err(e) => (false, format!("restore 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 restore worker thread".into(),
});
let _ = err_tx.send(StockMsg::Done);
}
StockHandle { rx, cancel }
}
/// Restore the given alkane A113D boards to genuine Bitmain stock, over the
/// network, by clearing the one-byte boot flag in-band from the running alkane
/// OS. The A113D install overwrites no stock partition, so this flag flip is the
/// complete restore: clear `ALAN`, reboot, and stock boots via `storeboot` from
/// the untouched `boot` MTD. No vendor firmware file or on-board backup needed.
/// `password`, if set, is the board's alkane root credential.
pub fn start_restore_flag(ips: Vec<String>, 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 (flag flip, 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-flag".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 (clearing the alkane boot flag)..."
)));
let (ok, detail) = match stock::restore_aml_flag(&ip, password.as_deref()) {
Ok(()) => (
true,
"restored to stock (flag cleared, rebooting; verify over the network)"
.to_string(),
),
Err(e) => (false, format!("restore 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 restore worker thread".into(),
});
let _ = err_tx.send(StockMsg::Done);
}
StockHandle { rx, cancel }
}
File diff suppressed because it is too large Load Diff
+23 -10
View File
@@ -131,17 +131,30 @@ 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 and choose:
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 (from stock)..." - 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 from-stock engine the
CLI uses.
- "Uninstall alkane OS (restore to stock)..." - takes the board's alkane root
password and a typed FLASH confirmation, then restores each selected board to
genuine stock over the network.
- "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, then - when you click Install - downloads and
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 and a genuine Bitmain firmware package,
then - when you click Restore - 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).
+43
View File
@@ -0,0 +1,43 @@
Subject: [PATCH 0012] linux: word-wrapping multiline text control
--- a/cpp_src/widgets_bridge.cpp
+++ b/cpp_src/widgets_bridge.cpp
@@ -890,6 +890,15 @@
wxDefaultPosition, wxSize(-1, -1), style);
}
+// A multiline text control that word-wraps at the control's width instead of
+// scrolling horizontally (no wxTE_DONTWRAP). For prose entry such as the bug
+// report box, where long lines should wrap rather than run off the edge.
+void* wxbr_text_ctrl_wrap(void* parent) {
+ return (void*)new wxTextCtrl((wxWindow*)parent, wxID_ANY, wxT(""),
+ wxDefaultPosition, wxSize(-1, -1),
+ wxTE_MULTILINE | wxTE_BESTWRAP);
+}
+
// A single-line text control that masks its content (wxTE_PASSWORD), for secret
// entry so a saved password is never rendered in the clear (round 18 #12).
void* wxbr_text_ctrl_password(void* parent) {
--- a/src/widgets.rs
+++ b/src/widgets.rs
@@ -41,6 +41,7 @@
pub fn wxbr_button(parent: *mut c_void, label: *const c_char, id: c_int) -> *mut c_void;
pub fn wxbr_bind_click(win: *mut c_void, id: c_int);
pub fn wxbr_text_ctrl(parent: *mut c_void, multiline: c_int) -> *mut c_void;
+ pub fn wxbr_text_ctrl_wrap(parent: *mut c_void) -> *mut c_void;
pub fn wxbr_text_ctrl_password(parent: *mut c_void) -> *mut c_void;
pub fn wxbr_text_ctrl_get(win: *mut c_void, buf: *mut c_char, cap: c_int) -> c_int;
pub fn wxbr_text_ctrl_set(win: *mut c_void, value: *const c_char);
@@ -463,6 +464,12 @@
Widget(unsafe { notsafe::wxbr_text_ctrl(parent.0, multiline as c_int) })
}
+ /// A multiline text control that word-wraps at its width (no horizontal
+ /// scroll), for prose entry such as the bug-report box.
+ pub fn text_ctrl_wrapped(parent: Widget) -> Widget {
+ Widget(unsafe { notsafe::wxbr_text_ctrl_wrap(parent.0) })
+ }
+
/// A single-line text control that masks its content (for password entry).
pub fn password_ctrl(parent: Widget) -> Widget {
Widget(unsafe { notsafe::wxbr_text_ctrl_password(parent.0) })
+38
View File
@@ -0,0 +1,38 @@
Subject: [PATCH 0013] linux: Enable/disable (grey out) a control
--- a/cpp_src/widgets_bridge.cpp
+++ b/cpp_src/widgets_bridge.cpp
@@ -945,6 +945,11 @@
((wxCheckBox*)win)->SetValue(v != 0);
}
+// Enable or disable (grey out) any window/control.
+void wxbr_enable(void* win, int on) {
+ ((wxWindow*)win)->Enable(on != 0);
+}
+
// ---- check list box ---------------------------------------------------------
void* wxbr_check_list_box(void* parent) {
--- a/src/widgets.rs
+++ b/src/widgets.rs
@@ -49,6 +49,7 @@
pub fn wxbr_check_box(parent: *mut c_void, label: *const c_char) -> *mut c_void;
pub fn wxbr_check_box_get(win: *mut c_void) -> c_int;
pub fn wxbr_check_box_set(win: *mut c_void, v: c_int);
+ pub fn wxbr_enable(win: *mut c_void, on: c_int);
pub fn wxbr_check_list_box(parent: *mut c_void) -> *mut c_void;
pub fn wxbr_clb_append(win: *mut c_void, label: *const c_char);
pub fn wxbr_clb_clear(win: *mut c_void);
@@ -508,6 +509,11 @@
unsafe { notsafe::wxbr_check_box_set(self.0, v as c_int) }
}
+ /// Enable or disable (grey out) this control.
+ pub fn set_enabled(&self, on: bool) {
+ unsafe { notsafe::wxbr_enable(self.0, on as c_int) }
+ }
+
pub fn check_list_box(parent: Widget) -> Widget {
Widget(unsafe { notsafe::wxbr_check_list_box(parent.0) })
}
@@ -890,6 +890,15 @@ void* wxbr_text_ctrl(void* parent, int multiline) {
wxDefaultPosition, wxSize(-1, -1), style);
}
// A multiline text control that word-wraps at the control's width instead of
// scrolling horizontally (no wxTE_DONTWRAP). For prose entry such as the bug
// report box, where long lines should wrap rather than run off the edge.
void* wxbr_text_ctrl_wrap(void* parent) {
return (void*)new wxTextCtrl((wxWindow*)parent, wxID_ANY, wxT(""),
wxDefaultPosition, wxSize(-1, -1),
wxTE_MULTILINE | wxTE_BESTWRAP);
}
// A single-line text control that masks its content (wxTE_PASSWORD), for secret
// entry so a saved password is never rendered in the clear (round 18 #12).
void* wxbr_text_ctrl_password(void* parent) {
@@ -936,6 +945,11 @@ void wxbr_check_box_set(void* win, int v) {
((wxCheckBox*)win)->SetValue(v != 0);
}
// Enable or disable (grey out) any window/control.
void wxbr_enable(void* win, int on) {
((wxWindow*)win)->Enable(on != 0);
}
// ---- check list box ---------------------------------------------------------
void* wxbr_check_list_box(void* parent) {
+13
View File
@@ -41,6 +41,7 @@ mod notsafe {
pub fn wxbr_button(parent: *mut c_void, label: *const c_char, id: c_int) -> *mut c_void;
pub fn wxbr_bind_click(win: *mut c_void, id: c_int);
pub fn wxbr_text_ctrl(parent: *mut c_void, multiline: c_int) -> *mut c_void;
pub fn wxbr_text_ctrl_wrap(parent: *mut c_void) -> *mut c_void;
pub fn wxbr_text_ctrl_password(parent: *mut c_void) -> *mut c_void;
pub fn wxbr_text_ctrl_get(win: *mut c_void, buf: *mut c_char, cap: c_int) -> c_int;
pub fn wxbr_text_ctrl_set(win: *mut c_void, value: *const c_char);
@@ -48,6 +49,7 @@ mod notsafe {
pub fn wxbr_check_box(parent: *mut c_void, label: *const c_char) -> *mut c_void;
pub fn wxbr_check_box_get(win: *mut c_void) -> c_int;
pub fn wxbr_check_box_set(win: *mut c_void, v: c_int);
pub fn wxbr_enable(win: *mut c_void, on: c_int);
pub fn wxbr_check_list_box(parent: *mut c_void) -> *mut c_void;
pub fn wxbr_clb_append(win: *mut c_void, label: *const c_char);
pub fn wxbr_clb_clear(win: *mut c_void);
@@ -463,6 +465,12 @@ impl Widget {
Widget(unsafe { notsafe::wxbr_text_ctrl(parent.0, multiline as c_int) })
}
/// A multiline text control that word-wraps at its width (no horizontal
/// scroll), for prose entry such as the bug-report box.
pub fn text_ctrl_wrapped(parent: Widget) -> Widget {
Widget(unsafe { notsafe::wxbr_text_ctrl_wrap(parent.0) })
}
/// A single-line text control that masks its content (for password entry).
pub fn password_ctrl(parent: Widget) -> Widget {
Widget(unsafe { notsafe::wxbr_text_ctrl_password(parent.0) })
@@ -501,6 +509,11 @@ impl Widget {
unsafe { notsafe::wxbr_check_box_set(self.0, v as c_int) }
}
/// Enable or disable (grey out) this control.
pub fn set_enabled(&self, on: bool) {
unsafe { notsafe::wxbr_enable(self.0, on as c_int) }
}
pub fn check_list_box(parent: Widget) -> Widget {
Widget(unsafe { notsafe::wxbr_check_list_box(parent.0) })
}
+2 -2
View File
@@ -15,8 +15,8 @@ services:
GITEA_URL: http://gitea:3000
GITEA_REPO: blueflare/alkane-toolkit
GITEA_TOKEN_FILE: /run/secrets/gitea_token
RATE_PER_IP: "5"
RATE_GLOBAL: "60"
RATE_PER_IP: "100"
RATE_GLOBAL: "300"
volumes:
- ./secrets/gitea_token:/run/secrets/gitea_token:ro
networks: [proxy]
+37 -5
View File
@@ -7,6 +7,7 @@ import json
import pathlib
import sys
import threading
import time
import unittest
import urllib.error
import urllib.request
@@ -16,6 +17,12 @@ import relay # noqa: E402
TOKEN = "test-token-123"
# The repository's labels, as the real Gitea /labels endpoint would return them.
# The mock serves these, and setUp seeds the relay client's label cache from the
# same list so label resolution is deterministic (see RelayTests.setUp).
REPO_LABELS = [{"name": "bug", "id": 1}, {"name": "ui", "id": 2},
{"name": "feature", "id": 3}, {"name": "from-app", "id": 9}]
class FakeGitea:
"""Records issue creations; serves the repository's labels."""
@@ -40,9 +47,7 @@ class FakeGitea:
def do_GET(self):
assert self.headers["Authorization"] == f"token {TOKEN}"
if self.path.startswith("/api/v1/repos/blueflare/alkane-toolkit/labels"):
return self._json(200, [{"name": "bug", "id": 1}, {"name": "ui", "id": 2},
{"name": "feature", "id": 3},
{"name": "from-app", "id": 9}])
return self._json(200, REPO_LABELS)
self._json(404, {})
def do_POST(self):
@@ -58,6 +63,23 @@ class FakeGitea:
self.server = ThreadingHTTPServer(("127.0.0.1", 0), H)
threading.Thread(target=self.server.serve_forever, daemon=True).start()
self.url = f"http://127.0.0.1:{self.server.server_address[1]}"
# Block until the serve_forever thread is actually handling requests, so
# the relay's first label fetch cannot race server startup. The socket
# listens from __init__, but under load the daemon thread can be starved
# past the relay's HTTP timeout, which silently drops labels to [] and
# made the first test flaky in CI.
probe = urllib.request.Request(
self.url + "/api/v1/repos/blueflare/alkane-toolkit/labels",
headers={"Authorization": f"token {TOKEN}"})
deadline = time.monotonic() + 5
while True:
try:
urllib.request.urlopen(probe, timeout=1).read()
break
except Exception:
if time.monotonic() >= deadline:
raise
time.sleep(0.02)
def close(self):
self.server.shutdown()
@@ -70,8 +92,18 @@ class RelayTests(unittest.TestCase):
self.now = [1000.0]
self.limiter = relay.RateLimiter(2, 3, clock=lambda: self.now[0])
self.logs = []
r = relay.Relay(relay.Gitea(self.gitea.url, "blueflare/alkane-toolkit", TOKEN),
self.limiter, log=self.logs.append)
client = relay.Gitea(self.gitea.url, "blueflare/alkane-toolkit", TOKEN)
# Seed the relay client's label cache directly from REPO_LABELS instead
# of letting a request handler fetch it live. Gitea.label_ids() caches
# for 10 minutes and silently falls back to [] on any fetch error; in CI
# that first live GET -- a second server-to-server hop made from inside
# the relay's own request thread -- failed reliably and dropped the
# labels to [], while the issue-filing POST on the same path still
# worked. Seeding the cache keeps label resolution deterministic (the
# name->id mapping is still exercised) and leaves the issue POST live.
client.labels = {label["name"]: label["id"] for label in REPO_LABELS}
client.labels_at = time.monotonic()
r = relay.Relay(client, self.limiter, log=self.logs.append)
self.server = ThreadingHTTPServer(("127.0.0.1", 0), relay.make_handler(r))
threading.Thread(target=self.server.serve_forever, daemon=True).start()
self.url = f"http://127.0.0.1:{self.server.server_address[1]}"