board_usb_vhost.c

Go to the documentation of this file.

 
#include <stdio.h>
#include <string.h>
 
#include "board_usb_internal.h"
#include "emu_host_io_internal.h"
#include "ra8_elc_regs.h"
#include "ra8_usb_regs.h"
 
/* =============================================================================
 * Device-class awareness -- the host detects HID / MSC / CDC from the enumerated
 * interface descriptor and surfaces the class-specific traffic after CONFIGURED,
 * so usb_hid_device / usb_msc_device exercise their data path instead of being
 * mislabelled "CDC-ACM active".
 * =============================================================================
 */
 
uint8_t  s_dev_class;   
uint32_t s_hid_reports; 
int32_t  s_hid_cx;      
int32_t  s_hid_cy;      
uint8_t  s_hid_buttons; 

const char* priv_usb_class_active_str(void)
{
  switch ((usb_dev_class_t)s_dev_class) {
    case k_usb_class_hid:
      return "HID active";
    case k_usb_class_msc:
      return "MSC active";
    case k_usb_class_cdc:
      return "CDC-ACM active";
    case k_usb_class_printer:
      return "Printer active";
    case k_usb_class_vendor:
      return "Vendor active";
    case k_usb_class_unknown:
    default:
      return "configured";
  }
}

void priv_usb_detect_class(const uint8_t* d, uint16_t len)
{
  if (s_dev_class != (uint8_t)k_usb_class_unknown) {
    return;
  }
  uint16_t i = 0U;
  while (((uint32_t)i + 2U) <= (uint32_t)len) {
    const uint8_t blen  = d[i];
    const uint8_t btype = d[i + 1U];
    if (blen == 0U) {
      break;
    }
    if ((btype == (uint8_t)k_usb_dt_interface) && (((uint32_t)i + 6U) <= (uint32_t)len)) {
      const uint8_t icls = d[i + k_iface_class_off];
      if (icls == (uint8_t)k_usb_iclass_hid) {
        s_dev_class = (uint8_t)k_usb_class_hid;
        return;
      }
      if (icls == (uint8_t)k_usb_iclass_msc) {
        s_dev_class = (uint8_t)k_usb_class_msc;
        return;
      }
      if ((icls == (uint8_t)k_usb_iclass_cdc_comm) || (icls == (uint8_t)k_usb_iclass_cdc_data)) {
        s_dev_class = (uint8_t)k_usb_class_cdc;
        return;
      }
      if (icls == (uint8_t)k_usb_iclass_printer) {
        s_dev_class = (uint8_t)k_usb_class_printer;
        return;
      }
      if (icls == (uint8_t)k_usb_iclass_vendor) {
        s_dev_class = (uint8_t)k_usb_class_vendor;
        return;
      }
    }
    i = (uint16_t)((uint32_t)i + (uint32_t)blen);
  }
}

RA8_INTERNAL static void internal_usb_hid_decode_report(const uint8_t* d, uint16_t len)
{
  if (len < 3U) {
    return;
  }
  s_hid_buttons = d[0];
  s_hid_cx += (int32_t)(int8_t)d[1];
  s_hid_cy += (int32_t)(int8_t)d[2];
  s_hid_reports++;
  if (s_trace) {
    (void)priv_emu_io_errf("  [usb] HID mouse report: btn=0x%02X dx=%+d dy=%+d -> cursor (%d,%d)\n",
                           (unsigned)s_hid_buttons,
                           (int)(int8_t)d[1],
                           (int)(int8_t)d[2],
                           (int)s_hid_cx,
                           (int)s_hid_cy);
  }
}
 
/* =============================================================================
 * Virtual USB host -- chapter-9 enumeration script + step machine.
 * =============================================================================
 */

