/*
 * 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-write since 2026-08-28 (FABRIC-3.md §F.1): SCSI WRITE(10) is real
 * (xhci_bot_send_write10()/xhci_bot_write_block()/xhci_bot_write_data_out(),
 * xhci.c), mirroring READ(10)'s existing CBW/data-stage/CSW machinery with
 * the data direction flipped. Verified live on amd64: BLK-CONFIRM-FORMAT's
 * BAM/reloc zero-page writes and an explicit block content write both
 * survived a cold reboot and read back correctly.
 *
 * 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 */