emu_usbh_seam.c

Go to the documentation of this file.

 
#include "emu_usbh_seam.h"
 
#include <stdio.h>
#include <string.h>
 
#include "emu_elf.h"
#include "emu_exc.h"
#include "emu_host_io_internal.h"
#include "emu_memory_access.h"
#include "emu_trace.h"

typedef enum : uint32_t {
  k_ra8_err_no_data  = 0x10AU, 
  k_ra8_err_inval_st = 0x104U, 
} usbh_err_code_t;
 
/* ============================================================================
 * Virtual USB host-mode device: a HID boot keyboard behind the ra8_usb_host_*
 * seam.
 *
 * board_usb.c models the USBFS controller in DEVICE mode (a virtual host drives
 * the firmware's device stack). The inverse case -- the firmware acting as USB
 * HOST -- drives the USBHS controller (0x40351000, unmodelled) through the
 * first-party `ra8_usb_host_*` primitives, and with no peer the control
 * transfer wedges (SUREQ never acked -> k_ra8_err_busy). Rather than model a
 * second controller register-by-register, seam those primitives the same way
 * ra8_eth_* is seamed to a virtual net peer (the register model "cannot
 * satisfy" that sequence either): present a virtual boot keyboard that answers
 * chapter-9 enumeration and streams interrupt-IN reports. This lets a host
 * example (usb_host_keyboard) enumerate + read reports end to end with no
 * hardware -- validating the host stack's control/data logic, not silicon
 * timing.
 * ==========================================================================*/

typedef enum : uint16_t {
  k_vkbd_breq_get_descriptor = 0x06U, 
  k_vkbd_dt_device           = 0x01U, 
  k_vkbd_dt_config           = 0x02U, 
  k_vkbd_dt_string           = 0x03U, 
  k_vkbd_dt_hid_report       = 0x22U, 
  k_vkbd_lnst_attached       = 0x02U, 
  k_vkbd_report_len          = 8U,    
  k_vkbd_num_keys            = 5U,    
  k_vkbd_dev_desc_len        = 18U,   
  k_vkbd_cfg_desc_len        = 34U,   
  k_vkbd_stop_reports        = 8U,    
} vkbd_const_t;

static const uint8_t s_k_vkbd_device_desc[k_vkbd_dev_desc_len] = {
  0x12,
  0x01,
  0x00,
  0x02,
  0x00,
  0x00,
  0x00,
  0x40, /* len,DEVICE,bcdUSB2.00,class0,MPS64 */
  0x6A,
  0x1A,
  0x88,
  0x42,
  0x00,
  0x01,
  0x00,
  0x00, /* idVendor 0x1A6A, idProduct 0x4288 */
  0x00,
  0x01, /* bcdDevice, iM/iP/iS=0, 1 config */
};

static const uint8_t s_k_vkbd_config_desc[k_vkbd_cfg_desc_len] = {
  0x09, 0x02, 0x22, 0x00, 0x01, 0x01, 0x00, 0xA0, 0x32, /* CONFIG: wTotalLen 34, 1 iface */
  0x09, 0x04, 0x00, 0x00, 0x01, 0x03, 0x01, 0x01, 0x00, /* IFACE: HID, boot, keyboard    */
  0x09, 0x21, 0x11, 0x01, 0x00, 0x01, 0x22, 0x3F, 0x00, /* HID: report desc len 0x3F     */
  0x07, 0x05, 0x81, 0x03, 0x40, 0x00, 0x01,             /* EP1 IN, interrupt, MPS64, 1ms
                                               */
};

static const uint8_t s_k_vkbd_report_desc[63] = {
  0x05, 0x01, 0x09, 0x06, 0xA1, 0x01, 0x05, 0x07, 0x19, 0xE0, 0x29, 0xE7, 0x15, 0x00, 0x25, 0x01,
  0x75, 0x01, 0x95, 0x08, 0x81, 0x02, 0x95, 0x01, 0x75, 0x08, 0x81, 0x01, 0x95, 0x05, 0x75, 0x01,
  0x05, 0x08, 0x19, 0x01, 0x29, 0x05, 0x91, 0x02, 0x95, 0x01, 0x75, 0x03, 0x91, 0x01, 0x95, 0x06,
  0x75, 0x08, 0x15, 0x00, 0x25, 0x65, 0x05, 0x07, 0x19, 0x00, 0x29, 0x65, 0x81, 0x00, 0xC0,
};