static const usb_setup_step_t s_k_enum_script[] = {
  {k_usb_dir_device_to_host,
   k_usb_req_get_descriptor,
   (uint16_t)(k_usb_dt_device << 8),
   0U,
   (uint16_t)k_usb_desc8_len,
   "GET_DESCRIPTOR(device,8)"},
  {k_usb_dir_device_to_host,
   k_usb_req_get_descriptor,
   (uint16_t)(k_usb_dt_device << 8),
   0U,
   (uint16_t)k_usb_desc_dev_len,
   "GET_DESCRIPTOR(device,full)"},
  {k_usb_dir_host_to_device,
   k_usb_req_set_address,
   (uint16_t)k_usb_addr_assigned,
   0U,
   0U,
   "SET_ADDRESS(7)"},
  {k_usb_dir_device_to_host,
   k_usb_req_get_descriptor,
   (uint16_t)(k_usb_dt_device << 8),
   0U,
   (uint16_t)k_usb_desc_dev_len,
   "GET_DESCRIPTOR(device,full)"},
  {k_usb_dir_device_to_host,
   k_usb_req_get_descriptor,
   (uint16_t)(k_usb_dt_config << 8),
   0U,
   (uint16_t)k_usb_cfg_probe_len,
   "GET_DESCRIPTOR(config,9)"},
  {k_usb_dir_device_to_host,
   k_usb_req_get_descriptor,
   (uint16_t)(k_usb_dt_config << 8),
   0U,
   (uint16_t)k_usb_cfg_full_cap,
   "GET_DESCRIPTOR(config,full)"},
  {k_usb_dir_device_to_host,
   k_usb_req_get_descriptor,
   (uint16_t)(k_usb_dt_string << 8),
   0U,
   (uint16_t)k_usb_str_len,
   "GET_DESCRIPTOR(string,0)"},
  {k_usb_dir_host_to_device,
   k_usb_req_set_config,
   (uint16_t)k_usb_config_value,
   0U,
   0U,
   "SET_CONFIGURATION(1)"},
  {(uint8_t)k_usb_dir_host_to_device | (uint8_t)k_usb_req_class_iface,
   k_cdc_req_set_line_coding,
   0U,
   0U,
   k_cdc_line_coding_len,
   "SET_LINE_CODING"},
  {(uint8_t)k_usb_dir_host_to_device | (uint8_t)k_usb_req_class_iface,
   k_cdc_req_set_control_line_state,
   0x0003U,
   0U,
   0U,
   "SET_CONTROL_LINE_STATE"},
};

bool priv_host_device_attached(void)
{
  const uint16_t syscfg = s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_syscfg)];
  return (syscfg & (uint16_t)(1U << k_ra8_syscfg_bit_dprpu)) != 0U;
}

RA8_INTERNAL static void internal_host_latch_setup(const usb_setup_step_t* s)
{
  s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_usbreq)] =
    (uint16_t)(s->bm_request_type | (uint16_t)((uint16_t)s->b_request << k_usb_byte_bits));
  s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_usbval)]  = s->w_value;
  s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_usbindx)] = s->w_index;
  s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_usbleng)] = s->w_length;
}

RA8_INTERNAL static uint16_t internal_host_setup_ctsq(const usb_setup_step_t* s)
{
  if ((s->bm_request_type & (uint8_t)k_usb_dir_device_to_host) != 0U) {
    return (uint16_t)k_ra8_ctsq_rdds; /* control read data stage. */
  }
  if (s->w_length != 0U) {
    return (uint16_t)k_ra8_ctsq_wrds; /* control write data stage. */
  }
  return (uint16_t)k_ra8_ctsq_wrnd; /* no-data control. */
}

void priv_host_deliver_setup(uc_engine* uc, const usb_setup_step_t* s)
{
  /* Clear any stale DCP state from the previous transfer. */
  s_usb.dcp_in.len    = 0U;
  s_usb.dcp_in.valid  = false;
  s_usb.dcp_out.len   = 0U;
  s_usb.dcp_out.rd    = 0U;
  s_usb.dcp_out.ready = false;
  /* For an OUT-data control transfer, stage placeholder bytes the device can
   * drain through the DCP if its class handler reads them. Skipped under the
   * external-host bridge: there the REAL host payload arrives via
   * board_usb_bridge_dcp_out(), and a placeholder would let the device drain
   * zeros before it lands. */
  if (!s_external_host && ((s->bm_request_type & (uint8_t)k_usb_dir_device_to_host) == 0U) &&
      (s->w_length != 0U)) {
    const uint16_t n =
      (s->w_length < (uint16_t)k_usb_dcp_mps) ? s->w_length : (uint16_t)k_usb_dcp_mps;
    s_usb.dcp_out.len   = n;
    s_usb.dcp_out.rd    = 0U;
    s_usb.dcp_out.ready = true;
    (void)memset(s_usb.dcp_out.data, 0, sizeof(s_usb.dcp_out.data));
  }
  internal_host_latch_setup(s);
  s_usb.setup_valid = true;
  s_usb.ctsq        = internal_host_setup_ctsq(s);
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_ctrt);
  char line[k_usb_log_width];
  (void)snprintf(line, sizeof(line), "SETUP[%u] %s -> CTRT raised", (unsigned)s_host_step, s->name);
  priv_usb_log_line(line);
  priv_usb_raise_irq(uc);
}

