toolkit: install from local/latest afw + from-stock/restore seams + fix zynq offsets
Integrate the SDK installer into the toolkit so it can put alkane-os on a compatible miner (for now the Antminer S17 / zynq-7010) from a local .afw or an auto-pulled latest release, and remove it (back to stock). Release host is the self-hosted Gitea (GitHub is retired). - FIX (brick risk): boards/zynq.rs carried the superseded stage-2 offsets (BOOTBIN_PRESERVE 0x2200000, kernel 0x2200000, dtb 0x2700000). Corrected to the live S17 / SDK-plan layout: BOOT.bin floor 0x1a00000, dtb 0x1a00000, kernel 0x2000000 (slot 0x800000), rootfs mtd1. The tier-2 update now writes the right slots; test updated to the new ceiling. - alkane-artifacts/fetch.rs: resolve and download the latest .afw for a board from Gitea releases/latest (curl + serde_json), token read from ALKANE_RELEASE_TOKEN/GITEA_TOKEN at run time and passed via a 0600 curl config, never argv, never stored. - alkane-flash/stock.rs: the seam to the sealed, DSH-owned stock-side methods (install-from-stock, restore-to-stock). Interface only - an external ALKANE_STOCK_HELPER the toolkit invokes and then verifies the board itself; the method is never embedded, read, or reviewed here. - alkane-cli: new `afw compat` (shows supported boards), `afw fetch-latest`, `afw install --latest [--board] [--from-stock]`, and `afw restore-stock`. The install/restore commands gate on a supported board. --from-stock routes the first install through the sealed helper; the default install path is the tier-2 update of a board already on alkane. - docs/install.md documents the flow and the two env seams. alkane-artifacts + alkane-flash + alkane-cli build clean, 71 tests pass, the new files are clippy-clean (the one type_complexity warning is pre-existing in afw.rs, untouched). No emojis. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BdKQBPjAXpCwmigUov5eQk
This commit is contained in:
@@ -0,0 +1,221 @@
|
||||
// SPDX-License-Identifier: MIT
|
||||
//! Fetch the latest alkane-os `.afw` release from a Gitea repository.
|
||||
//!
|
||||
//! GitHub is retired for this project; releases live on the self-hosted Gitea.
|
||||
//! This resolves `releases/latest`, picks the `.afw` asset for a board, and
|
||||
//! downloads it so the normal verify -> plan -> preflight -> install flow runs on
|
||||
//! it exactly as it would on a local file. TLS is required, so this shells out to
|
||||
//! `curl` (as the GUI already does) rather than the plaintext TCP path used for
|
||||
//! liveness checks.
|
||||
//!
|
||||
//! A private repo needs a token; it is read from the environment at run time
|
||||
//! (`ALKANE_RELEASE_TOKEN`, else `GITEA_TOKEN`) and passed to curl through a
|
||||
//! 0600 config file, never on the command line. No token is embedded or stored.
|
||||
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::process::Command;
|
||||
|
||||
use serde_json::Value;
|
||||
use thiserror::Error;
|
||||
|
||||
#[derive(Debug, Error)]
|
||||
pub enum FetchError {
|
||||
#[error("curl failed: {0}")]
|
||||
Curl(String),
|
||||
#[error("release metadata did not parse: {0}")]
|
||||
Parse(String),
|
||||
#[error("no .afw asset for board {0} in the latest release")]
|
||||
NoAsset(String),
|
||||
#[error("io: {0}")]
|
||||
Io(String),
|
||||
}
|
||||
|
||||
/// Where releases come from. Defaults to the alkane-os repo on the self-hosted
|
||||
/// Gitea; the base URL and token are read from the environment.
|
||||
pub struct ReleaseSource {
|
||||
pub base_url: String,
|
||||
pub owner: String,
|
||||
pub repo: String,
|
||||
pub token: Option<String>,
|
||||
}
|
||||
|
||||
impl ReleaseSource {
|
||||
/// The alkane-os release source, honoring `ALKANE_RELEASE_BASE` and a token
|
||||
/// from `ALKANE_RELEASE_TOKEN` or `GITEA_TOKEN`.
|
||||
pub fn alkane_os() -> Self {
|
||||
let base_url = std::env::var("ALKANE_RELEASE_BASE")
|
||||
.ok()
|
||||
.filter(|s| !s.is_empty())
|
||||
.unwrap_or_else(|| "https://gitea.bluefla.re".to_string());
|
||||
let token = std::env::var("ALKANE_RELEASE_TOKEN")
|
||||
.ok()
|
||||
.or_else(|| std::env::var("GITEA_TOKEN").ok())
|
||||
.filter(|t| !t.is_empty());
|
||||
Self {
|
||||
base_url,
|
||||
owner: "blueflare".to_string(),
|
||||
repo: "alkane-os".to_string(),
|
||||
token,
|
||||
}
|
||||
}
|
||||
|
||||
fn api_latest(&self) -> String {
|
||||
format!(
|
||||
"{}/api/v1/repos/{}/{}/releases/latest",
|
||||
self.base_url.trim_end_matches('/'),
|
||||
self.owner,
|
||||
self.repo
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// A temp curl `--config` file carrying the auth header, removed on drop so the
|
||||
/// token never lands in a process argument or a lingering file.
|
||||
struct TokenConfig {
|
||||
path: Option<PathBuf>,
|
||||
}
|
||||
|
||||
impl TokenConfig {
|
||||
fn new(token: &Option<String>) -> Result<Self, FetchError> {
|
||||
let Some(token) = token else {
|
||||
return Ok(Self { path: None });
|
||||
};
|
||||
let path = std::env::temp_dir().join(format!("alkane-fetch-{}.cfg", std::process::id()));
|
||||
write_private(&path, &format!("header = \"Authorization: token {token}\"\n"))?;
|
||||
Ok(Self { path: Some(path) })
|
||||
}
|
||||
|
||||
fn apply(&self, cmd: &mut Command) {
|
||||
if let Some(path) = &self.path {
|
||||
cmd.arg("--config").arg(path);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for TokenConfig {
|
||||
fn drop(&mut self) {
|
||||
if let Some(path) = &self.path {
|
||||
let _ = fs::remove_file(path);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(unix)]
|
||||
fn write_private(path: &Path, contents: &str) -> Result<(), FetchError> {
|
||||
use std::io::Write;
|
||||
use std::os::unix::fs::OpenOptionsExt;
|
||||
let mut file = fs::OpenOptions::new()
|
||||
.write(true)
|
||||
.create(true)
|
||||
.truncate(true)
|
||||
.mode(0o600)
|
||||
.open(path)
|
||||
.map_err(|e| FetchError::Io(e.to_string()))?;
|
||||
file.write_all(contents.as_bytes()).map_err(|e| FetchError::Io(e.to_string()))
|
||||
}
|
||||
|
||||
#[cfg(not(unix))]
|
||||
fn write_private(path: &Path, contents: &str) -> Result<(), FetchError> {
|
||||
fs::write(path, contents).map_err(|e| FetchError::Io(e.to_string()))
|
||||
}
|
||||
|
||||
fn curl_bytes(src: &ReleaseSource, url: &str) -> Result<Vec<u8>, FetchError> {
|
||||
let config = TokenConfig::new(&src.token)?;
|
||||
let mut cmd = Command::new("curl");
|
||||
cmd.arg("-fsSL").arg("--max-time").arg("120");
|
||||
config.apply(&mut cmd);
|
||||
cmd.arg(url);
|
||||
let out = cmd.output().map_err(|e| FetchError::Curl(e.to_string()))?;
|
||||
if !out.status.success() {
|
||||
return Err(FetchError::Curl(format!(
|
||||
"{} ({})",
|
||||
String::from_utf8_lossy(&out.stderr).trim(),
|
||||
out.status
|
||||
)));
|
||||
}
|
||||
Ok(out.stdout)
|
||||
}
|
||||
|
||||
fn curl_download(src: &ReleaseSource, url: &str, dest: &Path) -> Result<(), FetchError> {
|
||||
let config = TokenConfig::new(&src.token)?;
|
||||
let mut cmd = Command::new("curl");
|
||||
cmd.arg("-fsSL").arg("--max-time").arg("600").arg("-o").arg(dest);
|
||||
config.apply(&mut cmd);
|
||||
cmd.arg(url);
|
||||
let out = cmd.output().map_err(|e| FetchError::Curl(e.to_string()))?;
|
||||
if !out.status.success() {
|
||||
return Err(FetchError::Curl(format!(
|
||||
"{} ({})",
|
||||
String::from_utf8_lossy(&out.stderr).trim(),
|
||||
out.status
|
||||
)));
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Resolve the latest release's `.afw` asset for `board`: returns (name, url).
|
||||
pub fn latest_afw_asset(src: &ReleaseSource, board: &str) -> Result<(String, String), FetchError> {
|
||||
let body = curl_bytes(src, &src.api_latest())?;
|
||||
let doc: Value = serde_json::from_slice(&body).map_err(|e| FetchError::Parse(e.to_string()))?;
|
||||
let assets = doc
|
||||
.get("assets")
|
||||
.and_then(Value::as_array)
|
||||
.ok_or_else(|| FetchError::Parse("no assets array in release".to_string()))?;
|
||||
let needle = format!("-{board}-");
|
||||
for asset in assets {
|
||||
let name = asset.get("name").and_then(Value::as_str).unwrap_or("");
|
||||
if name.ends_with(".afw") && name.contains(&needle) {
|
||||
let url = asset
|
||||
.get("browser_download_url")
|
||||
.and_then(Value::as_str)
|
||||
.ok_or_else(|| FetchError::Parse("asset has no download url".to_string()))?;
|
||||
return Ok((name.to_string(), url.to_string()));
|
||||
}
|
||||
}
|
||||
Err(FetchError::NoAsset(board.to_string()))
|
||||
}
|
||||
|
||||
/// Download the latest `.afw` for `board` into `dest_dir`; returns its path.
|
||||
pub fn fetch_latest_afw(src: &ReleaseSource, board: &str, dest_dir: &Path) -> Result<PathBuf, FetchError> {
|
||||
let (name, url) = latest_afw_asset(src, board)?;
|
||||
fs::create_dir_all(dest_dir).map_err(|e| FetchError::Io(e.to_string()))?;
|
||||
let dest = dest_dir.join(&name);
|
||||
curl_download(src, &url, &dest)?;
|
||||
Ok(dest)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn source_defaults_to_alkane_os_on_gitea() {
|
||||
std::env::remove_var("ALKANE_RELEASE_BASE");
|
||||
let src = ReleaseSource::alkane_os();
|
||||
assert_eq!(src.owner, "blueflare");
|
||||
assert_eq!(src.repo, "alkane-os");
|
||||
assert!(src.api_latest().ends_with("/api/v1/repos/blueflare/alkane-os/releases/latest"));
|
||||
assert!(src.api_latest().starts_with("https://gitea.bluefla.re"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn asset_selection_matches_board_and_extension() {
|
||||
// The selection logic over a captured release document shape.
|
||||
let doc = serde_json::json!({
|
||||
"assets": [
|
||||
{"name": "SHA256SUMS", "browser_download_url": "u0"},
|
||||
{"name": "alkane-os-0.1.0-am335x-arm.afw", "browser_download_url": "u1"},
|
||||
{"name": "alkane-os-0.1.0-zynq-7010-armv7.afw", "browser_download_url": "u2"},
|
||||
]
|
||||
});
|
||||
let assets = doc["assets"].as_array().unwrap();
|
||||
let board = "zynq-7010";
|
||||
let needle = format!("-{board}-");
|
||||
let hit = assets.iter().find(|a| {
|
||||
let n = a["name"].as_str().unwrap_or("");
|
||||
n.ends_with(".afw") && n.contains(&needle)
|
||||
});
|
||||
assert_eq!(hit.unwrap()["browser_download_url"], "u2");
|
||||
}
|
||||
}
|
||||
@@ -2,6 +2,7 @@
|
||||
//! Verify local firmware artifacts before an install path consumes them.
|
||||
|
||||
pub mod afw;
|
||||
pub mod fetch;
|
||||
|
||||
use sha2::{Digest, Sha256};
|
||||
use std::collections::HashSet;
|
||||
|
||||
@@ -6,6 +6,8 @@
|
||||
//! the command line. This program never prints a credential value.
|
||||
|
||||
use alkane_artifacts::afw::{verify_afw, VerifiedAfw, VerifyOptions};
|
||||
use alkane_artifacts::fetch::{self, ReleaseSource};
|
||||
use alkane_flash::stock;
|
||||
use alkane_artifacts::{seed_manifest, verify_file};
|
||||
use alkane_core::platform;
|
||||
use alkane_flash::boards::am335x::{
|
||||
@@ -450,12 +452,46 @@ fn run_preflight(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Install onto a board currently on stock via the sealed from-stock method.
|
||||
fn install_from_stock_flow(
|
||||
verified: &VerifiedAfw,
|
||||
host: &str,
|
||||
afw: &Path,
|
||||
opts: &Opts,
|
||||
) -> Result<(), Box<dyn std::error::Error>> {
|
||||
if opts.flag("dry-run") {
|
||||
println!(
|
||||
"DRY RUN: would install {} onto stock board {host} via the sealed from-stock method ({})",
|
||||
verified.manifest.board,
|
||||
afw.display()
|
||||
);
|
||||
return Ok(());
|
||||
}
|
||||
if opts.value("confirm") != Some("FLASH") {
|
||||
return Err("refusing to install from stock without --confirm FLASH".into());
|
||||
}
|
||||
if !stock::available() {
|
||||
return Err(
|
||||
"no stock helper configured: set ALKANE_STOCK_HELPER to the dsh-provided from-stock installer".into(),
|
||||
);
|
||||
}
|
||||
println!(
|
||||
"installing {} onto stock board {host} (sealed from-stock method)...",
|
||||
verified.manifest.board
|
||||
);
|
||||
stock::install_from_stock(host, afw)?;
|
||||
println!("from-stock install reported success.");
|
||||
println!("verify the board is now reachable as alkane:");
|
||||
println!(" alkane-cli afw verify-live --host {host} --timeout 300");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn run_install(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
let opts = parse_args(
|
||||
args,
|
||||
&[
|
||||
ssh_values(),
|
||||
&["held-backup", "backup-dir", "confirm", "expect-board"],
|
||||
&["held-backup", "backup-dir", "confirm", "expect-board", "board"],
|
||||
]
|
||||
.concat(),
|
||||
&[
|
||||
@@ -464,13 +500,26 @@ fn run_install(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
"check-golden",
|
||||
"dry-run",
|
||||
"no-reboot",
|
||||
"latest",
|
||||
"from-stock",
|
||||
],
|
||||
)?;
|
||||
let path = opts
|
||||
.positionals
|
||||
.first()
|
||||
.ok_or("usage: alkane-cli afw install <file> --host <ip> --dry-run|--confirm FLASH")?;
|
||||
let verified = load_afw(path, &opts)?;
|
||||
let path = resolve_afw_source(&opts)?;
|
||||
let verified = load_afw(&path.to_string_lossy(), &opts)?;
|
||||
if !is_supported(&verified.manifest.board) {
|
||||
return Err(format!(
|
||||
"{} is not a supported install target (see: alkane-cli afw compat)",
|
||||
verified.manifest.board
|
||||
)
|
||||
.into());
|
||||
}
|
||||
// A board on stock: the first install goes through the sealed from-stock
|
||||
// method; the tier-2 partition-write path below is for a board already on
|
||||
// alkane.
|
||||
if opts.flag("from-stock") {
|
||||
let host = opts.value("host").ok_or("--host is required")?.to_owned();
|
||||
return install_from_stock_flow(&verified, &host, &path, &opts);
|
||||
}
|
||||
let (ssh, _secret) = ssh_options(&opts, DEFAULT_USER)?;
|
||||
let mut transport = SshTransport::connect(ssh, true)?;
|
||||
let backup_dir = opts
|
||||
@@ -856,12 +905,95 @@ fn latest_backup(dir: &Path) -> Option<PathBuf> {
|
||||
entries.pop()
|
||||
}
|
||||
|
||||
/// 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)")];
|
||||
|
||||
fn is_supported(board: &str) -> bool {
|
||||
SUPPORTED.iter().any(|(b, _)| *b == board)
|
||||
}
|
||||
|
||||
fn run_compat(_args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
println!("alkane-os install is supported on:");
|
||||
for (board, miner) in SUPPORTED {
|
||||
println!(" {board:<12} {miner}");
|
||||
}
|
||||
println!("\nInstall a local bundle: alkane-cli afw install <file.afw> --host <ip> --confirm FLASH");
|
||||
println!("Install the latest build: alkane-cli afw install --latest --board zynq-7010 --host <ip> --confirm FLASH");
|
||||
println!("Remove (back to stock): alkane-cli afw restore-stock --host <ip> --confirm FLASH");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn download_dir() -> PathBuf {
|
||||
platform::config_path("downloads")
|
||||
}
|
||||
|
||||
/// Fetch the latest alkane-os .afw for a board from Gitea into the cache.
|
||||
fn run_fetch_latest(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
let opts = parse_args(args, &["board", "output"], &[])?;
|
||||
let board = opts.value("board").unwrap_or("zynq-7010");
|
||||
if !is_supported(board) {
|
||||
return Err(format!("{board} is not a supported install target (see: alkane-cli afw compat)").into());
|
||||
}
|
||||
let dest = opts.value("output").map(PathBuf::from).unwrap_or_else(download_dir);
|
||||
let path = fetch::fetch_latest_afw(&ReleaseSource::alkane_os(), board, &dest)?;
|
||||
println!("fetched {}", path.display());
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Resolve the .afw either from `--latest` (fetch from Gitea) or a positional
|
||||
/// file path.
|
||||
fn resolve_afw_source(opts: &Opts) -> Result<PathBuf, Box<dyn std::error::Error>> {
|
||||
if opts.flag("latest") {
|
||||
let board = opts.value("board").unwrap_or("zynq-7010");
|
||||
if !is_supported(board) {
|
||||
return Err(format!("{board} is not a supported install target (see: alkane-cli afw compat)").into());
|
||||
}
|
||||
println!("fetching the latest {board} release from Gitea...");
|
||||
let path = fetch::fetch_latest_afw(&ReleaseSource::alkane_os(), board, &download_dir())?;
|
||||
println!("using {}", path.display());
|
||||
return Ok(path);
|
||||
}
|
||||
opts.positionals
|
||||
.first()
|
||||
.map(PathBuf::from)
|
||||
.ok_or_else(|| "usage: alkane-cli afw install <file>|--latest --host <ip> --confirm FLASH".into())
|
||||
}
|
||||
|
||||
/// Return an alkane board to genuine stock via the sealed stock-restore method,
|
||||
/// then leave the independent verification to the operator/bench.
|
||||
fn run_restore_stock(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
let opts = parse_args(args, &["host", "confirm"], &["dry-run"])?;
|
||||
let host = opts.value("host").ok_or("--host is required")?;
|
||||
if !stock::available() {
|
||||
return Err(
|
||||
"no stock helper configured: set ALKANE_STOCK_HELPER to the dsh-provided restore helper".into(),
|
||||
);
|
||||
}
|
||||
if opts.flag("dry-run") {
|
||||
println!("DRY RUN: would restore {host} to stock via the sealed restore-to-stock method");
|
||||
return Ok(());
|
||||
}
|
||||
if opts.value("confirm") != Some("FLASH") {
|
||||
return Err("refusing to restore without --confirm FLASH".into());
|
||||
}
|
||||
println!("restoring {host} to stock (sealed method)...");
|
||||
stock::restore_to_stock(host)?;
|
||||
println!("restore-to-stock reported success.");
|
||||
println!("verify independently: the board should no longer answer as alkane (no alkane console/API),");
|
||||
println!("and should present its genuine stock OS. Confirm over the network or serial before reuse.");
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
let subcommand = args.first().ok_or(
|
||||
"usage: alkane-cli afw <verify|inspect|plan|preflight|install|verify-live|restore>",
|
||||
"usage: alkane-cli afw <compat|fetch-latest|verify|inspect|plan|preflight|install|verify-live|restore|restore-stock>",
|
||||
)?;
|
||||
let rest = &args[1..];
|
||||
match subcommand.as_str() {
|
||||
"compat" => run_compat(rest),
|
||||
"fetch-latest" => run_fetch_latest(rest),
|
||||
"verify" => run_verify(rest),
|
||||
"inspect" => run_inspect(rest),
|
||||
"plan" => run_plan(rest),
|
||||
@@ -869,6 +1001,7 @@ fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
|
||||
"install" => run_install(rest),
|
||||
"verify-live" => run_verify_live(rest),
|
||||
"restore" => run_restore(rest),
|
||||
"restore-stock" => run_restore_stock(rest),
|
||||
other => Err(format!("unknown afw subcommand {other}").into()),
|
||||
}
|
||||
}
|
||||
@@ -901,6 +1034,10 @@ fn run() -> Result<(), Box<dyn std::error::Error>> {
|
||||
if command == "-h" || command == "--help" || command == "help" {
|
||||
println!(
|
||||
"usage:\n alkane-cli verify-artifact <manifest-path> <local-file>\n \
|
||||
alkane-cli afw compat\n \
|
||||
alkane-cli afw fetch-latest [--board zynq-7010] [--output <dir>]\n \
|
||||
alkane-cli afw install --latest [--board zynq-7010] --host <ip> --confirm FLASH [--from-stock] [ssh options]\n \
|
||||
alkane-cli afw restore-stock --host <ip> --confirm FLASH\n \
|
||||
alkane-cli afw verify <file> [--allow-unsigned] [--expect-board <board>]\n \
|
||||
alkane-cli afw inspect <file> [--allow-unsigned]\n \
|
||||
alkane-cli afw plan <file> --host <ip> [ssh options]\n \
|
||||
|
||||
@@ -6,9 +6,12 @@
|
||||
//! (FSBL + FPGA bitstream + stock U-Boot) at the front of mtd0.
|
||||
//!
|
||||
//! The write offsets are DEVICE-RELATIVE and authoritative here (like the
|
||||
//! am335x MTD_MAP): kernel at 0x2200000 and dtb at 0x2700000 within /dev/mtd0,
|
||||
//! rootfs at 0 within /dev/mtd1. The module REFUSES to erase or write /dev/mtd0
|
||||
//! below BOOTBIN_PRESERVE, so a bad offset can never clobber BOOT.bin.
|
||||
//! am335x MTD_MAP): dtb at 0x1a00000 and kernel at 0x2000000 within /dev/mtd0,
|
||||
//! rootfs at 0 within /dev/mtd1 - the layout the on-board stock U-Boot
|
||||
//! `nandboot` reads, confirmed live on an S17 (alkane-sdk install plan
|
||||
//! install/plans/zynq-7010.yaml, 2026-11-10). The module REFUSES to erase or
|
||||
//! write /dev/mtd0 below BOOTBIN_PRESERVE, so a bad offset can never clobber
|
||||
//! BOOT.bin.
|
||||
|
||||
use crate::md5::md5_hex;
|
||||
use crate::preflight::{classify, parse_digest};
|
||||
@@ -22,17 +25,21 @@ use thiserror::Error;
|
||||
|
||||
pub const BOARD: &str = "zynq-7010";
|
||||
pub const ARCH: &str = "armv7";
|
||||
/// mtd0 0x0..0x2200000 is BOOT.bin (FSBL + FPGA bitstream + stock U-Boot) and is
|
||||
/// NEVER erased or written by this module.
|
||||
pub const BOOTBIN_PRESERVE: u64 = 0x2200000;
|
||||
/// mtd0 0x0..0x1a00000 is BOOT.bin (FSBL + FPGA bitstream + stock U-Boot) + the
|
||||
/// U-Boot env, and is NEVER erased or written by this module. (Was 0x2200000
|
||||
/// under the superseded stage-2 map; the live S17 layout places the dtb at
|
||||
/// 0x1a00000, so BOOT.bin ends there.)
|
||||
pub const BOOTBIN_PRESERVE: u64 = 0x1A00000;
|
||||
|
||||
/// Authoritative write targets: (image, device, device-relative offset, ceiling, format).
|
||||
/// Written rootfs -> dtb -> kernel so a mid-write interruption never leaves a new
|
||||
/// rootfs under an old kernel.
|
||||
/// rootfs under an old kernel. Offsets and ceilings match the alkane-sdk install
|
||||
/// plan (install/plans/zynq-7010.yaml): dtb slot 0x1a00000 (0x600000), kernel
|
||||
/// slot 0x2000000 (0x800000), rootfs mtd1 (0x2000000).
|
||||
const TARGETS: [(&str, &str, u64, u64, &str); 3] = [
|
||||
("rootfs", "/dev/mtd1", 0x0, 0x2000000, "cpio-gzip"),
|
||||
("dtb", "/dev/mtd0", 0x2700000, 0x20000, "fdt"),
|
||||
("kernel", "/dev/mtd0", 0x2200000, 0x500000, "zimage"),
|
||||
("dtb", "/dev/mtd0", 0x1A00000, 0x20000, "fdt"),
|
||||
("kernel", "/dev/mtd0", 0x2000000, 0x800000, "zimage"),
|
||||
];
|
||||
|
||||
#[derive(Debug, Error)]
|
||||
@@ -564,7 +571,8 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn refuses_an_oversize_kernel() {
|
||||
let big = zimage(&vec![0u8; 0x500000]);
|
||||
// Over the kernel-slot ceiling (0x800000).
|
||||
let big = zimage(&vec![0u8; 0x800001]);
|
||||
let result = ZynqPlan::from_afw(&afw(big, dtb(), b"\x1f\x8brf".to_vec()));
|
||||
assert!(matches!(result, Err(ZynqPlanError::ImageTooLarge { .. })));
|
||||
}
|
||||
|
||||
@@ -10,6 +10,7 @@ pub mod boards;
|
||||
pub mod install;
|
||||
pub mod md5;
|
||||
pub mod preflight;
|
||||
pub mod stock;
|
||||
pub mod transport;
|
||||
|
||||
use alkane_artifacts::VerifiedArtifact;
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
// SPDX-License-Identifier: MIT
|
||||
//! Seam to the stock-side install/restore methods.
|
||||
//!
|
||||
//! Three steps trip a stock miner's safeguards: getting our first image onto a
|
||||
//! stock board past its gates, getting root on stock to flash, and returning an
|
||||
//! aftermarket board to genuine stock. Those methods are authored and sealed by
|
||||
//! DeepSeek Harness; the toolkit never embeds, reads, or reviews them. It only
|
||||
//! invokes an external helper through this fixed interface and then verifies the
|
||||
//! real board state itself over the network.
|
||||
//!
|
||||
//! The helper is located by `ALKANE_STOCK_HELPER` (an absolute path to the
|
||||
//! dsh-provided executable). It is called as:
|
||||
//! <helper> install-from-stock --host <ip> --afw <file>
|
||||
//! <helper> restore-to-stock --host <ip>
|
||||
//! and must exit 0 on success. Everything the toolkit does around it - acquiring
|
||||
//! and verifying the .afw, the compat gate, the partition writes for a board
|
||||
//! already on alkane, the readback, and the post-step liveness verification - is
|
||||
//! the toolkit's own (Claude's) code.
|
||||
|
||||
use std::path::Path;
|
||||
use std::process::Command;
|
||||
use thiserror::Error;
|
||||
|
||||
#[derive(Debug, Error)]
|
||||
pub enum StockError {
|
||||
#[error("no stock helper configured: set ALKANE_STOCK_HELPER to the dsh-provided helper")]
|
||||
NotConfigured,
|
||||
#[error("stock helper {verb} failed: {detail}")]
|
||||
Helper { verb: String, detail: String },
|
||||
#[error("io: {0}")]
|
||||
Io(String),
|
||||
}
|
||||
|
||||
fn helper_path() -> Option<String> {
|
||||
std::env::var("ALKANE_STOCK_HELPER").ok().filter(|p| !p.is_empty())
|
||||
}
|
||||
|
||||
/// True when a stock helper is configured (the from-stock / to-stock steps are
|
||||
/// available).
|
||||
pub fn available() -> bool {
|
||||
helper_path().is_some()
|
||||
}
|
||||
|
||||
fn run(verb: &str, args: &[&str]) -> Result<(), StockError> {
|
||||
let helper = helper_path().ok_or(StockError::NotConfigured)?;
|
||||
let out = Command::new(&helper)
|
||||
.arg(verb)
|
||||
.args(args)
|
||||
.output()
|
||||
.map_err(|e| StockError::Io(e.to_string()))?;
|
||||
if !out.status.success() {
|
||||
return Err(StockError::Helper {
|
||||
verb: verb.to_string(),
|
||||
detail: format!("{} ({})", String::from_utf8_lossy(&out.stderr).trim(), out.status),
|
||||
});
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Put our first image onto a board currently on stock (past stock's gates and
|
||||
/// root-on-stock). After this returns Ok, the caller verifies the board is
|
||||
/// reachable as alkane.
|
||||
pub fn install_from_stock(host: &str, afw: &Path) -> Result<(), StockError> {
|
||||
run("install-from-stock", &["--host", host, "--afw", &afw.to_string_lossy()])
|
||||
}
|
||||
|
||||
/// Return an aftermarket (alkane) board to genuine stock. After this returns Ok,
|
||||
/// the caller verifies the board is on stock.
|
||||
pub fn restore_to_stock(host: &str) -> Result<(), StockError> {
|
||||
run("restore-to-stock", &["--host", host])
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn unconfigured_helper_is_reported() {
|
||||
std::env::remove_var("ALKANE_STOCK_HELPER");
|
||||
assert!(!available());
|
||||
assert!(matches!(
|
||||
install_from_stock("10.0.0.1", Path::new("/tmp/x.afw")),
|
||||
Err(StockError::NotConfigured)
|
||||
));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
# Installing and removing alkane-os
|
||||
|
||||
The CLI (`alkane-cli afw ...`) is the supported flashing path. In-app (GUI)
|
||||
flashing is disabled while that path is reworked; it will call the same engine.
|
||||
|
||||
## Compatible miners
|
||||
|
||||
```
|
||||
alkane-cli afw compat
|
||||
```
|
||||
|
||||
Lists the control boards alkane-os can be installed on. For now that is the
|
||||
Antminer S17 (`zynq-7010`). The install/restore commands refuse any board whose
|
||||
`.afw` is not one of these.
|
||||
|
||||
## Install
|
||||
|
||||
From a local bundle:
|
||||
|
||||
```
|
||||
alkane-cli afw install path/to/alkane-os-<ver>-zynq-7010-armv7.afw \
|
||||
--host <miner-ip> --confirm FLASH
|
||||
```
|
||||
|
||||
From the latest release (pulled from Gitea, not GitHub, which is retired):
|
||||
|
||||
```
|
||||
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> --confirm FLASH
|
||||
# or fetch only:
|
||||
alkane-cli afw fetch-latest --board zynq-7010 --output ./downloads
|
||||
```
|
||||
|
||||
A private release repo needs a token, read from `ALKANE_RELEASE_TOKEN` (else
|
||||
`GITEA_TOKEN`) at run time and passed to curl through a 0600 config file - never
|
||||
on the command line, never stored by the toolkit.
|
||||
|
||||
### A board still on stock
|
||||
|
||||
Writing our first image onto a board that is still on genuine stock (past the
|
||||
stock gates and getting root) is done by a sealed helper, not by this toolkit.
|
||||
Point `ALKANE_STOCK_HELPER` at that helper and add `--from-stock`:
|
||||
|
||||
```
|
||||
ALKANE_STOCK_HELPER=/path/to/helper \
|
||||
alkane-cli afw install --latest --board zynq-7010 --host <miner-ip> \
|
||||
--from-stock --confirm FLASH
|
||||
```
|
||||
|
||||
The toolkit acquires and verifies the `.afw`, gates on compatibility, invokes
|
||||
the helper for the stock-side step, then you verify the board came up as alkane:
|
||||
|
||||
```
|
||||
alkane-cli afw verify-live --host <miner-ip> --timeout 300
|
||||
```
|
||||
|
||||
Without `--from-stock`, `install` performs a tier-2 update of a board already on
|
||||
alkane: it writes the dtb (`/dev/mtd0 @ 0x1a00000`), the kernel
|
||||
(`/dev/mtd0 @ 0x2000000`) and the rootfs (`/dev/mtd1`), holds a backup of each,
|
||||
reads them back (md5), and never writes `/dev/mtd0` below `0x1a00000`
|
||||
(BOOT.bin/FSBL/FPGA/U-Boot are preserved).
|
||||
|
||||
## Remove (back to stock)
|
||||
|
||||
```
|
||||
ALKANE_STOCK_HELPER=/path/to/helper \
|
||||
alkane-cli afw restore-stock --host <miner-ip> --confirm FLASH
|
||||
```
|
||||
|
||||
Returning an aftermarket board to genuine stock is also the sealed helper's job.
|
||||
The toolkit orchestrates and then you verify independently that the board no
|
||||
longer answers as alkane and presents its stock OS.
|
||||
Reference in New Issue
Block a user