Virtual USB host-mode device seams (see emu_usbh_seam.h). More...

#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"

Include dependency graph for emu_usbh_seam.c:

Data Structures
struct	vmsc_overlay_t
	One overwritten sector of the otherwise-synthesized FAT16 volume. More...

Enumerations
enum	usbh_err_code_t : uint32_t { k_ra8_err_no_data = 0x10AU , k_ra8_err_inval_st = 0x104U }
	ra8_err_t values the virtual devices return to the host stack. More...
enum	vkbd_const_t : 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 }
	bRequest / descriptor-type / sizing constants for the virtual device. More...
enum	vkbd_keycode_t : 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 }
	HID Usage-Table keycodes (Usage Page 0x07) for the typed string. More...
enum	vmsc_const_t : 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 }
	FAT16 geometry + boot/dir layout for the virtual MSC volume. More...
enum	vmsc_bpb_t : 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 }
	FAT16 BPB byte offsets, fixed field values, and store shifts. More...
enum	hmsc_dev_t : 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 }
	ra8_usb_hmsc_device_t field offsets + reported bulk EP packet/VID/PID. More...

Functions
static RA8_INTERNAL uint32_t	internal_usbh_arg5 (uc_engine *uc)
	Read the 5th (stack-passed) argument of an AAPCS call: mem32[SP].
