feat(flash): SD installation-media engine + stock-recovery card builder

New `sd_media` module: build bootable removable-media card *images* for
boards that boot from a card, root-free up to the final device write.

- `CardImage`: assemble a single-partition (MBR, FAT32 type 0x0c @ LBA 2048)
  card image as an ordinary file using sfdisk + mkfs.vfat + mtools
  (mcopy/mmd) -- no loopback mount, no root -- so the `.img` is fully
  inspectable and unit-testable without hardware. This is the exact card
  shape proven on the bench S17 (2026-11-17): stock U-Boot card-detects it
  and side-loads the flasher-OS trio with no boot-mode strap and no uEnv.txt.
- `build_stock_recovery_card`: codify the by-hand bench procedure -- replicate
  a genuine vendor SD-recovery package's layout (flasher-OS trio at the card
  root + `bin/` NAND payload) onto a card image. `locate_vendor_card` finds
  the layout inside an unpacked (possibly nested) vendor package.
- `write_image_to_device`: guarded, separate dd of a finished image to a block
  device (the only part that touches real hardware; caller confirms target).

Tests build a card from a synthetic vendor package and read it back with
mdir/mtype (skip cleanly if the host lacks the image toolchain).

First slice of the SD Installation-Media feature; alkane simple-boot and
installer card builders, the GUI window, and CLI parity follow.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B1W6qKwKxq3oUPDKWicM6i
This commit is contained in:
2026-11-17 10:36:43 -06:00
co-authored by Claude Opus 4.8
parent 0873d2c79d
commit 0d9c0fb7c1
2 changed files with 496 additions and 0 deletions
+1
View File
@@ -16,6 +16,7 @@ pub mod boards;
pub mod install;
pub mod md5;
pub mod preflight;
pub mod sd_media;
pub mod stock;
pub mod stock_firmware;
pub mod uimage;
+495
View File
@@ -0,0 +1,495 @@
// SPDX-License-Identifier: MIT
//! Build bootable SD / removable-media card *images* for control boards that
//! boot from a card, and (separately, guarded) write a finished image to a
//! physical device.
//!
//! Everything here is **network-free and root-free up to the final device
//! write**: a card image is assembled as an ordinary file using `sfdisk`
//! (partition table), `mkfs.vfat` (FAT32 filesystem) and `mtools`
//! (`mcopy`/`mmd`, which populate a FAT image with no loopback mount and no
//! root). The resulting `.img` is byte-for-byte what lands on the card, so it
//! is fully inspectable and unit-testable without hardware. Only
//! [`write_image_to_device`] touches a real block device, and it is deliberately
//! kept apart so a caller confirms the target first.
//!
//! The card layout this produces is the one proven on a bench Antminer S17
//! (2026-11-17): a single MBR primary FAT32 partition (type 0x0c) starting at
//! LBA 2048. On the Zynq boards the stock U-Boot card-detects such a card and
//! side-loads the flasher-OS trio (`uImage` / `devicetree.dtb` /
//! `uramdisk.image.gz`) from its root -- no boot-mode strap and no `uEnv.txt`
//! required (see `alkane-sdk-construction: zynq-s17-recovery.md`).
use std::fmt;
use std::fs;
use std::io::Write as _;
use std::path::{Path, PathBuf};
use std::process::Command;
/// Partition starts at LBA 2048 (1 MiB) -- the conventional alignment, and what
/// the proven S17 card used.
const PART_LBA: u64 = 2048;
const SECTOR: u64 = 512;
const PART_OFFSET_BYTES: u64 = PART_LBA * SECTOR;
#[derive(Debug)]
pub enum MediaError {
/// A required external tool (`sfdisk` / `mkfs.vfat` / an mtools binary) was
/// not found on the system.
MissingTool(String),
/// A source file or directory the card needs is absent.
MissingSource(String),
/// A vendor package did not contain a recognisable card layout.
BadPackage(String),
/// An external command exited non-zero; carries a short diagnostic.
Command(String),
Io(std::io::Error),
}
impl fmt::Display for MediaError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
MediaError::MissingTool(t) => write!(f, "required tool not found: {t}"),
MediaError::MissingSource(s) => write!(f, "missing source: {s}"),
MediaError::BadPackage(s) => write!(f, "unrecognised package layout: {s}"),
MediaError::Command(s) => write!(f, "{s}"),
MediaError::Io(e) => write!(f, "io: {e}"),
}
}
}
impl std::error::Error for MediaError {}
impl From<std::io::Error> for MediaError {
fn from(e: std::io::Error) -> Self {
MediaError::Io(e)
}
}
type Result<T> = std::result::Result<T, MediaError>;
/// Find an executable by name, searching `PATH` plus the usual `sbin`
/// directories (`mkfs.vfat` / `sfdisk` live in `/sbin` or `/usr/sbin`, which are
/// often absent from a GUI process's `PATH`).
fn find_tool(name: &str) -> Result<PathBuf> {
if let Ok(path) = std::env::var("PATH") {
for dir in std::env::split_paths(&path) {
let p = dir.join(name);
if p.is_file() {
return Ok(p);
}
}
}
for dir in ["/sbin", "/usr/sbin", "/usr/local/sbin", "/bin", "/usr/bin"] {
let p = Path::new(dir).join(name);
if p.is_file() {
return Ok(p);
}
}
Err(MediaError::MissingTool(name.to_string()))
}
fn run(mut cmd: Command, what: &str) -> Result<()> {
let out = cmd
.output()
.map_err(|e| MediaError::Command(format!("{what}: failed to launch: {e}")))?;
if !out.status.success() {
let mut msg = format!("{what}: exit {:?}", out.status.code());
let err = String::from_utf8_lossy(&out.stderr);
let err = err.trim();
if !err.is_empty() {
msg.push_str(": ");
msg.push_str(err.lines().next_back().unwrap_or(err));
}
return Err(MediaError::Command(msg));
}
Ok(())
}
/// A FAT32 card image under construction: a single MBR primary partition that
/// mtools populates through a private config file (no mount, no root).
pub struct CardImage {
img: PathBuf,
mtoolsrc: PathBuf,
mcopy: PathBuf,
mmd: PathBuf,
_tmp: Option<tempdir::TempHold>,
}
impl CardImage {
/// Create a new `size_mb`-megabyte image at `img_path`, partition it with a
/// single FAT32 (type 0x0c) partition at LBA 2048, format that partition
/// FAT32 with the given volume `label` (upper-cased, <= 11 chars), and
/// prepare mtools to write into it.
pub fn create(img_path: &Path, size_mb: u64, label: &str) -> Result<CardImage> {
let sfdisk = find_tool("sfdisk")?;
let mkfs = find_tool("mkfs.vfat")?;
let mcopy = find_tool("mcopy")?;
let mmd = find_tool("mmd")?;
// 1. Zero-filled image of the requested size.
let f = fs::File::create(img_path)?;
f.set_len(size_mb.saturating_mul(1024 * 1024))?;
drop(f);
// 2. MBR: one primary FAT32 (LBA) partition from sector 2048 to the end.
{
let mut cmd = Command::new(&sfdisk);
cmd.arg(img_path).stdin(std::process::Stdio::piped());
cmd.stdout(std::process::Stdio::null());
cmd.stderr(std::process::Stdio::piped());
let mut child = cmd
.spawn()
.map_err(|e| MediaError::Command(format!("sfdisk: {e}")))?;
{
let stdin = child
.stdin
.as_mut()
.ok_or_else(|| MediaError::Command("sfdisk: no stdin".to_string()))?;
writeln!(stdin, "label: dos")?;
writeln!(stdin, "start={PART_LBA}, type=0c")?;
}
let out = child
.wait_with_output()
.map_err(|e| MediaError::Command(format!("sfdisk: {e}")))?;
if !out.status.success() {
return Err(MediaError::Command(format!(
"sfdisk: {}",
String::from_utf8_lossy(&out.stderr).trim()
)));
}
}
// 3. Format the partition region (no root) via mkfs.vfat --offset.
let label = sanitize_label(label);
let mut cmd = Command::new(&mkfs);
cmd.args(["-F", "32", "-n", &label, "--offset"])
.arg(PART_LBA.to_string())
.arg(img_path)
.stdout(std::process::Stdio::null());
run(cmd, "mkfs.vfat")?;
// 4. Private mtools config mapping drive C: to the partition region.
let tmp = tempdir::TempHold::new()?;
let mtoolsrc = tmp.path().join("mtools.conf");
{
let mut mf = fs::File::create(&mtoolsrc)?;
writeln!(
mf,
"drive C: file=\"{}\" offset={}",
img_path.display(),
PART_OFFSET_BYTES
)?;
}
Ok(CardImage {
img: img_path.to_path_buf(),
mtoolsrc,
mcopy,
mmd,
_tmp: Some(tmp),
})
}
fn mtools_cmd(&self, tool: &Path) -> Command {
let mut cmd = Command::new(tool);
cmd.env("MTOOLSRC", &self.mtoolsrc);
cmd.env("MTOOLS_SKIP_CHECK", "1");
cmd
}
/// Create a directory on the card, e.g. `bin`. Tolerates "already exists".
pub fn mkdir(&self, dest: &str) -> Result<()> {
let path = format!("C:/{}", dest.trim_start_matches('/'));
let out = self
.mtools_cmd(&self.mmd)
.arg(&path)
.output()
.map_err(|e| MediaError::Command(format!("mmd: {e}")))?;
if out.status.success() {
return Ok(());
}
let err = String::from_utf8_lossy(&out.stderr);
if err.to_lowercase().contains("already exists") {
Ok(())
} else {
Err(MediaError::Command(format!("mmd {dest}: {}", err.trim())))
}
}
/// Copy a local file onto the card at `dest` (a card-relative path like
/// `uImage` or `bin/BOOT.bin`). Overwrites.
pub fn copy_file(&self, local: &Path, dest: &str) -> Result<()> {
if !local.is_file() {
return Err(MediaError::MissingSource(local.display().to_string()));
}
let mut cmd = self.mtools_cmd(&self.mcopy);
cmd.arg("-o") // overwrite without prompting
.arg(local)
.arg(format!("C:/{}", dest.trim_start_matches('/')));
run(cmd, &format!("mcopy {}", local.display()))
}
/// Copy an entire local directory's contents onto the card under `dest`
/// (created if needed). Recurses.
pub fn copy_dir(&self, local: &Path, dest: &str) -> Result<()> {
if !local.is_dir() {
return Err(MediaError::MissingSource(local.display().to_string()));
}
self.mkdir(dest)?;
for entry in fs::read_dir(local)? {
let entry = entry?;
let name = entry.file_name();
let name = name.to_string_lossy();
let child_dest = format!("{}/{}", dest.trim_end_matches('/'), name);
if entry.file_type()?.is_dir() {
self.copy_dir(&entry.path(), &child_dest)?;
} else {
self.copy_file(&entry.path(), &child_dest)?;
}
}
Ok(())
}
/// The finished image path.
pub fn path(&self) -> &Path {
&self.img
}
}
/// Upper-case and clamp a FAT volume label to 11 chars; empty becomes `ALKANE`.
fn sanitize_label(label: &str) -> String {
let up: String = label
.chars()
.filter(|c| c.is_ascii_alphanumeric() || *c == '_' || *c == '-')
.take(11)
.collect::<String>()
.to_ascii_uppercase();
if up.is_empty() {
"ALKANE".to_string()
} else {
up
}
}
/// A located vendor SD-recovery card layout: the flasher-OS trio at the package
/// root plus the `bin/` NAND payload directory.
pub struct VendorCardLayout {
/// Directory holding `uImage`, `devicetree.dtb`, `uramdisk.image.gz` and
/// `bin/`.
pub root: PathBuf,
}
/// Locate the card layout inside an unpacked vendor SD-recovery package. Vendor
/// zips often nest the real card directory one or two levels deep (e.g.
/// `sd_set_default_password_enhanced_0527_S17/.../`). Accept the shallowest
/// directory that contains all three root-level flasher files and a `bin/`.
pub fn locate_vendor_card(unpacked_root: &Path) -> Result<VendorCardLayout> {
fn has_layout(dir: &Path) -> bool {
dir.join("uImage").is_file()
&& dir.join("devicetree.dtb").is_file()
&& dir.join("uramdisk.image.gz").is_file()
&& dir.join("bin").is_dir()
}
// Breadth-first to prefer the shallowest match.
let mut queue = vec![unpacked_root.to_path_buf()];
let mut depth_guard = 0;
while let Some(dir) = queue.first().cloned() {
queue.remove(0);
if has_layout(&dir) {
return Ok(VendorCardLayout { root: dir });
}
depth_guard += 1;
if depth_guard > 4096 {
break;
}
if let Ok(rd) = fs::read_dir(&dir) {
for e in rd.flatten() {
if e.file_type().map(|t| t.is_dir()).unwrap_or(false) {
queue.push(e.path());
}
}
}
}
Err(MediaError::BadPackage(format!(
"no flasher-OS trio (uImage/devicetree.dtb/uramdisk.image.gz) + bin/ found under {}",
unpacked_root.display()
)))
}
/// Build a genuine-vendor **stock-recovery** card image from an already-unpacked
/// vendor SD-recovery package directory. The card is a single FAT32 partition
/// carrying the vendor layout verbatim: flasher-OS trio at the root plus the
/// `bin/` NAND payload. This is the toolkit codification of the procedure proven
/// by hand on the bench S17 (2026-11-17).
///
/// `unpacked_pkg` is a directory (the caller unpacks a `.zip`/`.tar.gz` first,
/// reusing [`crate::stock_firmware`]'s extraction helpers or `unzip`). The
/// finished image is written to `out_img`.
pub fn build_stock_recovery_card(unpacked_pkg: &Path, out_img: &Path) -> Result<()> {
let layout = locate_vendor_card(unpacked_pkg)?;
let root = &layout.root;
// Size the card to comfortably hold the payload (flasher ~45 MB + bin ~34 MB)
// with slack, rounded up; a 256 MiB card is plenty and small to write/verify.
let card = CardImage::create(out_img, 256, "ANTMINER")?;
for f in ["uImage", "devicetree.dtb", "uramdisk.image.gz"] {
card.copy_file(&root.join(f), f)?;
}
// README.md is harmless vendor documentation; include it if present.
let readme = root.join("README.md");
if readme.is_file() {
card.copy_file(&readme, "README.md")?;
}
card.copy_dir(&root.join("bin"), "bin")?;
Ok(())
}
/// Write a finished card image to a block device with `dd`. **Destructive** --
/// the caller is responsible for confirming `device` is the intended removable
/// card (never a system disk). This never runs as part of image building.
pub fn write_image_to_device(img: &Path, device: &Path) -> Result<()> {
if !img.is_file() {
return Err(MediaError::MissingSource(img.display().to_string()));
}
let dd = find_tool("dd")?;
let mut cmd = Command::new(dd);
cmd.arg(format!("if={}", img.display()))
.arg(format!("of={}", device.display()))
.arg("bs=4M")
.arg("oflag=direct")
.arg("conv=fsync");
run(cmd, &format!("dd to {}", device.display()))
}
/// A minimal owned temp directory that removes itself on drop (the crate avoids
/// pulling a tempdir dependency; this mirrors the small helper style used
/// elsewhere).
mod tempdir {
use std::path::{Path, PathBuf};
pub struct TempHold {
path: PathBuf,
}
impl TempHold {
pub fn new() -> std::io::Result<TempHold> {
let base = std::env::temp_dir();
// Unique-ish without pulling rand: pid + a monotonic counter.
use std::sync::atomic::{AtomicU64, Ordering};
static CTR: AtomicU64 = AtomicU64::new(0);
let n = CTR.fetch_add(1, Ordering::Relaxed);
let dir = base.join(format!("alkane-media-{}-{}", std::process::id(), n));
std::fs::create_dir_all(&dir)?;
Ok(TempHold { path: dir })
}
pub fn path(&self) -> &Path {
&self.path
}
}
impl Drop for TempHold {
fn drop(&mut self) {
let _ = std::fs::remove_dir_all(&self.path);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn write(p: &Path, bytes: &[u8]) {
if let Some(parent) = p.parent() {
fs::create_dir_all(parent).unwrap();
}
fs::write(p, bytes).unwrap();
}
/// Build a fake vendor SD-recovery package (nested like the real one) and
/// assemble a stock-recovery card image from it, then read the card back
/// with `mdir`/`mtype` and confirm the layout and content survived.
#[test]
fn builds_a_stock_recovery_card_from_a_vendor_package() {
// Skip cleanly if the host lacks the tools (keeps CI green where the
// image toolchain is unavailable; the alkane-ci image carries them).
for t in ["sfdisk", "mkfs.vfat", "mcopy", "mmd", "mdir", "mtype"] {
if find_tool(t).is_err() {
eprintln!("skipping: {t} not available");
return;
}
}
let tmp = tempdir::TempHold::new().unwrap();
let pkg = tmp.path().join("SD_S17/inner");
// Flasher-OS trio at the card root.
write(&pkg.join("uImage"), b"FLASHER-KERNEL-xxxxxxxx");
write(&pkg.join("devicetree.dtb"), b"FLASHER-DTB");
write(&pkg.join("uramdisk.image.gz"), b"FLASHER-RAMDISK");
write(&pkg.join("README.md"), b"vendor notes");
// bin/ NAND payload.
write(&pkg.join("bin/BOOT.bin"), b"BOOTBIN-PAYLOAD");
write(&pkg.join("bin/devicetree.dtb"), b"MINER-DTB");
write(&pkg.join("bin/uImage"), b"MINER-KERNEL");
write(&pkg.join("bin/uramdisk.image.gz"), b"MINER-RAMDISK");
write(&pkg.join("bin/passwd.txt"), b"root\n");
let out = tmp.path().join("card.img");
build_stock_recovery_card(tmp.path(), &out).unwrap();
assert!(out.is_file());
// Read the card back via mtools against the partition at offset 1 MiB.
let mtoolsrc = tmp.path().join("verify.conf");
fs::write(
&mtoolsrc,
format!(
"drive C: file=\"{}\" offset={}\n",
out.display(),
PART_OFFSET_BYTES
),
)
.unwrap();
let mdir = find_tool("mdir").unwrap();
let listing = Command::new(&mdir)
.env("MTOOLSRC", &mtoolsrc)
.env("MTOOLS_SKIP_CHECK", "1")
.args(["-/", "C:/"])
.output()
.unwrap();
let text = String::from_utf8_lossy(&listing.stdout);
for name in ["UIMAGE", "DEVICETREE", "URAMDISK", "BIN", "BOOT"] {
assert!(
text.to_uppercase().contains(name),
"card listing missing {name}:\n{text}"
);
}
// Content check: bin/BOOT.bin round-trips.
let mtype = find_tool("mtype").unwrap();
let got = Command::new(&mtype)
.env("MTOOLSRC", &mtoolsrc)
.env("MTOOLS_SKIP_CHECK", "1")
.arg("C:/bin/BOOT.bin")
.output()
.unwrap();
assert_eq!(
String::from_utf8_lossy(&got.stdout).trim_end(),
"BOOTBIN-PAYLOAD"
);
}
#[test]
fn rejects_a_package_with_no_card_layout() {
let tmp = tempdir::TempHold::new().unwrap();
write(&tmp.path().join("random/file.txt"), b"nope");
let out = tmp.path().join("card.img");
let err = build_stock_recovery_card(tmp.path(), &out).unwrap_err();
assert!(matches!(err, MediaError::BadPackage(_)));
}
#[test]
fn sanitizes_volume_labels() {
assert_eq!(sanitize_label("alkane install!!"), "ALKANEINSTA");
assert_eq!(sanitize_label(""), "ALKANE");
assert_eq!(sanitize_label("ANTMINER"), "ANTMINER");
}
}