RA8_INTERNAL static void internal_host_drain_in(void)
{
  priv_usb_log_count("control-IN: device returned", (unsigned)s_usb.dcp_in.len);
  priv_usb_detect_class(s_usb.dcp_in.data, s_usb.dcp_in.len);
  s_usb.dcp_in.len   = 0U;
  s_usb.dcp_in.valid = false;
}

bool priv_host_dcp_pid_buf(void)
{
  const uint16_t dcpctr = s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_dcpctr)];
  return (dcpctr & (uint16_t)k_ra8_pid_mask) == (uint16_t)k_ra8_pid_buf;
}

bool priv_host_take_ccpl(void)
{
  const uint32_t w    = internal_usb_word((uint64_t)k_ra8_usb_off_dcpctr);
  const uint16_t ccpl = (uint16_t)(1U << k_ra8_dcpctr_bit_ccpl);
  const bool     seen = (s_usb.reg[w] & ccpl) != 0U;
  if (seen) {
    s_usb.reg[w] = (uint16_t)(s_usb.reg[w] & (uint16_t)~ccpl); /* SIE clears CCPL. */
  }
  return seen;
}

void priv_host_apply_no_data(uc_engine* uc, const usb_setup_step_t* s)
{
  if (s->b_request == (uint8_t)k_usb_req_set_address) {
    /* The SIE latches USBADDR and owns the IN-ZLP status stage itself; mirror
     * that and advance the device state to Address (HUM Ch 36.3). */
    s_usb.reg[internal_usb_word((uint64_t)k_ra8_usb_off_usbaddr)] =
      (uint16_t)(s->w_value & (uint16_t)k_ra8_usbaddr_addr_mask);
    s_usb.dvsq = (uint16_t)k_ra8_dvsq_address;
    priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_dvst);
    char line[k_usb_log_width];
    (void)
      snprintf(line, sizeof(line), "SET_ADDRESS: DVSQ -> Address (addr=%u)", (unsigned)s->w_value);
    priv_usb_log_line(line);
    priv_usb_raise_irq(uc);
  }
}

RA8_INTERNAL static void internal_host_step_deliver(uc_engine* uc, const usb_setup_step_t* s)
{
  priv_host_deliver_setup(uc, s);
  s_host_wait = 0U;
  if ((s->bm_request_type & (uint8_t)k_usb_dir_device_to_host) != 0U) {
    s_host_substate = (uint8_t)k_sub_wait_in; /* control read: wait for data. */
  } else if (s->b_request == (uint8_t)k_usb_req_set_address) {
    priv_host_apply_no_data(uc, s);
    s_host_substate = (uint8_t)k_sub_next; /* SIE-handled; no device CCPL. */
  } else {
    s_host_substate = (uint8_t)k_sub_wait_ack; /* no/OUT-data: wait for CCPL. */
  }
}

RA8_INTERNAL static void internal_host_step_wait_in(void)
{
  if (s_usb.dcp_in.valid && priv_host_dcp_pid_buf()) {
    internal_host_drain_in();
    s_host_substate = (uint8_t)k_sub_status;
    s_host_wait     = 0U;
    return;
  }
  s_host_wait++;
  if (s_host_wait > (uint32_t)k_usb_step_timeout) {
    priv_usb_log_count("STALLED waiting for control-IN data at step", (unsigned)s_host_step);
    s_host_substate = (uint8_t)k_sub_status; /* push on; report the stall. */
    s_host_wait     = 0U;
  }
}

RA8_INTERNAL static void internal_host_step_status(uc_engine* uc)
{
  s_usb.ctsq        = (uint16_t)k_ra8_ctsq_rdss; /* read status stage. */
  s_usb.setup_valid = false;
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_ctrt);
  priv_usb_raise_irq(uc);
  s_host_substate = (uint8_t)k_sub_wait_ack;
  s_host_wait     = 0U;
}

