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

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