From 8b2fb448c7463974fd798343154504cd123d9877 Mon Sep 17 00:00:00 2001 From: Robert Allan James Date: Wed, 26 Aug 2026 07:56:07 -0400 Subject: [PATCH] Clarify: home-blocks thumbdrives are not bound to any particular size Captain Bob's correction. 64MB (disk/zuse.img, usb-thumbdrive-test.img) was always just an arbitrary QEMU-test convenience size, never a real-world constraint -- but the docs and script didn't say so explicitly, and an earlier memory's "16GB reference size" phrasing (already hedged as tentative) risked reading as a decided target. Audited the actual format for hardcoded size assumptions: none found. homeblocks_sig_t already carries its own metadata_devblocks field, recording whatever size a real drive's partition actually is. Changes: scripts/bleach_zuse_img.sh gains a --size-mb override (tested both the override and the unchanged default); disk/README.md's zuse.img entry and FABRIC-3.md both now state the point explicitly; the memory file and its MEMORY.md index line corrected to match (the GPT layout's design point is the *proportions* -- small metadata partition, everything else block storage -- not any absolute size). Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn --- FABRIC-3.md | 12 ++++++++++++ disk/README.md | 32 ++++++++++++++++++++------------ scripts/bleach_zuse_img.sh | 31 +++++++++++++++++++++++++++---- 3 files changed, 59 insertions(+), 16 deletions(-) diff --git a/FABRIC-3.md b/FABRIC-3.md index d072daf..f1096a1 100644 --- a/FABRIC-3.md +++ b/FABRIC-3.md @@ -301,6 +301,18 @@ decisions get added here, not to `FABRIC-2.md`. Follow the same discipline `FABR kernel code touched this step (host-side test tooling only), so no 3-arch acceptance boot needed — single live amd64 QMP-hotplug confirmation is the right verification tier. + **Correction (Captain Bob, 2026-08-26): drives are not bound to any particular size.** + 64MB was only ever this fixture's arbitrary test-convenience size, matching + `usb-thumbdrive-test.img`'s existing BOT-driver-testing precedent — never a real-world + constraint. Audited for anywhere this might have implied otherwise: the actual format + (`homeblocks_sig_t`) already carries its own `metadata_devblocks` field and hardcodes no + size anywhere, confirmed clean. `scripts/bleach_zuse_img.sh` gained a `--size-mb` override + so this was never a hidden assumption baked into the tooling either. The earlier + `project_usb_thumbdrive_gpt_layout.md` memory's "16GB reference size" phrasing (already + hedged as tentative, but risked reading as a target) corrected to state the point + explicitly — the GPT layout's design point is the *proportions* (small metadata partition, + everything else block storage), not any absolute size. + **Still open, not attempted:** the mint-then-pin boot-sequence fix itself, the `MINT` word, and the Zuse recovery path. diff --git a/disk/README.md b/disk/README.md index 5020db7..5967206 100644 --- a/disk/README.md +++ b/disk/README.md @@ -85,18 +85,26 @@ carrying timestamp noise in git history. - `zuse.img` — 64MB raw image simulating the physical Zuse superuser thumbdrive for QEMU testing (FABRIC-3.md, Phase 8: `zuse.img` "bleach" - mechanism, added 2026-08-26). Blank (all zero) at creation — reads back - as `HOMEBLOCKS_SIG_BLANK` via `homeblocks_sig_check()`, confirmed live - (`xhci: USB drive not recognized (blank or foreign media)`), simulating - a genuine first boot for exercising the still-to-be-built one-time - mint-Zuse flow. **"Bleach" it back to this pristine/unminted state with - `scripts/bleach_zuse_img.sh`** before each first-boot test run, rather - than hand-regenerating the file — same all-zero content either way, the - script just makes the reset a single documented, repeatable command. - Deliberately a flat/raw image, not GPT-partitioned, matching - `homeblocks_sig_check()`'s current call site (`repl.c`, - `sig_start_fblock=0`) — both will move to a real GPT-partition-relative - offset together once a GPT parser exists, not attempted ahead of that. + mechanism, added 2026-08-26). **64MB is only this fixture's size, not a + constraint on real home-blocks thumbdrives** (Captain Bob, 2026-08-26) — + the design is not bound to any particular drive size; `homeblocks_sig_t`'s + own `metadata_devblocks` field records whatever size is actually observed + on a real drive, nothing in the format hardcodes one. 64MB here is purely + an arbitrary QEMU-test convenience (matching `usb-thumbdrive-test.img`'s + existing precedent for BOT driver testing scale); use + `scripts/bleach_zuse_img.sh --size-mb N` for a different test size. Blank + (all zero) at creation — reads back as `HOMEBLOCKS_SIG_BLANK` via + `homeblocks_sig_check()`, confirmed live (`xhci: USB drive not recognized + (blank or foreign media)`), simulating a genuine first boot for exercising + the still-to-be-built one-time mint-Zuse flow. **"Bleach" it back to this + pristine/unminted state with `scripts/bleach_zuse_img.sh`** before each + first-boot test run, rather than hand-regenerating the file — same + all-zero content either way, the script just makes the reset a single + documented, repeatable command. Deliberately a flat/raw image, not + GPT-partitioned, matching `homeblocks_sig_check()`'s current call site + (`repl.c`, `sig_start_fblock=0`) — both will move to a real + GPT-partition-relative offset together once a GPT parser exists, not + attempted ahead of that. **Convention, standing as of 2026-08-22: every virtual disk/thumb-drive image used for testing — Artemis persistence disks above, and USB Mass Storage diff --git a/scripts/bleach_zuse_img.sh b/scripts/bleach_zuse_img.sh index 4239b69..a2126f0 100755 --- a/scripts/bleach_zuse_img.sh +++ b/scripts/bleach_zuse_img.sh @@ -1,5 +1,6 @@ #!/bin/bash -# bleach_zuse_img.sh - Reset disk/zuse.img back to pristine/unminted state. +# bleach_zuse_img.sh - Reset disk/zuse.img (or any home-blocks test image) +# back to pristine/unminted state. # # disk/zuse.img simulates the physical Zuse superuser thumbdrive for QEMU # testing (FABRIC-3.md, Phase 8 kickoff). "Bleaching" it means restoring the @@ -8,21 +9,43 @@ # be exercised repeatedly during development without hand-regenerating the # whole image each time. # +# 64MB is only this script's default -- an arbitrary QEMU-test convenience +# size (matching the existing usb-thumbdrive-test.img precedent for BOT +# driver testing scale), not a constraint on real home-blocks thumbdrives. +# The design is not bound to any particular drive size: homeblocks_sig_t's +# own metadata_devblocks field records whatever size is actually observed, +# nothing in the format or this repo hardcodes one. Override with --size-mb +# for a different test size. +# # Deliberately a flat/raw image, not GPT-partitioned, matching the same # simplifying assumption homeblocks_sig_check()'s current call site in # repl.c uses (sig_start_fblock=0) -- both will need to move to a real # GPT-partition-relative offset together, once a GPT parser exists. Not # invented ahead of that work here. # -# Usage: scripts/bleach_zuse_img.sh [path] -# path Optional override; defaults to disk/zuse.img relative to repo root. +# Usage: scripts/bleach_zuse_img.sh [path] [--size-mb N] +# path Optional override; defaults to disk/zuse.img relative to repo root. +# --size-mb N Optional override; defaults to 64 (arbitrary test convenience, see above). set -euo pipefail REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -IMG="${1:-$REPO_ROOT/disk/zuse.img}" +IMG="$REPO_ROOT/disk/zuse.img" SIZE_MB=64 +while [ $# -gt 0 ]; do + case "$1" in + --size-mb) + SIZE_MB="$2" + shift 2 + ;; + *) + IMG="$1" + shift + ;; + esac +done + if [ -e "$IMG" ] && [ ! -f "$IMG" ]; then echo "bleach_zuse_img: refusing to overwrite non-regular-file '$IMG'" >&2 exit 1