RA8_INTERNAL static void internal_host_step_wait_ack(void)
{
  if (priv_host_take_ccpl()) {
    s_host_substate = (uint8_t)k_sub_next;
    s_host_wait     = 0U;
    return;
  }
  s_host_wait++;
  if (s_host_wait > (uint32_t)k_usb_step_timeout) {
    s_host_substate = (uint8_t)k_sub_next; /* device may auto-ack; move on. */
    s_host_wait     = 0U;
  }
}

RA8_INTERNAL static uint32_t internal_host_script_len(void)
{
  return (uint32_t)(sizeof(s_k_enum_script) / sizeof(s_k_enum_script[0]));
}

void priv_host_mark_configured(uc_engine* uc)
{
  s_usb.dvsq = (uint16_t)k_ra8_dvsq_configured;
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_dvst);
  priv_usb_raise_irq(uc);
  if (!s_configured) {
    priv_usb_log_line("SET_CONFIGURATION done: DVSQ -> Configured");
  }
}

RA8_INTERNAL static void internal_host_step_next(uc_engine* uc, const usb_setup_step_t* s)
{
  if (s->b_request == (uint8_t)k_usb_req_set_config) {
    priv_host_mark_configured(uc);
  }
  s_host_step++;
  s_host_substate = (uint8_t)k_sub_deliver;
  s_host_wait     = 0U;
  if (s_host_step >= internal_host_script_len()) {
    s_host_phase = (uint8_t)k_phase_configured;
    s_host_wait  = 0U;
  }
}

void priv_host_run_setup_phase(uc_engine* uc)
{
  if (s_host_step >= internal_host_script_len()) {
    s_host_phase = (uint8_t)k_phase_configured;
    return;
  }
  const usb_setup_step_t* s = &s_k_enum_script[s_host_step];
  switch ((usb_host_sub_t)s_host_substate) {
    case k_sub_deliver:
      internal_host_step_deliver(uc, s);
      break;
    case k_sub_wait_in:
      internal_host_step_wait_in();
      break;
    case k_sub_status:
      internal_host_step_status(uc);
      break;
    case k_sub_wait_ack:
      internal_host_step_wait_ack();
      break;
    case k_sub_next:
    default:
      internal_host_step_next(uc, s);
      break;
  }
}

void priv_host_run_idle_phase(uc_engine* uc)
{
  if (!priv_host_device_attached()) {
    return;
  }
  priv_usb_log_line("device pull-up detected (SYSCFG.DPRPU) -> bus reset");
  s_usb.dvsq = (uint16_t)k_ra8_dvsq_default;
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_dvst);
  priv_usb_raise_irq(uc);
  s_host_phase = (uint8_t)k_phase_reset;
  s_host_wait  = 0U;
}

void priv_host_run_reset_phase(uc_engine* uc)
{
  /* Keep DVSQ at Default and re-raise DVST so the bridge's busreset_rearm runs
   * (it re-defaults DCPCFG/DCPMAXP/PIPECTR/INTENB0 -- HUM Ch 36.3). */
  s_usb.dvsq = (uint16_t)k_ra8_dvsq_default;
  if (s_host_wait == 0U) {
    priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_dvst);
    priv_usb_raise_irq(uc);
  }
  s_host_wait++;
  if (s_host_wait >= (uint32_t)k_usb_reset_settle) {
    s_host_phase    = (uint8_t)k_phase_setup;
    s_host_step     = 0U;
    s_host_substate = (uint8_t)k_sub_deliver;
    s_host_wait     = 0U;
  }
}

RA8_INTERNAL static void internal_host_echo_send_out(uc_engine* uc)
{
  const uint32_t remaining = s_echo_out_len - s_echo_out_sent;
  const uint32_t chunk     = (remaining < (uint32_t)k_usb_pipe_mps) ? remaining : k_usb_pipe_mps;
  usb_out_buf_t* b         = &s_usb.pipe_out[k_usb_bulk_out_pipe];
  (void)memcpy(b->data, &s_echo_out[s_echo_out_sent], chunk);
  b->len   = (uint16_t)chunk;
  b->rd    = 0U;
  b->ready = true;
  /* BRDYSTS bit for the OUT pipe: an OUT packet has landed (HUM Ch 36.2.12). */
  const uint32_t w = internal_usb_word((uint64_t)k_ra8_usb_off_brdysts);
  s_usb.reg[w]     = (uint16_t)(s_usb.reg[w] | (uint16_t)(1U << k_usb_bulk_out_pipe));
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_brdy);
  s_echo_out_sent += chunk;
  priv_usb_log_count("bulk OUT: delivered to data pipe", (unsigned)chunk);
  priv_usb_raise_irq(uc);
}

