Artemis Milestone 2h: blkio_usb.c backend -- USB thumb drive is now a real block device

Wires a hot-plugged USB Mass Storage device into the block subsystem's
unified LBN chain. blkio_usb.c/blkio_usb.h mirror virtio_blk.c/
virtio_blk.h's established shape exactly (singleton state, blkio_vtable_t,
a blkio_usb_open_msc() "find" function playing virtio_blk_find_artemis()'s
role): read() translates a Forth block into a SCSI LBA/count pair and
calls xhci_bot_read_block() + xhci_bot_wait_for_idle(); write() returns
BLKIO_ENOSUP (no SCSI WRITE(10) exists yet, and blk_format_or_load_disk()
never writes at attach time, so read-only is sufficient -- confirmed by
reading that function first, not assumed). Refuses (-2) if the reported
SCSI block size doesn't evenly divide the 1024-byte Forth block size.

Connect-time wiring reuses the bot_msc_attach_pending/consume-in-
sk_repl_idle() shape the prior increment's temp probe already validated,
now made permanent: SET_CONFIGURATION sets the flag, sk_repl_idle()
(strictly after its own xhci_poll_events() call returns) calls
blkio_usb_open_msc() then blk_subsys_attach_device().

Verified live via hot-attach: full chain from USB connect through
'blkio_usb: MSC device ready' to 'blk: disk 'StarForth Volume' v2 LBN
26074..75184 (49111 user blocks)' -- real attachment, disk image confirmed
byte-for-byte untouched after. Chased a real debugging detour along the
way: the attach initially appeared silent (no blk: log line) -- traced to
LOG_INFO filtering at the default LOG_WARN boot level, not a functional
bug (settled via a temporary log-level bump, reverted after capture; also
found and reported, but did not fix, a pre-existing unrelated
Makefile.starkernel bug where --log-level=info via KERNEL_ARGS breaks
printf parsing). All three architectures re-verified clean. FABRIC-2.md
Section X 2h updated -- only hot-detach remains for 2h.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CXjAPTEKrgY2Mrk25KoLDn

FABRIC-2.md

@@ -3699,14 +3699,15 @@ afterward, all three architectures, clean boots with no BOT activity: `logs/2026
 `logs/20260825-114114/aarch64/`, `logs/20260825-114321/riscv64/`.
 
 **2h. Integration with the existing block subsystem**
-- [ ] Wire a working USB MSC device into `blk_subsys_attach_device()` (or
+- [x] Wire a working USB MSC device into `blk_subsys_attach_device()` (or
       `blk_subsys_add_raw_device()`, whichever fits — confirm which, since USB is
       persistent+removable, a hybrid of the two existing categories) — this is the point
       where Milestone 2's work actually becomes visible to everything in Section U/V's
-      block-layout design
-- [ ] Confirm a plugged-in USB drive shows up in the LBN chain at the expected offset
+      block-layout design. **Done 2026-08-25**, `blk_subsys_attach_device()` confirmed the
+      right call (per the "Confirmed with Captain Bob" note below), see writeup below
+- [x] Confirm a plugged-in USB drive shows up in the LBN chain at the expected offset
       (today: attach-order-based, per Section V area A — item below in Milestone 3 changes
-      this to identity-derived)
+      this to identity-derived). **Done 2026-08-25** — see writeup below
 
 **Confirmed with Captain Bob, 2026-08-22: `blk_subsys_attach_device()` is the right call, not
 `blk_subsys_add_raw_device()`.** Re-read the `block_subsystem.c` header comment
@@ -3789,10 +3790,69 @@ permanent, reusable substrate for the next 2h increment (the actual `blkio_usb.c
 Re-verified probe-free afterward, all three architectures, clean boots with no BOT activity:
 `logs/20260825-122016/amd64/`, `logs/20260825-122318/aarch64/`, `logs/20260825-122527/riscv64/`.
 