typedef enum : uint8_t {
  k_vkbd_key_r = 0x15U, 
  k_vkbd_key_a = 0x04U, 
  k_vkbd_key_8 = 0x25U, 
  k_vkbd_key_d = 0x07U, 
  k_vkbd_key_2 = 0x1FU, 
} vkbd_keycode_t;

static const uint8_t s_k_vkbd_keycodes[k_vkbd_num_keys] = {k_vkbd_key_r,
                                                           k_vkbd_key_a,
                                                           k_vkbd_key_8,
                                                           k_vkbd_key_d,
                                                           k_vkbd_key_2};
 
static uint8_t  s_vkbd_seq           = 0U; 
static uint32_t s_vkbd_ctrl_serviced = 0U; 
static uint32_t s_vkbd_reports_sent  = 0U; 

RA8_INTERNAL static uint32_t internal_usbh_arg5(uc_engine* uc)
{
  uint32_t sp = 0U;
  uint32_t p  = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_SP, &sp);
  (void)emu_mem_read(uc, (uint64_t)sp, &p, sizeof(p));
  return p;
}

RA8_INTERNAL static void
internal_on_usbh_ok(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}

RA8_INTERNAL static void
internal_on_usbh_line_state(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  eth_hook_return(uc, (uint32_t)k_vkbd_lnst_attached);
}

RA8_INTERNAL static void
internal_on_usbh_control_xfer(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  uint32_t setup_ptr = 0U;
  uint32_t data_ptr  = 0U;
  uint32_t data_len  = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_R1, &setup_ptr);
  (void)uc_reg_read(uc, UC_ARM_REG_R2, &data_ptr);
  (void)uc_reg_read(uc, UC_ARM_REG_R3, &data_len);
  const uint32_t out_ptr = internal_usbh_arg5(uc);
 
  uint8_t s[8] = {};
  (void)emu_mem_read(uc, (uint64_t)setup_ptr, s, sizeof(s));
  const uint8_t  b_request = s[1];
  const uint8_t  desc_type = s[3]; /* wValue high byte = descriptor type. */
  const uint8_t* src       = nullptr;
  uint16_t       src_len   = 0U;
  if (b_request == (uint8_t)k_vkbd_breq_get_descriptor) {
    if (desc_type == (uint8_t)k_vkbd_dt_device) {
      src     = s_k_vkbd_device_desc;
      src_len = (uint16_t)k_vkbd_dev_desc_len;
    } else if (desc_type == (uint8_t)k_vkbd_dt_config) {
      src     = s_k_vkbd_config_desc;
      src_len = (uint16_t)k_vkbd_cfg_desc_len;
    } else if (desc_type == (uint8_t)k_vkbd_dt_hid_report) {
      src     = s_k_vkbd_report_desc;
      src_len = (uint16_t)sizeof(s_k_vkbd_report_desc);
    }
  }
  uint16_t n = 0U;
  if ((src != nullptr) && (data_ptr != 0U)) {
    n = (src_len < (uint16_t)data_len) ? src_len : (uint16_t)data_len;
    (void)emu_mem_write(uc, (uint64_t)data_ptr, src, n);
  }
  /* No-data control writes (SET_ADDRESS / SET_CONFIGURATION / SET_IDLE /
   * SET_PROTOCOL) just leave n = 0; the host treats that as a successful ack.
   */
  if (out_ptr != 0U) {
    (void)emu_mem_write(uc, (uint64_t)out_ptr, &n, sizeof(n));
  }
  s_vkbd_ctrl_serviced++;
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}

RA8_INTERNAL static void
internal_on_usbh_bulk_in(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  uint32_t buf     = 0U;
  uint32_t max_len = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_R2, &buf);
  (void)uc_reg_read(uc, UC_ARM_REG_R3, &max_len);
  const uint32_t out_ptr = internal_usbh_arg5(uc);
  /* Boot-keyboard report: [seq][reserved 0][keycodes R A 8 D 2][0]. The host
   * ignores byte 0 and pattern-checks bytes 1.. -- it streams "RA8D2". */
  uint8_t rep[k_vkbd_report_len] = {};
  rep[0]                         = s_vkbd_seq++;
  for (uint32_t i = 0U; i < (uint32_t)k_vkbd_num_keys; i++) {
    rep[2U + i] = s_k_vkbd_keycodes[i];
  }
  uint16_t n = (uint16_t)k_vkbd_report_len;
  if ((uint32_t)n > max_len) {
    n = (uint16_t)max_len;
  }
  if (buf != 0U) {
    (void)emu_mem_write(uc, (uint64_t)buf, rep, n);
  }
  if (out_ptr != 0U) {
    (void)emu_mem_write(uc, (uint64_t)out_ptr, &n, sizeof(n));
  }
  s_vkbd_reports_sent++;
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}
 