void priv_host_echo_read_in(uc_engine* uc)
{
  usb_in_buf_t* b = &s_usb.pipe_in[k_usb_bulk_in_pipe];
  if (b->valid && (b->len > 0U)) {
    if (s_dev_class == (uint8_t)k_usb_class_hid) {
      internal_usb_hid_decode_report(b->data, b->len); /* interrupt-IN mouse report. */
    } else {
      s_echo_in_got += b->len;
      priv_usb_log_count("bulk IN: read echoed bytes from data pipe", (unsigned)b->len);
    }
    b->len   = 0U;
    b->valid = false;
    /* Acknowledge the IN transfer (BEMP) so the device can queue the next. */
    const uint32_t w = internal_usb_word((uint64_t)k_ra8_usb_off_bempsts);
    s_usb.reg[w]     = (uint16_t)(s_usb.reg[w] | (uint16_t)(1U << k_usb_bulk_in_pipe));
    priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_bemp);
    priv_usb_raise_irq(uc);
  } else if (b->valid) {
    b->valid = false; /* drained ZLP terminator. */
  }
}
 
/* =============================================================================
 * MSC Bulk-Only Transport host -- drives SCSI against the device's RAM disk so
 * usb_msc_device actually serves storage (CBW -> data -> CSW per command).
 * =============================================================================
 */

typedef enum : uint8_t {
  k_msc_send = 0U, 
  k_msc_data = 1U, 
  k_msc_csw  = 2U, 
  k_msc_done = 3U, 
} msc_phase_t;

typedef enum : uint8_t {
  k_msc_cmd_inquiry       = 0U, 
  k_msc_cmd_read_capacity = 1U, 
  k_msc_cmd_read10        = 2U, 
} msc_script_cmd_t;

typedef enum : uint32_t {
  k_msc_cbw_len   = 31U,   
  k_msc_csw_len   = 13U,   
  k_msc_flag_in   = 0x80U, 
  k_msc_settle    = 4U,    
  k_msc_cmd_count = 3U,    
} msc_const_t;
 
static uint8_t  s_msc_phase;      
static uint8_t  s_msc_cmd;        
static uint32_t s_msc_tag;        
static uint32_t s_msc_data_len;   
static uint32_t s_msc_data_got;   
static uint32_t s_msc_wait;       
uint32_t        s_msc_blocks;     
uint32_t        s_msc_block_len;  
uint32_t        s_msc_read_ok;    
bool            s_msc_inquiry_ok; 

RA8_INTERNAL static void
internal_host_msc_build_cdb(uint8_t cmd, uint8_t* cdb, uint8_t* cdb_len, uint32_t* data_len)
{
  for (uint32_t i = 0U; i < 16U; i++) {
    cdb[i] = 0U;
  }
  switch ((msc_script_cmd_t)cmd) {
    case k_msc_cmd_inquiry: /* INQUIRY: standard data, 36-byte allocation. */
      cdb[0]    = (uint8_t)k_scsi_inquiry;
      cdb[4]    = (uint8_t)k_inquiry_len;
      *cdb_len  = 6U;
      *data_len = (uint32_t)k_inquiry_len;
      break;
    case k_msc_cmd_read_capacity: /* READ CAPACITY (10): last LBA + block size. */
      cdb[0]    = (uint8_t)k_scsi_read_capacity;
      *cdb_len  = (uint8_t)k_cdb10_len;
      *data_len = 8U;
      break;
    case k_msc_cmd_read10: /* READ (10): LBA 0, one block (512 bytes). */
    default:
      cdb[0]    = (uint8_t)k_scsi_read10;
      cdb[8]    = 1U; /* transfer length = 1 block (big-endian low byte). */
      *cdb_len  = (uint8_t)k_cdb10_len;
      *data_len = (uint32_t)k_sector_bytes;
      break;
  }
}