-Still ahead for 2h: the `blkio_usb.c` backend itself (per `blk_format_or_load_disk()`'s own
-"NEVER writes to disk here" discipline at attach time, a read-only backend is sufficient to land
-first — WRITE(10) doesn't exist in this driver yet and isn't a prerequisite), the connect-time
-call site wiring a ready `blkio_dev*` into `blk_subsys_attach_device()`, and the hot-detach path.
+**`blkio_usb.c` backend + connect-time attach, done 2026-08-25 — a USB thumb drive is now a real
+block device.** `src/starkernel/usb/blkio_usb.c`/`include/starkernel/blkio_usb.h` mirror
+`virtio_blk.c`/`virtio_blk.h`'s own established shape exactly (singleton state struct,
+`static const blkio_vtable_t`, a `blkio_usb_open_msc()` "find" function playing the same role
+`virtio_blk_find_artemis()` does): `read()` translates a Forth block number into a SCSI LBA/
+block-count pair (`lba = fblock * blocks_per_fblock`, matching `virtio_blk.h`'s own
+`VBLK_SECTORS_PER_BLOK` precedent for the same 1 KiB-Forth-block-as-N-SCSI-blocks idea) and
+calls `xhci_bot_read_block()` + `xhci_bot_wait_for_idle()`; `write()` returns `BLKIO_ENOSUP`
+(no SCSI WRITE(10) exists in this driver yet, and per `blk_format_or_load_disk()`'s own "NEVER
+writes to disk here" discipline at attach time, a read-only backend is sufficient — confirmed
+by reading that function before writing any code, not assumed); `open()`/`info()` are cheap
+(capacity discovery already happened in `blkio_usb_open_msc()` itself, matching `vblk_open()`'s
+own precedent of not re-discovering what a "find" function already found). `blkio_usb_open_msc()`
+refuses (`-2`) if the reported SCSI block size doesn't evenly divide `BLKIO_FORTH_BLOCK_SIZE`
+(1024) — this backend has no way to serve a partial Forth block, so it refuses rather than
+silently misbehaving (advisor-flagged before writing any code).
+
+Connect-time wiring reuses the exact `bot_msc_attach_pending`/consume-in-`sk_repl_idle()` shape
+the previous increment's temp probe already validated, just made permanent: the
+SET_CONFIGURATION completion handler sets the flag once a device is confirmed Mass Storage/BOT
+and configured; `sk_repl_idle()`, strictly after its own `xhci_poll_events()` call has already
+returned, consumes it by calling `blkio_usb_open_msc()` then `blk_subsys_attach_device()` — both
+synchronous, both requiring the same "outside `xhci_poll_events()`'s own call frame" constraint
+`xhci_bot_wait_for_idle()` itself carries.
+
+**A real, if minor, debugging detour: the attach appeared to silently do nothing.** First live
+run (`logs/20260825-123339/amd64/`) showed the full TUR→READ CAPACITY10→PASS→`blkio_usb: MSC
+device ready`→four TUR+READ10 cycles (the block subsystem's own 4 KiB header read, one cycle per
+1 KiB Forth block) — but no `blk: disk ...`/`blk: unrecognised ...` line ever appeared, and
+nothing else looked wrong either. Traced to `blk_subsys_attach_device()`'s own success log being
+`LOG_INFO`, filtered at this kernel's default `LOG_WARN` boot level — confirmed by grepping the
+same log for the *existing* virtio-blk/Artemis attach's own `blk: disk ...` line from earlier in
+the same boot and finding it equally absent, ruling out a regression before chasing one. Passing
+`--log-level=info` via `KERNEL_ARGS` turned out to be a dead end (a pre-existing, unrelated
+`Makefile.starkernel` bug: `printf '$(KERNEL_ARGS)\n'` misparses any value starting with `--` as
+a `printf` option itself, and GNU Make strips leading whitespace from command-line variable
+assignments too, so no quoting trick routes around it from the command line — reported here per
+this project's "report broken tooling, don't silently fix it unprompted" convention, not fixed).
+Settled instead by temporarily bumping `kernel_main.c`'s compiled-in default from `LOG_WARN` to
+`LOG_INFO` for one diagnostic boot (marked `TEMP PROBE`, reverted immediately after capture, same
+discipline as every other probe in this project) — `logs/20260825-123803/amd64/` is that run,
+and it settled the question cleanly: `blk: disk 'StarForth Volume' v2 LBN 26074..75184 (49111
+user blocks); devblocks=16384 bam=2 base=3 total=49143 free=49111`, appended right after the
+existing RAM/ramdrive/Artemis `blk:` lines in the same unified LBN chain — the USB drive was
+attached correctly the entire time, this was purely a log-visibility artifact, not a functional
+bug. `git status`/`sha256sum` on `disk/usb-thumbdrive-test.img` after this run confirmed the
+image byte-for-byte unchanged, as expected for a read-only backend. `PROVISIONAL` (not
+`FORMATTED`) is the correct outcome here too — the label reads `"StarForth Volume"` regardless of
+format state (it's `blk_compute_fresh_geometry()`'s own fixed placeholder string for *any* fresh/
+unrecognized disk, not something read back off this blank test image, confirmed by grepping
+`block_subsystem.c` itself rather than assumed from the log line alone).
+
+Reverted the diagnostic log-level bump; rebuilt and re-verified live via hot-attach one more time
+with the reverted (default `LOG_WARN`) tree to confirm the attach still succeeds without the INFO
+logging crutch (it does — same silent-but-working behavior as the very first run). All three
+architectures then re-verified clean with nothing hot-attached (this backend has no boot-time
+call site of its own — USB is inherently hotplug, so a boot with no device connected exercises
+none of this new code, same as every earlier BOT increment's own probe-free acceptance runs):
+`logs/20260825-124143/amd64/`, `logs/20260825-124323/aarch64/`, `logs/20260825-124909/riscv64/`.
+
+Still ahead for 2h: only the hot-**detach** path remains — `chain_append()` only adds, there is
+no removal function yet (Section V area A's identity-derived-offset work in Milestone 3 is a
+separate, later concern, not blocking here).
 
 ### Milestone 3 — Block subsystem extensions (Section U items 3-6, Section V area A)
 

capsules/BLOCK_MAP.md

@@ -1,5 +1,5 @@
 # Capsule Block Manifest — Auto-generated
-<!-- Generated by mkcapsule --manifest  2026-08-25T16:24:57Z -->
+<!-- Generated by mkcapsule --manifest  2026-08-25T16:48:38Z -->
 <!-- DO NOT EDIT — re-run mkcapsule --manifest to refresh.  -->
 <!-- Hand-written justifications and immutability notes live  -->
 <!-- in MANIFEST.md alongside this auto-generated index.      -->

include/starkernel/blkio_usb.h

@@ -0,0 +1,51 @@
+/*
+ * blkio_usb.h — USB Mass Storage (Bulk-Only Transport) blkio_dev backend
+ * for StarKernel, Milestone 2h. Presents a blkio_dev_t interface for
+ * attachment to the StarForth block subsystem via blk_subsys_attach_device(),
+ * matching virtio_blk.h's own precedent — built on top of the xHCI BOT
+ * driver's synchronous bridge (xhci_bot_wait_for_idle(), xhci_bot_get_capacity(),
+ * xhci_bot_read_block()) from Milestone 2h's foundational increment.
+ *
+ * Read-only this increment: no SCSI WRITE(10) exists in the xHCI driver yet
+ * (block_subsystem.c's own attach-time disk probing never writes, per
+ * blk_format_or_load_disk()'s "NEVER writes to disk here" discipline, so a
+ * read-only backend is sufficient to land this piece first).
+ *
+ * Only one USB MSC device is supported (single-outstanding-transaction
+ * scope, matching the xHCI driver it sits on).
+ */
+
+#ifndef STARKERNEL_BLKIO_USB_H
+#define STARKERNEL_BLKIO_USB_H
+
+#include <stdint.h>
+#include "blkio.h"
+#include "starkernel/xhci_driver.h"
+
+/*
+ * blkio_usb_open_msc — synchronously query a confirmed Mass Storage/BOT
+ *                        device's capacity (SCSI READ CAPACITY(10), via
+ *                        xhci_bot_get_capacity() + xhci_bot_wait_for_idle())
+ *                        and fill in *dev_out so the caller can pass it to
+ *                        blk_subsys_attach_device().
+ *
+ * xdev/slot_id identify an already-enumerated, already-configured Mass
+ * Storage/BOT device (SET_CONFIGURATION already succeeded) — this function
+ * does not enumerate or configure anything itself.
+ *
+ * MUST be called from outside xhci_poll_events()'s own call frame, same
+ * constraint as xhci_bot_wait_for_idle() itself (see its own doc comment
+ * in xhci_driver.h) — this function calls it directly.
+ *
+ * dev_out must point to a zero-initialised blkio_dev_t.
+ *
+ * Returns  0 on success.
+ * Returns -1 if xdev/slot_id are invalid, or the capacity query didn't PASS.
+ * Returns -2 if the device's reported SCSI block size doesn't evenly divide
+ *             BLKIO_FORTH_BLOCK_SIZE (1024) — this backend has no way to
+ *             serve a partial Forth block, so it refuses rather than
+ *             silently misbehaving.
+ */
+int blkio_usb_open_msc(blkio_dev_t *dev_out, xhci_dev_t *xdev, uint32_t slot_id);
+
+#endif /* STARKERNEL_BLKIO_USB_H */

include/starkernel/xhci_driver.h

@@ -232,6 +232,18 @@ typedef struct {
     uint32_t            bot_cap_last_lba;
     uint32_t            bot_cap_block_size;
 
+    /* Milestone 2h: set by the SET_CONFIGURATION completion handler
+     * (inside xhci_poll_events()'s own call frame, so it only sets a flag
+     * -- no doorbell ring, no xhci_bot_wait_for_idle() call, both unsafe
+     * from there) once a device is confirmed Mass Storage/SCSI/BOT and
+     * configured. Consumed by sk_repl_idle() strictly after its own
+     * xhci_poll_events() call has returned, which is the only place safe
+     * to actually act on it -- calls blkio_usb_open_msc() (READ CAPACITY(10)
+     * + xhci_bot_wait_for_idle(), both requiring that same "outside
+     * xhci_poll_events()" constraint) then blk_subsys_attach_device(). */
+    uint8_t             bot_msc_attach_pending;
+    uint32_t            bot_msc_attach_slot_id;
+
     /* Deferred chaining: a doorbell ring (new control transfer) must
      * never happen synchronously from inside xhci_poll_events()'s event-
      * processing loop, before ERDP has been updated for the event

src/starkernel/repl.c

@@ -35,6 +35,8 @@
 #include "starkernel/timer.h"
 #include "starkernel/arch.h"
 #include "starkernel/xhci_driver.h"
+#include "starkernel/blkio_usb.h"
+#include "block_subsystem.h"
 #include "word_source/include/keyboard_words.h"
 #include <stdint.h>
 #include <string.h>
@@ -87,6 +89,27 @@ static void sk_repl_idle(void)
      * controller was found/brought up (xhci_bringup() never latched a
      * device). */
     xhci_poll_events();
+
+    /* Milestone 2h: a Mass Storage/BOT device finished SET_CONFIGURATION
+     * during the xhci_poll_events() call just above -- run the
+     * synchronous capacity query + block-subsystem attach here, strictly
+     * after that call has already returned (see bot_msc_attach_pending's
+     * own doc comment in xhci_driver.h for why: xhci_bot_wait_for_idle()'s
+     * busy-wait -- which blkio_usb_open_msc() uses internally -- must
+     * never run from inside xhci_poll_events()'s own call frame). */
+    xhci_dev_t *xdev = xhci_get_dev();
+    if (xdev && xdev->bot_msc_attach_pending) {
+        xdev->bot_msc_attach_pending = 0;
+        uint32_t slot_id = xdev->bot_msc_attach_slot_id;
+
+        static blkio_dev_t usb_blk_dev;
+        int rc = blkio_usb_open_msc(&usb_blk_dev, xdev, slot_id);
+        if (rc == 0) {
+            blk_subsys_attach_device(&usb_blk_dev);
+        } else {
+            console_println("xhci: USB MSC block-subsystem attach failed");
+        }
+    }
 }
 
 /*===========================================================================

src/starkernel/usb/blkio_usb.c

@@ -0,0 +1,127 @@
+/*
+ * blkio_usb.c — USB Mass Storage (Bulk-Only Transport) blkio_dev backend,
+ * see blkio_usb.h. Milestone 2h.
+ */
+
+#ifndef __STARKERNEL__
+#error "blkio_usb.c is kernel-only"
+#endif
+
+#include <stddef.h>
+#include <stdint.h>
+#include <string.h>
+
+#include "starkernel/blkio_usb.h"
+#include "console.h"
+
+typedef struct {
+    xhci_dev_t *xdev;
+    uint32_t    slot_id;
+    uint32_t    scsi_block_size;
+    uint32_t    scsi_blocks_per_fblock; /* BLKIO_FORTH_BLOCK_SIZE / scsi_block_size */
+    uint32_t    total_forth_blocks;
+} BlkioUsbState;
+
+/* Singleton — one USB MSC device (single-outstanding-transaction scope,
+ * matching the xHCI driver this backend sits on). */
+static BlkioUsbState g_usb_blk;
+
+static int usb_blk_open(blkio_dev_t *dev, const blkio_params_t *p) {
+    (void)p;
+    if (!dev) return BLKIO_EINVAL;
+    dev->state            = &g_usb_blk;
+    dev->forth_block_size = BLKIO_FORTH_BLOCK_SIZE;
+    dev->total_blocks     = g_usb_blk.total_forth_blocks;
+    return BLKIO_OK;
+}
+
+static int usb_blk_close(blkio_dev_t *dev) {
+    (void)dev;
+    return BLKIO_OK;
+}
+
+static int usb_blk_read(blkio_dev_t *dev, uint32_t fblock, void *dst) {
+    if (!dev || !dst) return BLKIO_EINVAL;
+    BlkioUsbState *s = (BlkioUsbState *)dev->state;
+    if (fblock >= s->total_forth_blocks) return BLKIO_EINVAL;
+
+    uint32_t lba = fblock * s->scsi_blocks_per_fblock;
+    if (xhci_bot_read_block(s->xdev, s->slot_id, lba,
+                             (uint16_t)s->scsi_blocks_per_fblock,
+                             s->scsi_block_size) != 0) {
+        return BLKIO_EIO;
+    }
+    if (xhci_bot_wait_for_idle(s->xdev, 100000u) != BOT_STATUS_PASS) {
+        return BLKIO_EIO;
+    }
+    memcpy(dst, s->xdev->bot_data_buf, BLKIO_FORTH_BLOCK_SIZE);
+    return BLKIO_OK;
+}
+
+static int usb_blk_write(blkio_dev_t *dev, uint32_t fblock, const void *src) {
+    (void)dev;
+    (void)fblock;
+    (void)src;
+    /* No SCSI WRITE(10) in the xHCI driver yet — read-only this increment,
+     * see blkio_usb.h's own doc comment. */
+    return BLKIO_ENOSUP;
+}
+
+static int usb_blk_flush(blkio_dev_t *dev) {
+    (void)dev;
+    return BLKIO_OK; /* nothing buffered to flush — read-only backend */
+}
+
+static int usb_blk_info(blkio_dev_t *dev, blkio_info_t *out) {
+    if (!dev || !out) return BLKIO_EINVAL;
+    BlkioUsbState *s = (BlkioUsbState *)dev->state;
+    out->forth_block_size = BLKIO_FORTH_BLOCK_SIZE;
+    out->total_blocks     = s->total_forth_blocks;
+    out->phys_sector_size = s->scsi_block_size;
+    out->phys_size_bytes  = (uint64_t)s->total_forth_blocks * BLKIO_FORTH_BLOCK_SIZE;
+    out->read_only        = 1;
+    return BLKIO_OK;
+}
+
+static const blkio_vtable_t g_usb_blk_vtable = {
+    .open  = usb_blk_open,
+    .close = usb_blk_close,
+    .read  = usb_blk_read,
+    .write = usb_blk_write,
+    .flush = usb_blk_flush,
+    .info  = usb_blk_info
+};
+
+int blkio_usb_open_msc(blkio_dev_t *dev_out, xhci_dev_t *xdev, uint32_t slot_id) {
+    if (!dev_out || !xdev) return -1;
+
+    if (xhci_bot_get_capacity(xdev, slot_id) != 0) return -1;
+    if (xhci_bot_wait_for_idle(xdev, 100000u) != BOT_STATUS_PASS) return -1;
+
+    uint32_t block_size = xdev->bot_cap_block_size;
+    if (block_size == 0 || (BLKIO_FORTH_BLOCK_SIZE % block_size) != 0) {
+        console_println("blkio_usb: SCSI block size doesn't divide Forth block size -- refusing");
+        return -2;
+    }
+
+    uint64_t total_scsi_blocks = (uint64_t)xdev->bot_cap_last_lba + 1u;
+    uint32_t blocks_per_fblock = BLKIO_FORTH_BLOCK_SIZE / block_size;
+    uint64_t total_forth_blocks = total_scsi_blocks / blocks_per_fblock;
+
+    g_usb_blk.xdev = xdev;
+    g_usb_blk.slot_id = slot_id;
+    g_usb_blk.scsi_block_size = block_size;
+    g_usb_blk.scsi_blocks_per_fblock = blocks_per_fblock;
+    g_usb_blk.total_forth_blocks = (total_forth_blocks > 0xFFFFFFFFull)
+                                    ? 0xFFFFFFFFu
+                                    : (uint32_t)total_forth_blocks;
+
+    console_println("blkio_usb: MSC device ready");
+
+    blkio_params_t params;
+    params.forth_block_size = BLKIO_FORTH_BLOCK_SIZE;
+    params.total_blocks     = g_usb_blk.total_forth_blocks;
+    params.opaque           = NULL;
+
+    return blkio_open(dev_out, &g_usb_blk_vtable, &params);
+}

src/starkernel/usb/xhci.c

@@ -325,6 +325,8 @@ int xhci_bringup(xhci_dev_t *dev)
     dev->bot_read10_block_size = 0;
     dev->bot_cap_last_lba = 0;
     dev->bot_cap_block_size = 0;
+    dev->bot_msc_attach_pending = 0;
+    dev->bot_msc_attach_slot_id = 0;
     dev->next_action = XHCI_NEXT_ACTION_NONE;
     dev->next_action_slot_id = 0;
     dev->next_action_length = 0;
@@ -1403,6 +1405,13 @@ void xhci_poll_events(void)
                         }
                         case XHCI_XFER_SET_CONFIG: {
                             console_println("xhci: device configured");
+                            /* Milestone 2h: hand off to sk_repl_idle(),
+                             * the only safe place to run the synchronous
+                             * capacity query + block-subsystem attach --
+                             * see bot_msc_attach_pending's own doc
+                             * comment in xhci_driver.h. */
+                            dev->bot_msc_attach_pending = 1;
+                            dev->bot_msc_attach_slot_id = xfer_slot_id;
                             break;
                         }
                         case XHCI_XFER_CBW_SENT: {