/* ----------------------------------------------------------------------------
 * Virtual USB host-mode MSC device: a read-only FAT16 disk whose one file
 * MRAM.BIN is the 1 MiB MRAM code window. Seams the first-party
 * `ra8_usb_hmsc_*` class API (one level above the BOT/SCSI bulk transport) so a
 * host MSC app (usb_host_msc_browse) enumerates, READ_CAPACITYs, mounts the
 * FAT16, browses the root directory, and content-verifies MRAM.BIN -- all with
 * no peer device. The boot/FAT/root sectors are a byte-identical replica of the
 * device's selftest_fat_fill_sector; the data region is read live from emulated
 * MRAM, so it matches the host's own MRAM compare byte-for-byte.
 * --------------------------------------------------------------------------*/

typedef enum : uint32_t {
  k_vmsc_block_size     = 512U,        
  k_vmsc_total_sectors  = 4146U,       
  k_vmsc_root_lba       = 18U,         
  k_vmsc_data_lba       = 50U,         
  k_vmsc_first_cluster  = 2U,          
  k_vmsc_last_mram_clus = 2049U,       
  k_vmsc_entries_per_fs = 256U,        
  k_vmsc_overlay_slots  = 64U,         
  k_vmsc_mram_base      = 0x02000000U, 
  k_vmsc_fat_entry0     = 0xFFF8U,     
  k_vmsc_fat_eoc        = 0xFFFFU,     
  k_vmsc_file_bytes     = 0x00100000U, 
  k_vmsc_volid          = 0x52A8D20AU, 
} vmsc_const_t;

typedef enum : uint32_t {
  k_bpb_shift8         = 8U,    
  k_bpb_shift16        = 16U,   
  k_bpb_shift24        = 24U,   
  k_bpb_jmp0           = 0xEBU, 
  k_bpb_jmp1           = 0x3CU, 
  k_bpb_jmp2           = 0x90U, 
  k_bpb_off_oem        = 3U,    
  k_bpb_off_bytspersec = 11U,   
  k_bpb_off_secperclus = 13U,   
  k_bpb_off_rsvdseccnt = 14U,   
  k_bpb_off_numfats    = 16U,   
  k_bpb_off_rootentcnt = 17U,   
  k_bpb_off_totsec16   = 19U,   
  k_bpb_off_media      = 21U,   
  k_bpb_off_fatsz16    = 22U,   
  k_bpb_off_secpertrk  = 24U,   
  k_bpb_off_numheads   = 26U,   
  k_bpb_off_drvnum     = 36U,   
  k_bpb_off_bootsig    = 38U,   
  k_bpb_off_volid      = 39U,   
  k_bpb_off_vollab     = 43U,   
  k_bpb_off_filsystype = 54U,   
  k_bpb_off_sig0       = 510U,  
  k_bpb_off_sig1       = 511U,  
  k_bpb_secperclus_1   = 1U,    
  k_bpb_rsvdseccnt_1   = 1U,    
  k_bpb_numfats_1      = 1U,    
  k_bpb_rootentcnt_512 = 512U,  
  k_bpb_media_f8       = 0xF8U, 
  k_bpb_fatsz16_17     = 17U,   
  k_bpb_secpertrk_32   = 32U,   
  k_bpb_numheads_16    = 16U,   
  k_bpb_drvnum_80      = 0x80U, 
  k_bpb_bootsig_29     = 0x29U, 
  k_bpb_sig0_55        = 0x55U, 
  k_bpb_sig1_aa        = 0xAAU, 
  k_dir_off_attr       = 11U,   
  k_dir_off_entry      = 32U,   
  k_dir_off_fstcluslo  = 26U,   
  k_dir_off_filesize   = 28U,   
  k_dir_attr_vollabel  = 0x08U, 
  k_dir_attr_readonly  = 0x01U, 
} vmsc_bpb_t;
 