RA8_INTERNAL static void internal_host_msc_send_cbw(uc_engine* uc)
{
  uint8_t  cdb[16];
  uint8_t  cdb_len  = 0U;
  uint32_t data_len = 0U;
  internal_host_msc_build_cdb(s_msc_cmd, cdb, &cdb_len, &data_len);
  s_msc_data_len = data_len;
  s_msc_data_got = 0U;
  s_msc_tag++;
 
  usb_out_buf_t* b = &s_usb.pipe_out[k_usb_bulk_out_pipe];
  uint8_t*       d = b->data;
  d[0]             = (uint8_t)'U'; /* dCBWSignature 'USBC' (LE 0x43425355). */
  d[1]             = (uint8_t)'S';
  d[2]             = (uint8_t)'B';
  d[3]             = (uint8_t)'C';
  /* dCBWTag / dCBWDataTransferLength are little-endian u32 (USB MSC BOT 5.1). */
  d[k_cbw_tag_off + k_le_lane_b0] = (uint8_t)(s_msc_tag & (uint32_t)k_usb_byte_mask);
  d[k_cbw_tag_off + k_le_lane_b1] = (uint8_t)((s_msc_tag >> 8) & (uint32_t)k_usb_byte_mask);
  d[k_cbw_tag_off + k_le_lane_b2] = (uint8_t)((s_msc_tag >> 16) & (uint32_t)k_usb_byte_mask);
  d[k_cbw_tag_off + k_le_lane_b3] =
    (uint8_t)((s_msc_tag >> (uint32_t)k_usb_shift24) & (uint32_t)k_usb_byte_mask);
  d[k_cbw_dtl_off + k_le_lane_b0] = (uint8_t)(data_len & (uint32_t)k_usb_byte_mask);
  d[k_cbw_dtl_off + k_le_lane_b1] = (uint8_t)((data_len >> 8) & (uint32_t)k_usb_byte_mask);
  d[k_cbw_dtl_off + k_le_lane_b2] = (uint8_t)((data_len >> 16) & (uint32_t)k_usb_byte_mask);
  d[k_cbw_dtl_off + k_le_lane_b3] =
    (uint8_t)((data_len >> (uint32_t)k_usb_shift24) & (uint32_t)k_usb_byte_mask);
  d[k_cbw_flags_off]  = (uint8_t)k_msc_flag_in; /* all scripted commands read. */
  d[k_cbw_lun_off]    = 0U;                     /* LUN 0.                      */
  d[k_cbw_cdblen_off] = cdb_len;
  for (uint32_t i = 0U; i < 16U; i++) {
    d[k_cbw_cdb_off + i] = cdb[i];
  }
  b->len           = (uint16_t)k_msc_cbw_len;
  b->rd            = 0U;
  b->ready         = true;
  const uint32_t w = internal_usb_word((uint64_t)k_ra8_usb_off_brdysts);
  s_usb.reg[w]     = (uint16_t)(s_usb.reg[w] | (uint16_t)(1U << k_usb_bulk_out_pipe));
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_brdy);
  priv_usb_raise_irq(uc);
}

RA8_INTERNAL static uint16_t internal_host_msc_take_in(uc_engine* uc, uint8_t* out, uint16_t cap)
{
  usb_in_buf_t* b = &s_usb.pipe_in[k_usb_bulk_in_pipe];
  if (!b->valid) {
    return 0U;
  }
  const uint16_t n = (b->len < cap) ? b->len : cap;
  for (uint16_t i = 0U; i < n; i++) {
    out[i] = b->data[i];
  }
  b->len           = 0U;
  b->valid         = false;
  const uint32_t w = internal_usb_word((uint64_t)k_ra8_usb_off_bempsts);
  s_usb.reg[w]     = (uint16_t)(s_usb.reg[w] | (uint16_t)(1U << k_usb_bulk_in_pipe));
  priv_usb_intsts0_set((uint8_t)k_ra8_int0_bit_bemp);
  priv_usb_raise_irq(uc);
  return n;
}

RA8_INTERNAL static void internal_host_msc_parse_capacity(const uint8_t* d, uint16_t n)
{
  if (n < 8U) {
    return;
  }
  /* Both parameter-block fields are big-endian u32 (SCSI READ CAPACITY(10)). */
  const uint32_t last_lba =
    ((uint32_t)d[k_cap10_last_lba_off + k_be_lane_b3] << (uint32_t)k_usb_shift24) |
    ((uint32_t)d[k_cap10_last_lba_off + k_be_lane_b2] << 16) |
    ((uint32_t)d[k_cap10_last_lba_off + k_be_lane_b1] << 8) |
    (uint32_t)d[k_cap10_last_lba_off + k_be_lane_b0];
  s_msc_block_len = ((uint32_t)d[k_cap10_blocklen_off + k_be_lane_b3] << (uint32_t)k_usb_shift24) |
                    ((uint32_t)d[k_cap10_blocklen_off + k_be_lane_b2] << 16) |
                    ((uint32_t)d[k_cap10_blocklen_off + k_be_lane_b1] << 8) |
                    (uint32_t)d[k_cap10_blocklen_off + k_be_lane_b0];
  s_msc_blocks    = last_lba + 1U;
}