static RA8_INTERNAL void	internal_on_usbh_ok (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on USB host ok for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_usbh_line_state (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on USB host line state for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_usbh_control_xfer (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on USB host control xfer for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_usbh_bulk_in (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on USB host bulk in for the emu USB host seam model.
static RA8_INTERNAL bool	internal_vmsc_overlay_get (uint32_t lba, uint8_t *out)
	Return an overwritten sector if `lba` is in the overlay.
static RA8_INTERNAL void	internal_vmsc_overlay_put (uint32_t lba, const uint8_t *in)
	Record an overwritten sector (update existing slot or take a free one).
static RA8_INTERNAL void	internal_vmsc_put16 (uint8_t *p, uint16_t v)
	Little-endian 16-bit store into a sector buffer.
static RA8_INTERNAL void	internal_vmsc_put32 (uint8_t *p, uint32_t v)
	Little-endian 32-bit store into a sector buffer.
static RA8_INTERNAL void	internal_vmsc_fill_boot (uint8_t *out)
	Synthesize the FAT16 boot sector (BPB), mirroring the device side.
static RA8_INTERNAL void	internal_vmsc_fill_fat (uint32_t fat_sector, uint8_t *out)
	Synthesize one FAT sector: MRAM.BIN chains clusters 2..2049.
static RA8_INTERNAL void	internal_vmsc_fill_root (uint32_t root_sector, uint8_t *out)
	Synthesize root-directory sector 0: volume label + MRAM.BIN entry.
static RA8_INTERNAL void	internal_vmsc_fill_sector (uc_engine uc, uint32_t lba, uint8_t out)
	Fill one 512-byte volume sector (boot / FAT / root / live MRAM data).
static RA8_INTERNAL void	internal_on_hmsc_ok (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on hmsc ok for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_hmsc_enumerate (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on hmsc enumerate for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_hmsc_read_capacity (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on hmsc read capacity for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_hmsc_read10 (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on hmsc read10 for the emu USB host seam model.
static RA8_INTERNAL void	internal_on_hmsc_write10 (uc_engine uc, uint64_t address, uint32_t size, void user)
	Perform on hmsc write10 for the emu USB host seam model.
bool	usbh_seam_install (uc_engine uc, const emu_elf_source_t elf)
	Install the virtual USB host-mode device seam if the host stack is linked.
bool	emu_usbh_done (void)
	Implementation of emu_usbh_done() – the USBH early-stop predicate.

Variables
static const uint8_t	s_k_vkbd_device_desc [k_vkbd_dev_desc_len]
	18-byte DEVICE descriptor: class defined at interface, EP0 MPS 64.
static const uint8_t	s_k_vkbd_config_desc [k_vkbd_cfg_desc_len]
	34-byte CONFIGURATION: 1 HID boot-keyboard iface, 1 interrupt-IN EP1.
static const uint8_t	s_k_vkbd_report_desc [63]
	Standard boot-keyboard HID REPORT descriptor (63 bytes, USB HID 1.11 E.6).
static const uint8_t	s_k_vkbd_keycodes [k_vkbd_num_keys]
	HID Usage-Table keycodes the virtual keyboard "types": R A 8 D 2.
static uint8_t	s_vkbd_seq = 0U
	Rolling report seq (report byte 0).
static uint32_t	s_vkbd_ctrl_serviced = 0U
	Control transfers answered.
static uint32_t	s_vkbd_reports_sent = 0U
	Interrupt-IN reports streamed.
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
	Set once the host attempts a WRITE(10) into the READ-ONLY disk – the last host step before usb_host_msc_browse's PASS (read by the USBH_STOP guard).
static bool	s_vmsc_writable = false
	True when the virtual disk is writable (usb_host_file_ops links fileops_backend_write); else the disk is read-only and WRITE(10) is rejected.
static vmsc_overlay_t	s_vmsc_overlay [k_vmsc_overlay_slots]
	Write overlay for the writable disk (file_ops touches only a handful).

Detailed Description

Virtual USB host-mode device seams (see emu_usbh_seam.h).

The HID boot-keyboard peer for the ra8_usb_host_* primitives and the FAT16 MSC disk peer for the ra8_usb_hmsc_* class API (boot/FAT/root synthesis, the live-MRAM data region, and the small write overlay for the writable variant) – moved verbatim out of the ra8_emulator main translation unit.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file emu_usbh_seam.c.

Enumeration Type Documentation

◆ hmsc_dev_t

enum hmsc_dev_t : uint32_t

ra8_usb_hmsc_device_t field offsets + reported bulk EP packet/VID/PID.

Enumerator
k_hmsc_dev_bytes	Marshalled ra8_usb_hmsc_device_t size.
k_hmsc_off_vid	vid offset in ra8_usb_hmsc_device_t.
k_hmsc_off_pid	pid offset in ra8_usb_hmsc_device_t.
k_hmsc_bulk_mps	Reported bulk-endpoint max packet size.
k_hmsc_vendor_id	Reported USB vendor_id.
k_hmsc_product_id	Reported USB product_id.

Definition at line 630 of file emu_usbh_seam.c.

◆ usbh_err_code_t

enum usbh_err_code_t : uint32_t

ra8_err_t values the virtual devices return to the host stack.

Enumerator
k_ra8_err_no_data	ra8_err_t value: no RX data.
k_ra8_err_inval_st	ra8_err_t value: invalid state.

Definition at line 28 of file emu_usbh_seam.c.

◆ vkbd_const_t

enum vkbd_const_t : uint16_t

bRequest / descriptor-type / sizing constants for the virtual device.

Enumerator
k_vkbd_breq_get_descriptor	Standard GET_DESCRIPTOR bRequest.
k_vkbd_dt_device	DEVICE descriptor (wValue hi byte).
k_vkbd_dt_config	CONFIGURATION descriptor.
k_vkbd_dt_string	STRING descriptor.
k_vkbd_dt_hid_report	HID REPORT descriptor.
k_vkbd_lnst_attached	SYSSTS0.LNST J-state (device on bus).
k_vkbd_report_len	Boot-keyboard input report width.
k_vkbd_num_keys	Keycodes typed ("R A 8 D 2").
k_vkbd_dev_desc_len	DEVICE descriptor length.
k_vkbd_cfg_desc_len	Full CONFIGURATION descriptor length.
k_vkbd_stop_reports	Reports streamed before USB_STOP fires.

Definition at line 53 of file emu_usbh_seam.c.

◆ vkbd_keycode_t

enum vkbd_keycode_t : uint8_t

HID Usage-Table keycodes (Usage Page 0x07) for the typed string.

Enumerator
k_vkbd_key_r	HID usage for 'R'.
k_vkbd_key_a	HID usage for 'A'.
k_vkbd_key_8	HID usage for '8'.
k_vkbd_key_d	HID usage for 'D'.
k_vkbd_key_2	HID usage for '2'.

Definition at line 109 of file emu_usbh_seam.c.

◆ vmsc_bpb_t

enum vmsc_bpb_t : uint32_t

FAT16 BPB byte offsets, fixed field values, and store shifts.

Enumerator
k_bpb_shift8	Byte 1 store shift.
k_bpb_shift16	Byte 2 store shift.
k_bpb_shift24	Byte 3 store shift.
k_bpb_jmp0	BS_jmpBoot[0]: short jump opcode.
k_bpb_jmp1	BS_jmpBoot[1]: jump displacement.
k_bpb_jmp2	BS_jmpBoot[2]: NOP.
k_bpb_off_oem	BS_OEMName offset.
k_bpb_off_bytspersec	BPB_BytsPerSec offset.
k_bpb_off_secperclus	BPB_SecPerClus offset.
k_bpb_off_rsvdseccnt	BPB_RsvdSecCnt offset.
k_bpb_off_numfats	BPB_NumFATs offset.
k_bpb_off_rootentcnt	BPB_RootEntCnt offset.
k_bpb_off_totsec16	BPB_TotSec16 offset.
k_bpb_off_media	BPB_Media offset.
k_bpb_off_fatsz16	BPB_FATSz16 offset.
k_bpb_off_secpertrk	BPB_SecPerTrk offset.
k_bpb_off_numheads	BPB_NumHeads offset.
k_bpb_off_drvnum	BS_DrvNum offset.
k_bpb_off_bootsig	BS_BootSig offset.
k_bpb_off_volid	BS_VolID offset.
k_bpb_off_vollab	BS_VolLab offset.
k_bpb_off_filsystype	BS_FilSysType offset.
k_bpb_off_sig0	0x55 signature byte.
k_bpb_off_sig1	0xAA signature byte.
k_bpb_secperclus_1	1 sector per cluster.
k_bpb_rsvdseccnt_1	1 reserved sector.
k_bpb_numfats_1	1 FAT copy.
k_bpb_rootentcnt_512	512 root-directory entries.
k_bpb_media_f8	Fixed-disk media descriptor.
k_bpb_fatsz16_17	17 sectors per FAT.
k_bpb_secpertrk_32	32 sectors per track.
k_bpb_numheads_16	16 heads.
k_bpb_drvnum_80	Drive number (first fixed disk).
k_bpb_bootsig_29	Extended boot signature.
k_bpb_sig0_55	Boot-sector signature byte 0.
k_bpb_sig1_aa	Boot-sector signature byte 1.
k_dir_off_attr	Directory-entry attribute byte.
k_dir_off_entry	Second 32-byte directory entry.
k_dir_off_fstcluslo	DIR_FstClusLO offset within entry.
k_dir_off_filesize	DIR_FileSize offset within entry.
k_dir_attr_vollabel	ATTR_VOLUME_ID.
k_dir_attr_readonly	ATTR_READ_ONLY.

Definition at line 322 of file emu_usbh_seam.c.

◆ vmsc_const_t

enum vmsc_const_t : uint32_t

FAT16 geometry + boot/dir layout for the virtual MSC volume.

Enumerator
k_vmsc_block_size	Logical block size.
k_vmsc_total_sectors	1 reserved + 17 FAT + 32 root + 4096.
k_vmsc_root_lba	First root-directory LBA.
k_vmsc_data_lba	First data-region LBA (cluster 2).
k_vmsc_first_cluster	FAT data area starts at cluster 2.
k_vmsc_last_mram_clus	Last cluster of MRAM.BIN.
k_vmsc_entries_per_fs	FAT16 entries per 512-byte sector.
k_vmsc_overlay_slots	Overwritten sectors the overlay holds.
k_vmsc_mram_base	MRAM window base (MRAM.BIN data).
k_vmsc_fat_entry0	FAT[0]: media F8 + filler.
k_vmsc_fat_eoc	End-of-chain marker.
k_vmsc_file_bytes	MRAM.BIN size: 1 MiB.
k_vmsc_volid	Boot-sector volume serial.

Definition at line 305 of file emu_usbh_seam.c.

Function Documentation

◆ emu_usbh_done()

bool emu_usbh_done ( void )

Implementation of emu_usbh_done() – the USBH early-stop predicate.

Whether the virtual host-mode device served its final request.

Definition at line 856 of file emu_usbh_seam.c.

References k_vkbd_stop_reports, s_vkbd_reports_sent, and s_vmsc_write_seen.

Referenced by internal_run_stop_usb().

◆ internal_on_hmsc_enumerate()

RA8_INTERNAL void internal_on_hmsc_enumerate	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on hmsc enumerate for the emu USB host seam model.

Perform on hmsc enumerate for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on hmsc enumerate.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 652 of file emu_usbh_seam.c.

References emu_mem_write(), eth_hook_return(), internal_vmsc_put16(), k_hmsc_bulk_mps, k_hmsc_dev_bytes, k_hmsc_off_pid, k_hmsc_off_vid, k_hmsc_product_id, and k_hmsc_vendor_id.

Referenced by usbh_seam_install().

◆ internal_on_hmsc_ok()

RA8_INTERNAL void internal_on_hmsc_ok	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on hmsc ok for the emu USB host seam model.

Perform on hmsc ok for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on hmsc ok.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 620 of file emu_usbh_seam.c.

References eth_hook_return().

Referenced by usbh_seam_install().

◆ internal_on_hmsc_read10()

RA8_INTERNAL void internal_on_hmsc_read10	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on hmsc read10 for the emu USB host seam model.

Perform on hmsc read10 for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on hmsc read10.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 721 of file emu_usbh_seam.c.

References emu_mem_write(), eth_hook_return(), internal_vmsc_fill_sector(), internal_vmsc_overlay_get(), k_lo16_mask, and k_vmsc_block_size.

Referenced by usbh_seam_install().

◆ internal_on_hmsc_read_capacity()

RA8_INTERNAL void internal_on_hmsc_read_capacity	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on hmsc read capacity for the emu USB host seam model.

Perform on hmsc read capacity for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on hmsc read capacity.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 688 of file emu_usbh_seam.c.

References emu_mem_write(), eth_hook_return(), k_vmsc_block_size, and k_vmsc_total_sectors.

Referenced by usbh_seam_install().

◆ internal_on_hmsc_write10()

RA8_INTERNAL void internal_on_hmsc_write10	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on hmsc write10 for the emu USB host seam model.

Perform on hmsc write10 for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on hmsc write10.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 759 of file emu_usbh_seam.c.

References emu_mem_read(), eth_hook_return(), internal_vmsc_overlay_put(), k_lo16_mask, k_ra8_err_inval_st, k_vmsc_block_size, s_vmsc_writable, and s_vmsc_write_seen.

Referenced by usbh_seam_install().

◆ internal_on_usbh_bulk_in()

RA8_INTERNAL void internal_on_usbh_bulk_in	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on USB host bulk in for the emu USB host seam model.

Perform on usb host bulk in for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on USB host bulk in.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 262 of file emu_usbh_seam.c.

References emu_mem_write(), eth_hook_return(), internal_usbh_arg5(), k_vkbd_num_keys, k_vkbd_report_len, s_k_vkbd_keycodes, s_vkbd_reports_sent, and s_vkbd_seq.

Referenced by usbh_seam_install().

◆ internal_on_usbh_control_xfer()

RA8_INTERNAL void internal_on_usbh_control_xfer	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on USB host control xfer for the emu USB host seam model.

Perform on usb host control xfer for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on USB host control xfer.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 203 of file emu_usbh_seam.c.

References emu_mem_read(), emu_mem_write(), eth_hook_return(), internal_usbh_arg5(), k_vkbd_breq_get_descriptor, k_vkbd_cfg_desc_len, k_vkbd_dev_desc_len, k_vkbd_dt_config, k_vkbd_dt_device, k_vkbd_dt_hid_report, s_k_vkbd_config_desc, s_k_vkbd_device_desc, s_k_vkbd_report_desc, and s_vkbd_ctrl_serviced.

Referenced by usbh_seam_install().

◆ internal_on_usbh_line_state()

RA8_INTERNAL void internal_on_usbh_line_state	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on USB host line state for the emu USB host seam model.

Perform on usb host line state for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on USB host line state.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 182 of file emu_usbh_seam.c.

References eth_hook_return(), and k_vkbd_lnst_attached.

Referenced by usbh_seam_install().

◆ internal_on_usbh_ok()

RA8_INTERNAL void internal_on_usbh_ok	(	uc_engine *	uc,
		uint64_t	address,
		uint32_t	size,
		void *	user )

static

Perform on USB host ok for the emu USB host seam model.

Perform on usb host ok for the emu usb host seam model; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	address	Guest address involved in the operation.
[in]	size	Size of the requested region or access in bytes.
[in,out]	user	Hook context supplied when the callback was registered.

Precondition: Arguments satisfy the ranges documented for on USB host ok.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 161 of file emu_usbh_seam.c.

References eth_hook_return().

Referenced by usbh_seam_install().

◆ internal_usbh_arg5()

RA8_INTERNAL uint32_t internal_usbh_arg5 ( uc_engine * uc )

static

Read the 5th (stack-passed) argument of an AAPCS call: mem32[SP].

Read the 5th (stack-passed) argument of an aapcs call: mem32[sp]; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out] uc Unicorn engine whose emulated state is read or updated.

Returns: The USB host arg5 result produced by the emu USB host seam model.

Return values

value The operation-specific USB host arg5 value.

Precondition: Arguments satisfy the ranges documented for USB host arg5.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 139 of file emu_usbh_seam.c.

References emu_mem_read(), and RA8_INTERNAL.

Referenced by internal_on_usbh_bulk_in(), and internal_on_usbh_control_xfer().

◆ internal_vmsc_fill_boot()

RA8_INTERNAL void internal_vmsc_fill_boot ( uint8_t * out )

static

Synthesize the FAT16 boot sector (BPB), mirroring the device side.

Synthesize the fat16 boot sector (bpb), mirroring the device side; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[out] out Destination storage receiving the computed result.

Precondition: Arguments satisfy the ranges documented for vmsc fill boot.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 494 of file emu_usbh_seam.c.

References internal_vmsc_put16(), internal_vmsc_put32(), k_bpb_bootsig_29, k_bpb_drvnum_80, k_bpb_fatsz16_17, k_bpb_jmp0, k_bpb_jmp1, k_bpb_jmp2, k_bpb_media_f8, k_bpb_numfats_1, k_bpb_numheads_16, k_bpb_off_bootsig, k_bpb_off_bytspersec, k_bpb_off_drvnum, k_bpb_off_fatsz16, k_bpb_off_filsystype, k_bpb_off_media, k_bpb_off_numfats, k_bpb_off_numheads, k_bpb_off_oem, k_bpb_off_rootentcnt, k_bpb_off_rsvdseccnt, k_bpb_off_secperclus, k_bpb_off_secpertrk, k_bpb_off_sig0, k_bpb_off_sig1, k_bpb_off_totsec16, k_bpb_off_volid, k_bpb_off_vollab, k_bpb_rootentcnt_512, k_bpb_rsvdseccnt_1, k_bpb_secperclus_1, k_bpb_secpertrk_32, k_bpb_sig0_55, k_bpb_sig1_aa, k_vmsc_block_size, k_vmsc_total_sectors, k_vmsc_volid, memcpy(), RA8_INTERNAL, s_k_vmsc_fstype, s_k_vmsc_label, and s_k_vmsc_oem.

Referenced by internal_vmsc_fill_sector().

◆ internal_vmsc_fill_fat()

RA8_INTERNAL void internal_vmsc_fill_fat	(	uint32_t	fat_sector,
		uint8_t *	out )

static

Synthesize one FAT sector: MRAM.BIN chains clusters 2..2049.

Synthesize one fat sector: mram.bin chains clusters 2..2049; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in]	fat_sector	Fat sector input used by the operation.
[out]	out	Destination storage receiving the computed result.

Precondition: Arguments satisfy the ranges documented for vmsc fill fat.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 532 of file emu_usbh_seam.c.

References internal_vmsc_put16(), k_vmsc_entries_per_fs, k_vmsc_fat_entry0, k_vmsc_fat_eoc, k_vmsc_last_mram_clus, and RA8_INTERNAL.

Referenced by internal_vmsc_fill_sector().

◆ internal_vmsc_fill_root()

RA8_INTERNAL void internal_vmsc_fill_root	(	uint32_t	root_sector,
		uint8_t *	out )

static

Synthesize root-directory sector 0: volume label + MRAM.BIN entry.

Synthesize root-directory sector 0: volume label + mram.bin entry; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in]	root_sector	Root sector input used by the operation.
[out]	out	Destination storage receiving the computed result.

Precondition: Arguments satisfy the ranges documented for vmsc fill root.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 561 of file emu_usbh_seam.c.

References internal_vmsc_put16(), internal_vmsc_put32(), k_dir_attr_readonly, k_dir_attr_vollabel, k_dir_off_attr, k_dir_off_entry, k_dir_off_filesize, k_dir_off_fstcluslo, k_vmsc_file_bytes, k_vmsc_first_cluster, memcpy(), RA8_INTERNAL, s_k_vmsc_fname, and s_k_vmsc_label.

Referenced by internal_vmsc_fill_sector().

◆ internal_vmsc_fill_sector()

RA8_INTERNAL void internal_vmsc_fill_sector	(	uc_engine *	uc,
		uint32_t	lba,
		uint8_t *	out )

static

Fill one 512-byte volume sector (boot / FAT / root / live MRAM data).

Fill one 512-byte volume sector (boot / fat / root / live mram data); this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	uc	Unicorn engine whose emulated state is read or updated.
[in]	lba	Logical block address selected by the storage operation.
[out]	out	Destination storage receiving the computed result.

Precondition: Arguments satisfy the ranges documented for vmsc fill sector.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 586 of file emu_usbh_seam.c.

References emu_mem_read(), internal_vmsc_fill_boot(), internal_vmsc_fill_fat(), internal_vmsc_fill_root(), k_vmsc_block_size, k_vmsc_data_lba, k_vmsc_first_cluster, k_vmsc_last_mram_clus, k_vmsc_mram_base, k_vmsc_root_lba, memset(), and RA8_INTERNAL.

Referenced by internal_on_hmsc_read10().

◆ internal_vmsc_overlay_get()

RA8_INTERNAL bool internal_vmsc_overlay_get	(	uint32_t	lba,
		uint8_t *	out )

static

Return an overwritten sector if lba is in the overlay.

Return an overwritten sector if lba is in the overlay; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in]	lba	Logical block address selected by the storage operation.
[out]	out	Destination storage receiving the computed result.

Returns: The vmsc overlay get result produced by the emu USB host seam model.

Return values

true	The vmsc overlay get condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for vmsc overlay get.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 412 of file emu_usbh_seam.c.

References k_vmsc_block_size, memcpy(), RA8_INTERNAL, and s_vmsc_overlay.

Referenced by internal_on_hmsc_read10().

◆ internal_vmsc_overlay_put()

RA8_INTERNAL void internal_vmsc_overlay_put	(	uint32_t	lba,
		const uint8_t *	in )

static

Record an overwritten sector (update existing slot or take a free one).

Record an overwritten sector (update existing slot or take a free; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in]	lba	Logical block address selected by the storage operation.
[in]	in	In input used by the operation.

Precondition: Arguments satisfy the ranges documented for vmsc overlay put.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 432 of file emu_usbh_seam.c.

References k_vmsc_block_size, memcpy(), RA8_INTERNAL, and s_vmsc_overlay.

Referenced by internal_on_hmsc_write10().

◆ internal_vmsc_put16()

RA8_INTERNAL void internal_vmsc_put16	(	uint8_t *	p,
		uint16_t	v )

static

Little-endian 16-bit store into a sector buffer.

Little-endian 16-bit store into a sector buffer; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	p	Module-owned state object processed by the operation.
[in]	v	Register or payload value processed by the operation.

Precondition: Arguments satisfy the ranges documented for vmsc put16.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 461 of file emu_usbh_seam.c.

References k_bpb_shift8, k_byte_mask, and RA8_INTERNAL.

Referenced by internal_on_hmsc_enumerate(), internal_vmsc_fill_boot(), internal_vmsc_fill_fat(), and internal_vmsc_fill_root().

◆ internal_vmsc_put32()

RA8_INTERNAL void internal_vmsc_put32	(	uint8_t *	p,
		uint32_t	v )

static

Little-endian 32-bit store into a sector buffer.

Little-endian 32-bit store into a sector buffer; this step is contained within the emu USB host seam model and uses bounded caller or module-owned storage.

Parameters

[in,out]	p	Module-owned state object processed by the operation.
[in]	v	Register or payload value processed by the operation.

Precondition: Arguments satisfy the ranges documented for vmsc put32.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu USB host seam model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 477 of file emu_usbh_seam.c.

References k_bpb_shift16, k_bpb_shift24, k_bpb_shift8, k_byte_mask, and RA8_INTERNAL.

Referenced by internal_vmsc_fill_boot(), and internal_vmsc_fill_root().

◆ usbh_seam_install()

bool usbh_seam_install	(	uc_engine *	uc,
		const emu_elf_source_t *	elf )

Install the virtual USB host-mode device seam if the host stack is linked.

Picks the virtual device class from the firmware's linked host stack: an MSC host (links ra8_usb_hmsc_read10) gets a read-only FAT16 disk seamed at the ra8_usb_hmsc_* class API; otherwise a USB-host-capable firmware (links ra8_usb_host_control_xfer) gets a HID boot keyboard seamed at the ra8_usb_host_* primitives. Device-mode apps link neither call path, so the hooks are inert there and board_usb.c's device-mode virtual host is untouched.

Parameters

[in,out]	uc	Active Unicorn engine.
[in]	elf	Loaded ELF image (symbol resolution).

Precondition: uc is initialised and elf is a validated loaded image.

Postcondition: On a host app, the linked host API answers a virtual device.

Note: No effect on device-mode apps (the hooked symbols are never called).

Returns: true when a seam family was installed (the register-level USBHS host model must then stay dormant – see board_usb_host.h).

Return values

true	hmsc- or primitive-level seams now shadow the host API.
false	No usb-host seams; the register path is the real one.

Since: 0.1.0

Definition at line 818 of file emu_usbh_seam.c.

References elf_sym_addr(), eth_seam_hook(), internal_on_hmsc_enumerate(), internal_on_hmsc_ok(), internal_on_hmsc_read10(), internal_on_hmsc_read_capacity(), internal_on_hmsc_write10(), internal_on_usbh_bulk_in(), internal_on_usbh_control_xfer(), internal_on_usbh_line_state(), internal_on_usbh_ok(), priv_emu_io_errf(), and s_vmsc_writable.

Referenced by internal_main_install_run_seams().

Variable Documentation

◆ s_k_vkbd_config_desc

const uint8_t s_k_vkbd_config_desc[k_vkbd_cfg_desc_len]

static

Initial value:

                                          = {
  0x09, 0x02, 0x22, 0x00, 0x01, 0x01, 0x00, 0xA0, 0x32, 
  0x09, 0x04, 0x00, 0x00, 0x01, 0x03, 0x01, 0x01, 0x00, 
  0x09, 0x21, 0x11, 0x01, 0x00, 0x01, 0x22, 0x3F, 0x00, 
  0x07, 0x05, 0x81, 0x03, 0x40, 0x00, 0x01,             
}

34-byte CONFIGURATION: 1 HID boot-keyboard iface, 1 interrupt-IN EP1.

Definition at line 91 of file emu_usbh_seam.c.

Referenced by internal_on_usbh_control_xfer().

◆ s_k_vkbd_device_desc

const uint8_t s_k_vkbd_device_desc[k_vkbd_dev_desc_len]

static

Initial value:

                                          = {
  0x12,
  0x01,
  0x00,
  0x02,
  0x00,
  0x00,
  0x00,
  0x40, 
  0x6A,
  0x1A,
  0x88,
  0x42,
  0x00,
  0x01,
  0x00,
  0x00, 
  0x00,
  0x01, 
}

18-byte DEVICE descriptor: class defined at interface, EP0 MPS 64.

Definition at line 68 of file emu_usbh_seam.c.

Referenced by internal_on_usbh_control_xfer().

◆ s_k_vkbd_keycodes

const uint8_t s_k_vkbd_keycodes[k_vkbd_num_keys]

static

Initial value:

= {k_vkbd_key_r,
                    k_vkbd_key_a,
                    k_vkbd_key_8,
                    k_vkbd_key_d,
                    k_vkbd_key_2}

HID Usage-Table keycodes the virtual keyboard "types": R A 8 D 2.

Definition at line 118 of file emu_usbh_seam.c.

Referenced by internal_on_usbh_bulk_in().

◆ s_k_vkbd_report_desc

const uint8_t s_k_vkbd_report_desc[63]

static

Initial value:

                                          = {
  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,
}

Standard boot-keyboard HID REPORT descriptor (63 bytes, USB HID 1.11 E.6).

Definition at line 101 of file emu_usbh_seam.c.

Referenced by internal_on_usbh_control_xfer().

◆ s_k_vmsc_fname

const uint8_t s_k_vmsc_fname[11] = {'M', 'R', 'A', 'M', ' ', ' ', ' ', ' ', 'B', 'I', 'N'}

static

Definition at line 370 of file emu_usbh_seam.c.

Referenced by internal_vmsc_fill_root().

◆ s_k_vmsc_fstype

const uint8_t s_k_vmsc_fstype[8] = {'F', 'A', 'T', '1', '6', ' ', ' ', ' '}

static

Definition at line 369 of file emu_usbh_seam.c.

Referenced by internal_vmsc_fill_boot().

◆ s_k_vmsc_label

const uint8_t s_k_vmsc_label[11] = {'R', 'A', '8', 'D', '2', ' ', 'M', 'R', 'A', 'M', ' '}

static

Definition at line 368 of file emu_usbh_seam.c.

Referenced by internal_vmsc_fill_boot(), and internal_vmsc_fill_root().

◆ s_k_vmsc_oem

const uint8_t s_k_vmsc_oem[8] = {'R', 'A', '8', 'D', '2', 'F', 'W', ' '}

static

Definition at line 367 of file emu_usbh_seam.c.

Referenced by internal_vmsc_fill_boot().

◆ s_vkbd_ctrl_serviced

uint32_t s_vkbd_ctrl_serviced = 0U

static

Control transfers answered.

Definition at line 125 of file emu_usbh_seam.c.

Referenced by internal_on_usbh_control_xfer().

◆ s_vkbd_reports_sent

uint32_t s_vkbd_reports_sent = 0U

static

Interrupt-IN reports streamed.

Definition at line 126 of file emu_usbh_seam.c.

Referenced by emu_usbh_done(), and internal_on_usbh_bulk_in().

◆ s_vkbd_seq

uint8_t s_vkbd_seq = 0U

static

Rolling report seq (report byte 0).

Definition at line 124 of file emu_usbh_seam.c.

Referenced by internal_on_usbh_bulk_in().

◆ s_vmsc_overlay

vmsc_overlay_t s_vmsc_overlay[k_vmsc_overlay_slots]

static

Write overlay for the writable disk (file_ops touches only a handful).

Definition at line 398 of file emu_usbh_seam.c.

Referenced by internal_vmsc_overlay_get(), and internal_vmsc_overlay_put().

◆ s_vmsc_writable

bool s_vmsc_writable = false

static

True when the virtual disk is writable (usb_host_file_ops links fileops_backend_write); else the disk is read-only and WRITE(10) is rejected.

Definition at line 380 of file emu_usbh_seam.c.

Referenced by internal_on_hmsc_write10(), and usbh_seam_install().

◆ s_vmsc_write_seen

bool s_vmsc_write_seen = false

static

Set once the host attempts a WRITE(10) into the READ-ONLY disk – the last host step before usb_host_msc_browse's PASS (read by the USBH_STOP guard).

Definition at line 375 of file emu_usbh_seam.c.

Referenced by emu_usbh_done(), and internal_on_hmsc_write10().

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ hmsc_dev_t

◆ usbh_err_code_t

◆ vkbd_const_t

◆ vkbd_keycode_t

◆ vmsc_bpb_t

◆ vmsc_const_t

Function Documentation

◆ emu_usbh_done()

◆ internal_on_hmsc_enumerate()

◆ internal_on_hmsc_ok()

◆ internal_on_hmsc_read10()

◆ internal_on_hmsc_read_capacity()

◆ internal_on_hmsc_write10()

◆ internal_on_usbh_bulk_in()

◆ internal_on_usbh_control_xfer()

◆ internal_on_usbh_line_state()

◆ internal_on_usbh_ok()

◆ internal_usbh_arg5()

◆ internal_vmsc_fill_boot()

◆ internal_vmsc_fill_fat()

◆ internal_vmsc_fill_root()

◆ internal_vmsc_fill_sector()

◆ internal_vmsc_overlay_get()

◆ internal_vmsc_overlay_put()

◆ internal_vmsc_put16()

◆ internal_vmsc_put32()

◆ usbh_seam_install()

Variable Documentation

◆ s_k_vkbd_config_desc

◆ s_k_vkbd_device_desc

◆ s_k_vkbd_keycodes

◆ s_k_vkbd_report_desc

◆ s_k_vmsc_fname

◆ s_k_vmsc_fstype

◆ s_k_vmsc_label

◆ s_k_vmsc_oem

◆ s_vkbd_ctrl_serviced

◆ s_vkbd_reports_sent

◆ s_vkbd_seq

◆ s_vmsc_overlay

◆ s_vmsc_writable

◆ s_vmsc_write_seen