static const uint8_t s_k_vmsc_oem[8]    = {'R', 'A', '8', 'D', '2', 'F', 'W', ' '};
static const uint8_t s_k_vmsc_label[11] = {'R', 'A', '8', 'D', '2', ' ', 'M', 'R', 'A', 'M', ' '};
static const uint8_t s_k_vmsc_fstype[8] = {'F', 'A', 'T', '1', '6', ' ', ' ', ' '};
static const uint8_t s_k_vmsc_fname[11] = {'M', 'R', 'A', 'M', ' ', ' ', ' ', ' ', 'B', 'I', 'N'};

static bool s_vmsc_write_seen = false;

static bool s_vmsc_writable = false;

typedef struct {
  uint32_t lba;                     
  bool     valid;                   
  uint8_t  data[k_vmsc_block_size]; 
} vmsc_overlay_t;

static vmsc_overlay_t s_vmsc_overlay[k_vmsc_overlay_slots];

RA8_INTERNAL static bool internal_vmsc_overlay_get(uint32_t lba, uint8_t* out)
{
  for (uint32_t i = 0U; i < (uint32_t)(sizeof(s_vmsc_overlay) / sizeof(s_vmsc_overlay[0])); i++) {
    if (s_vmsc_overlay[i].valid && (s_vmsc_overlay[i].lba == lba)) {
      (void)memcpy(out, s_vmsc_overlay[i].data, (size_t)k_vmsc_block_size);
      return true;
    }
  }
  return false;
}

RA8_INTERNAL static void internal_vmsc_overlay_put(uint32_t lba, const uint8_t* in)
{
  const uint32_t slots = (uint32_t)(sizeof(s_vmsc_overlay) / sizeof(s_vmsc_overlay[0]));
  for (uint32_t i = 0U; i < slots; i++) {
    if (s_vmsc_overlay[i].valid && (s_vmsc_overlay[i].lba == lba)) {
      (void)memcpy(s_vmsc_overlay[i].data, in, (size_t)k_vmsc_block_size);
      return;
    }
  }
  for (uint32_t i = 0U; i < slots; i++) {
    if (!s_vmsc_overlay[i].valid) {
      s_vmsc_overlay[i].lba   = lba;
      s_vmsc_overlay[i].valid = true;
      (void)memcpy(s_vmsc_overlay[i].data, in, (size_t)k_vmsc_block_size);
      return;
    }
  }
}

RA8_INTERNAL static void internal_vmsc_put16(uint8_t* p, uint16_t v)
{
  p[0] = (uint8_t)(v & (uint16_t)k_byte_mask);
  p[1] = (uint8_t)((v >> (uint16_t)k_bpb_shift8) & (uint16_t)k_byte_mask);
}

RA8_INTERNAL static void internal_vmsc_put32(uint8_t* p, uint32_t v)
{
  p[0] = (uint8_t)(v & (uint32_t)k_byte_mask);
  p[1] = (uint8_t)((v >> (uint32_t)k_bpb_shift8) & (uint32_t)k_byte_mask);
  p[2] = (uint8_t)((v >> (uint32_t)k_bpb_shift16) & (uint32_t)k_byte_mask);
  p[3] = (uint8_t)((v >> (uint32_t)k_bpb_shift24) & (uint32_t)k_byte_mask);
}