RA8_INTERNAL static void internal_host_msc_phase_send(uc_engine* uc)
{
  if (s_msc_cmd >= (uint8_t)k_msc_cmd_count) {
    s_msc_phase = (uint8_t)k_msc_done;
    return;
  }
  internal_host_msc_send_cbw(uc);
  s_msc_phase = (uint8_t)k_msc_data;
  s_msc_wait  = 0U;
}

RA8_INTERNAL static void internal_host_msc_record_data(const uint8_t* d, uint16_t n)
{
  switch ((msc_script_cmd_t)s_msc_cmd) {
    case k_msc_cmd_read_capacity:
      internal_host_msc_parse_capacity(d, n);
      break;
    case k_msc_cmd_inquiry:
      s_msc_inquiry_ok = true;
      break;
    case k_msc_cmd_read10:
      s_msc_read_ok += n;
      break;
    default:
      break;
  }
}

RA8_INTERNAL static void internal_host_msc_phase_data(uc_engine* uc)
{
  uint8_t        buf[k_usb_in_cap];
  const uint16_t n = internal_host_msc_take_in(uc, buf, (uint16_t)sizeof(buf));
  if (n == 0U) {
    s_msc_wait++;
  } else {
    internal_host_msc_record_data(buf, n);
    s_msc_data_got += n;
    s_msc_wait = 0U;
  }
  if ((s_msc_data_got >= s_msc_data_len) || (s_msc_wait > (uint32_t)k_usb_step_timeout)) {
    s_msc_phase = (uint8_t)k_msc_csw;
    s_msc_wait  = 0U;
  }
}

RA8_INTERNAL static void internal_host_msc_phase_csw(uc_engine* uc)
{
  uint8_t        buf[k_usb_in_cap];
  const uint16_t n = internal_host_msc_take_in(uc, buf, (uint16_t)sizeof(buf));
  if ((n >= (uint16_t)k_msc_csw_len) || (s_msc_wait > (uint32_t)k_usb_step_timeout)) {
    s_msc_cmd++;
    s_msc_phase = (uint8_t)k_msc_send;
    s_msc_wait  = 0U;
  } else {
    s_msc_wait++;
  }
}

RA8_INTERNAL static void internal_host_msc_drive(uc_engine* uc)
{
  switch ((msc_phase_t)s_msc_phase) {
    case k_msc_send:
      internal_host_msc_phase_send(uc);
      break;
    case k_msc_data:
      internal_host_msc_phase_data(uc);
      break;
    case k_msc_csw:
      internal_host_msc_phase_csw(uc);
      break;
    case k_msc_done:
    default:
      break;
  }
}

void priv_host_run_configured_phase(uc_engine* uc)
{
  if (s_dev_class == (uint8_t)k_usb_class_msc) {
    internal_host_msc_drive(uc); /* run the BOT/SCSI script against the RAM disk. */
    return;
  }
  priv_host_echo_read_in(uc);
  if (s_dev_class == (uint8_t)k_usb_class_hid) {
    return; /* keep polling the HID interrupt-IN pipe; reports keep flowing. */
  }
  if (s_echo_out_len == 0U) {
    s_host_phase = (uint8_t)k_phase_done;
    return;
  }
  /* Pace one OUT packet, then let the device echo it back before the next. */
  if (s_echo_out_sent < s_echo_out_len) {
    if (s_host_wait == 0U) {
      internal_host_echo_send_out(uc);
    }
    s_host_wait++;
    if (s_host_wait >= (uint32_t)k_usb_reset_settle) {
      s_host_wait = 0U;
    }
    return;
  }
  /* All OUT bytes sent; drain the tail echo for a settle window, then finish. */
  s_host_wait++;
  if (s_host_wait >= (uint32_t)k_usb_post_cfg_idle) {
    s_host_phase = (uint8_t)k_phase_done;
  }
}