emu_usbh_seam.h File Reference

Virtual USB host-mode devices behind the ra8_usb_host_* / hmsc seams. More...

#include <stdint.h>
#include <unicorn/unicorn.h>
#include "emu_elf.h"
#include "ra8_attributes.h"

Include dependency graph for emu_usbh_seam.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
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)
	Whether the virtual host-mode device served its final request.

Detailed Description

Virtual USB host-mode devices behind the ra8_usb_host_* / hmsc seams.

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 through the first-party ra8_usb_host_* primitives, and with no peer the control transfer wedges. Rather than model a second controller register-by-register, those primitives are seamed to a virtual peer: a HID boot keyboard that answers chapter-9 enumeration and streams interrupt-IN reports, or – when the firmware links the ra8_usb_hmsc_* class API – a FAT16 MSC disk whose one file MRAM.BIN is the live 1 MiB MRAM code window (read-only for the browse app, writable with a small sector overlay for the file-ops app).

Split out of the ra8_emulator main translation unit; behaviour unchanged.

Copyright

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

Since

0.1.0

Definition in file emu_usbh_seam.h.

Function Documentation

emu_usbh_done()

bool emu_usbh_done

(

void

)

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

True once the virtual keyboard streamed its report quota, or the read-only MSC disk saw the host's WRITE(10) probe (the step right before usb_host_msc_browse's PASS) – the RA8_EMU_USBH_STOP early-stop condition.

Returns

true when the host-mode ladder has completed.

Return values

false

The virtual device is still being driven (or unused).

Precondition

None.

None.

Postcondition

No state is modified.

Note

Not thread-safe; the emulator is single-threaded host-side.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

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().

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 the FAT16 disk seamed at the class API; otherwise a USB-host-capable firmware (links ra8_usb_host_control_xfer) gets the HID boot keyboard seamed at the 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	Open ELF source used for symbol resolution.

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.

Precondition

uc is initialised and elf remains open.

Not running under –usbhs-loop (the caller gates that mode).

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).

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

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().