RA8_INTERNAL static void internal_vmsc_fill_boot(uint8_t* out)
{
  out[0] = (uint8_t)k_bpb_jmp0;
  out[1] = (uint8_t)k_bpb_jmp1;
  out[2] = (uint8_t)k_bpb_jmp2; /* jmp + nop */
  (void)memcpy(&out[k_bpb_off_oem], s_k_vmsc_oem, sizeof(s_k_vmsc_oem));
  internal_vmsc_put16(&out[k_bpb_off_bytspersec], (uint16_t)k_vmsc_block_size);
  out[k_bpb_off_secperclus] = (uint8_t)k_bpb_secperclus_1; /* sectors/cluster */
  internal_vmsc_put16(&out[k_bpb_off_rsvdseccnt],
                      (uint16_t)k_bpb_rsvdseccnt_1); /* reserved sectors */
  out[k_bpb_off_numfats] = (uint8_t)k_bpb_numfats_1; /* number of FATs   */
  internal_vmsc_put16(&out[k_bpb_off_rootentcnt],
                      (uint16_t)k_bpb_rootentcnt_512); /* root entries */
  internal_vmsc_put16(&out[k_bpb_off_totsec16], (uint16_t)k_vmsc_total_sectors);
  out[k_bpb_off_media] = (uint8_t)k_bpb_media_f8;                           /* media descriptor */
  internal_vmsc_put16(&out[k_bpb_off_fatsz16], (uint16_t)k_bpb_fatsz16_17); /* sectors per FAT  */
  internal_vmsc_put16(&out[k_bpb_off_secpertrk],
                      (uint16_t)k_bpb_secpertrk_32); /* sectors per track */
  internal_vmsc_put16(&out[k_bpb_off_numheads], (uint16_t)k_bpb_numheads_16); /* heads          */
  out[k_bpb_off_drvnum]  = (uint8_t)k_bpb_drvnum_80;                          /* drive number   */
  out[k_bpb_off_bootsig] = (uint8_t)k_bpb_bootsig_29;                         /* boot signature */
  internal_vmsc_put32(&out[k_bpb_off_volid], (uint32_t)k_vmsc_volid);
  (void)memcpy(&out[k_bpb_off_vollab], s_k_vmsc_label, sizeof(s_k_vmsc_label));
  (void)memcpy(&out[k_bpb_off_filsystype], s_k_vmsc_fstype, sizeof(s_k_vmsc_fstype));
  out[k_bpb_off_sig0] = (uint8_t)k_bpb_sig0_55;
  out[k_bpb_off_sig1] = (uint8_t)k_bpb_sig1_aa;
}

RA8_INTERNAL static void internal_vmsc_fill_fat(uint32_t fat_sector, uint8_t* out)
{
  const uint32_t first = fat_sector * (uint32_t)k_vmsc_entries_per_fs;
  for (uint32_t j = 0U; j < (uint32_t)k_vmsc_entries_per_fs; j++) {
    const uint32_t entry = first + j;
    uint16_t       value = 0U;
    if (entry == 0U) {
      value = (uint16_t)k_vmsc_fat_entry0;
    } else if ((entry == 1U) || (entry == (uint32_t)k_vmsc_last_mram_clus)) {
      /* Entry 1 is the reserved media/EOC marker and the last cluster ends the
       * chain -- both hold the same EOC word. */
      value = (uint16_t)k_vmsc_fat_eoc;
    } else if (entry < (uint32_t)k_vmsc_last_mram_clus) {
      value = (uint16_t)(entry + 1U);
    }
    internal_vmsc_put16(&out[(size_t)j * 2U], value);
  }
}

RA8_INTERNAL static void internal_vmsc_fill_root(uint32_t root_sector, uint8_t* out)
{
  if (root_sector != 0U) {
    return;
  }
  (void)memcpy(&out[0], s_k_vmsc_label, sizeof(s_k_vmsc_label));
  out[k_dir_off_attr] = (uint8_t)k_dir_attr_vollabel; /* volume-label attribute */
  uint8_t* e          = &out[k_dir_off_entry];
  (void)memcpy(e, s_k_vmsc_fname, sizeof(s_k_vmsc_fname));
  e[k_dir_off_attr] = (uint8_t)k_dir_attr_readonly; /* read-only attribute */
  internal_vmsc_put16(&e[k_dir_off_fstcluslo], (uint16_t)k_vmsc_first_cluster);
  internal_vmsc_put32(&e[k_dir_off_filesize], (uint32_t)k_vmsc_file_bytes);
}

RA8_INTERNAL static void internal_vmsc_fill_sector(uc_engine* uc, uint32_t lba, uint8_t* out)
{
  (void)memset(out, 0, (size_t)k_vmsc_block_size);
  if (lba == 0U) {
    internal_vmsc_fill_boot(out);
  } else if (lba < (uint32_t)k_vmsc_root_lba) {
    internal_vmsc_fill_fat(lba - 1U, out);
  } else if (lba < (uint32_t)k_vmsc_data_lba) {
    internal_vmsc_fill_root(lba - (uint32_t)k_vmsc_root_lba, out);
  } else {
    const uint32_t cluster = (lba - (uint32_t)k_vmsc_data_lba) + (uint32_t)k_vmsc_first_cluster;
    if (cluster <= (uint32_t)k_vmsc_last_mram_clus) {
      const uint32_t off = (cluster - (uint32_t)k_vmsc_first_cluster) * (uint32_t)k_vmsc_block_size;
      (void)emu_mem_read(uc,
                         (uint64_t)k_vmsc_mram_base + (uint64_t)off,
                         out,
                         (size_t)k_vmsc_block_size);
    }
  }
}

