zynq: add the stage-2 install mode (nand-install-stage2) for Leg 2

install_stage2 writes the uImage-wrapped stage-2 U-Boot to the kernel slot
(0x2000000) and the Alkane payload FIT to the rootfs slot (0x2800000) from the
stock side, after carving the v2 OOB stock backup; BOOT.bin preserved; both
slots read-back-verified. CLI: `afw nand-install-stage2 --host --stage2 --fit
--confirm FLASH`. Uses the method-free $ALKANE_OUTCOME_LOG progress logger.

Exercised on the bench S17: the install writes + carves correctly and the FIT it
places boots via stock bootm (crc32 OK, Alkane Linux up). The stock->stage-2
chainload itself is the from-stock boot mechanism (DSH's domain) and is the open
piece. 93 flash tests green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
2026-11-18 18:12:32 -06:00
co-authored by Claude Opus 4.8
parent 117e572407
commit 0dda194e1e
2 changed files with 107 additions and 0 deletions
+36
View File
@@ -1313,6 +1313,41 @@ fn run_nand_restore_onboard(args: &[String]) -> Result<(), Box<dyn std::error::E
Ok(())
}
/// Install the own stage-2 U-Boot + Alkane FIT onto a board on stock (Leg 2):
/// stage-2 uImage -> 0x2000000 (stock ECC), FIT -> 0x2800000; BOOT.bin preserved.
fn run_nand_install_stage2(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
let opts = parse_args(
args,
&[ssh_values(), &["confirm", "stage2", "fit"]].concat(),
&[],
)?;
let host = opts.value("host").ok_or("--host is required")?.to_owned();
let stage2_path = opts
.value("stage2")
.ok_or("--stage2 <uImage> is required")?
.to_owned();
let fit_path = opts
.value("fit")
.ok_or("--fit <itb> is required")?
.to_owned();
if opts.value("confirm") != Some("FLASH") {
return Err("refusing to install the stage-2 without --confirm FLASH".into());
}
let password = read_board_password(&opts)?;
let stage2 = fs::read(&stage2_path).map_err(|e| format!("reading {stage2_path}: {e}"))?;
let fit = fs::read(&fit_path).map_err(|e| format!("reading {fit_path}: {e}"))?;
println!(
"installing stage-2 U-Boot ({} B) + FIT ({} B) onto stock {host} (network-only)...",
stage2.len(),
fit.len()
);
zynq_nand::install_stage2(&host, &stage2, &fit, password.as_deref())?;
println!(
"stage-2 install reported success (stage-2 + FIT written, BOOT.bin preserved, 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).
@@ -1413,6 +1448,7 @@ fn run_afw(args: &[String]) -> Result<(), Box<dyn std::error::Error>> {
"nand-restore-stock" => run_nand_restore_stock(rest),
"nand-backup-check" => run_nand_backup_check(rest),
"nand-restore-onboard" => run_nand_restore_onboard(rest),
"nand-install-stage2" => run_nand_install_stage2(rest),
other => Err(format!("unknown afw subcommand {other}").into()),
}
}
+71
View File
@@ -950,6 +950,77 @@ fn install_from_stock_inner(
Ok(())
}
/// Install the own stage-2 U-Boot (Leg 2) onto a board currently on stock.
/// Writes the uImage-wrapped stage-2 to the kernel slot (0x2000000) and the
/// Alkane payload FIT to the rootfs slot (0x2800000), from the stock side (both
/// stock-ECC), after carving the genuine-stock backup. BOOT.bin preserved.
///
/// Boot chain after this: stock FSBL/U-Boot nandboot `bootm`s the stage-2 at
/// 0x2000000 (read with stock ECC); the stage-2 then reads the FIT at 0x2800000
/// with NAND_ECC_NONE (raw data + FIT crc32) and `bootm`s it. The dtb slot
/// (0x1a00000) keeps the genuine stock dtb (the stage-2 uses its own embedded
/// DT and ignores what stock's nandboot passes it).
pub fn install_stage2(
host: &str,
stage2_uimage: &[u8],
fit: &[u8],
password: Option<&str>,
) -> Result<(), StockError> {
outcome(&format!(
"install_stage2: begin host={host} stage2={} fit={}",
stage2_uimage.len(),
fit.len()
));
let mut sh = StockShell {
host: host.to_owned(),
password: password.map(str::to_owned),
};
let r = install_stage2_inner(&mut sh, stage2_uimage, fit);
match &r {
Ok(()) => outcome("install_stage2: COMPLETE (stage-2 + FIT written+verified, rebooting)"),
Err(e) => outcome(&format!("install_stage2: ERROR {e}")),
}
r
}
fn install_stage2_inner(
sh: &mut dyn Shell,
stage2_uimage: &[u8],
fit: &[u8],
) -> Result<(), StockError> {
if first_token(&sh.exec("id -u")?) != "0" {
return Err(StockError::Auth(
"did not obtain root on the stock board".into(),
));
}
outcome("root: ok");
let table = read_mtd_table(sh)?;
outcome(&format!("mtd-table: {} partitions", table.len()));
if stage2_uimage.len() as u64 > SLOT_KERNEL {
return Err(StockError::Method(
"stage-2 uImage over the kernel slot ceiling (0x800000)".into(),
));
}
if fit.len() as u64 > SLOT_ROOTFS {
return Err(StockError::Method(
"FIT over the rootfs slot ceiling (0x2000000)".into(),
));
}
// Carve the genuine-stock backup before any boot-slot write.
outcome("carve: begin (v2, OOB-preserving)");
carve_backup(sh, &table)?;
outcome("carve: ok (v2 stock backup written)");
// FIT first, then the stage-2, so an interrupted run never leaves a new
// stage-2 pointing at a half-written FIT.
outcome("write FIT -> 0x2800000");
write_abs(sh, &table, OFF_ROOTFS, fit, "fit")?;
outcome("write stage-2 -> 0x2000000");
write_abs(sh, &table, OFF_KERNEL, stage2_uimage, "stage2")?;
outcome("boot slots written+verified");
reboot(sh);
Ok(())
}
/// Return an alkane board to genuine stock from a vendor firmware FILE.
///
/// This is refused on the Zynq-7010: a vendor file carries image data only, with