RA8_INTERNAL static void
internal_on_hmsc_ok(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}

typedef enum : uint32_t {
  k_hmsc_dev_bytes  = 14U,     
  k_hmsc_off_vid    = 10U,     
  k_hmsc_off_pid    = 12U,     
  k_hmsc_bulk_mps   = 64U,     
  k_hmsc_vendor_id  = 0x1A6AU, 
  k_hmsc_product_id = 0x4288U, 
} hmsc_dev_t;

RA8_INTERNAL static void
internal_on_hmsc_enumerate(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  uint32_t dev_ptr = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_R0, &dev_ptr);
  if (dev_ptr != 0U) {
    /* ra8_usb_hmsc_device_t: addr,bin_ep,bout_ep,max_lun,iface,[pad],in_mps,
     * out_mps,vid,pid. */
    uint8_t d[k_hmsc_dev_bytes] = {};
    d[0]                        = 1U;                                     /* device_address      */
    d[1]                        = 1U;                                     /* bulk_in_ep          */
    d[2]                        = 2U;                                     /* bulk_out_ep         */
    internal_vmsc_put16(&d[6], (uint16_t)k_hmsc_bulk_mps);                /* bulk_in_max_packet  */
    internal_vmsc_put16(&d[8], (uint16_t)k_hmsc_bulk_mps);                /* bulk_out_max_packet */
    internal_vmsc_put16(&d[k_hmsc_off_vid], (uint16_t)k_hmsc_vendor_id);  /* vendor_id           */
    internal_vmsc_put16(&d[k_hmsc_off_pid], (uint16_t)k_hmsc_product_id); /* product_id          */
    (void)emu_mem_write(uc, (uint64_t)dev_ptr, d, sizeof(d));
  }
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}

RA8_INTERNAL static void
internal_on_hmsc_read_capacity(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  uint32_t bc_ptr = 0U;
  uint32_t bs_ptr = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_R1, &bc_ptr);
  (void)uc_reg_read(uc, UC_ARM_REG_R2, &bs_ptr);
  const uint32_t block_count = (uint32_t)k_vmsc_total_sectors;
  const uint32_t block_size  = (uint32_t)k_vmsc_block_size;
  if (bc_ptr != 0U) {
    (void)emu_mem_write(uc, (uint64_t)bc_ptr, &block_count, sizeof(block_count));
  }
  if (bs_ptr != 0U) {
    (void)emu_mem_write(uc, (uint64_t)bs_ptr, &block_size, sizeof(block_size));
  }
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}

RA8_INTERNAL static void
internal_on_hmsc_read10(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  uint32_t lba   = 0U;
  uint32_t count = 0U;
  uint32_t buf   = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_R1, &lba);
  (void)uc_reg_read(uc, UC_ARM_REG_R2, &count);
  (void)uc_reg_read(uc, UC_ARM_REG_R3, &buf);
  count &= (uint32_t)k_lo16_mask; /* block_count is a uint16_t argument. */
  for (uint32_t i = 0U; (i < count) && (buf != 0U); i++) {
    uint8_t sec[k_vmsc_block_size];
    if (!internal_vmsc_overlay_get(lba + i, sec)) { /* a host WRITE(10) wins over the synthesis. */
      internal_vmsc_fill_sector(uc, lba + i, sec);
    }
    (void)emu_mem_write(uc,
                        (uint64_t)buf + ((uint64_t)i * (uint64_t)k_vmsc_block_size),
                        sec,
                        sizeof(sec));
  }
  eth_hook_return(uc, 0U); /* k_ra8_ok */
}

RA8_INTERNAL static void
internal_on_hmsc_write10(uc_engine* uc, uint64_t address, uint32_t size, void* user)
{
  (void)address;
  (void)size;
  (void)user;
  if (!s_vmsc_writable) {
    /* Read-only disk (usb_host_msc_browse): reject. This is that app's last
     * step before PASS, so flag it for the host early-stop. */
    s_vmsc_write_seen = true;
    eth_hook_return(uc, (uint32_t)k_ra8_err_inval_st); /* write protected */
    return;
  }
  /* Writable disk (usb_host_file_ops): stash the written sectors in the overlay
   * so the host's read-back sees them, and accept. The write is mid-ladder
   * here, so do NOT trip the write-seen early-stop -- that app stops on its
   * banner. */
  uint32_t lba   = 0U;
  uint32_t count = 0U;
  uint32_t buf   = 0U;
  (void)uc_reg_read(uc, UC_ARM_REG_R1, &lba);
  (void)uc_reg_read(uc, UC_ARM_REG_R2, &count);
  (void)uc_reg_read(uc, UC_ARM_REG_R3, &buf);
  count &= (uint32_t)k_lo16_mask;
  for (uint32_t i = 0U; (i < count) && (buf != 0U); i++) {
    uint8_t sec[k_vmsc_block_size];
    (void)emu_mem_read(uc,
                       (uint64_t)buf + ((uint64_t)i * (uint64_t)k_vmsc_block_size),
                       sec,
                       sizeof(sec));
    internal_vmsc_overlay_put(lba + i, sec);
  }
  eth_hook_return(uc, 0U); /* k_ra8_ok -- write accepted */
}

bool usbh_seam_install(uc_engine* uc, const emu_elf_source_t* elf)
{
  const uint32_t msc = elf_sym_addr(elf, "ra8_usb_hmsc_read10", nullptr);
  if (msc != 0U) {
    /* usb_host_file_ops creates a file (it links fileops_backend_write) -> the
     * virtual disk is writable; usb_host_msc_browse tests a read-only LUN. */
    s_vmsc_writable = (elf_sym_addr(elf, "fileops_backend_write", nullptr) != 0U);
    eth_seam_hook(uc, elf, "ra8_usb_hmsc_init", (void*)internal_on_hmsc_ok);
    eth_seam_hook(uc, elf, "ra8_usb_hmsc_enumerate", (void*)internal_on_hmsc_enumerate);
    eth_seam_hook(uc, elf, "ra8_usb_hmsc_read_capacity", (void*)internal_on_hmsc_read_capacity);
    eth_seam_hook(uc, elf, "ra8_usb_hmsc_read10", (void*)internal_on_hmsc_read10);
    eth_seam_hook(uc, elf, "ra8_usb_hmsc_write10", (void*)internal_on_hmsc_write10);
    eth_seam_hook(uc, elf, "ra8_usb_hmsc_close", (void*)internal_on_hmsc_ok);
    (void)priv_emu_io_errf("  usb-host seam : hmsc=0x%08X (virtual MSC FAT16 "
                           "disk, file MRAM.BIN, %s)\n",
                           msc,
                           s_vmsc_writable ? "read-write" : "read-only");
    return true;
  }
  const uint32_t cx = elf_sym_addr(elf, "ra8_usb_host_control_xfer", nullptr);
  if (cx == 0U) {
    return false; /* not a USB-host-capable firmware -- nothing to seam. */
  }
  eth_seam_hook(uc, elf, "ra8_usb_host_line_state", (void*)internal_on_usbh_line_state);
  eth_seam_hook(uc, elf, "ra8_usb_host_control_xfer", (void*)internal_on_usbh_control_xfer);
  eth_seam_hook(uc, elf, "ra8_usb_host_bulk_in", (void*)internal_on_usbh_bulk_in);
  eth_seam_hook(uc, elf, "ra8_usb_host_bus_reset", (void*)internal_on_usbh_ok);
  eth_seam_hook(uc, elf, "ra8_usb_host_set_uact", (void*)internal_on_usbh_ok);
  eth_seam_hook(uc, elf, "ra8_usb_host_set_target", (void*)internal_on_usbh_ok);
  eth_seam_hook(uc, elf, "ra8_usb_host_pipe_setup", (void*)internal_on_usbh_ok);
  (void)priv_emu_io_errf("  usb-host seam : control=0x%08X (virtual HID boot "
                         "keyboard \"RA8D2\")\n",
                         cx);
  return true;
}

bool emu_usbh_done(void)
{
  return (s_vkbd_reports_sent >= (uint32_t)k_vkbd_stop_reports) || s_vmsc_write_seen;
}