USBFS controller model + a virtual USB host for the board emulator. More...

#include <stdint.h>
#include <unicorn/unicorn.h>

Include dependency graph for board_usb.h:

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

Typedefs
typedef void(*	board_usb_irq_raiser_t) (uc_engine *uc, uint16_t event)
	Signature of the ICU event-raise hook board_periph installs.

Functions
void	board_usb_init (bool trace)
	Reset the USBFS controller model and the virtual host state machine.
void	board_usb_set_irq_raiser (board_usb_irq_raiser_t raise)
	Install the ICU event-raise hook used to pend the USBFS interrupt.
uint64_t	board_usb_read (uc_engine uc, uint64_t addr, unsigned size, bool handled)
	Dispatch an MMIO read inside the USBFS register window.
void	board_usb_write (uc_engine uc, uint64_t addr, unsigned size, uint64_t value, bool handled)
	Dispatch an MMIO write inside the USBFS register window.
void	board_usb_tick (uc_engine *uc)
	Advance the virtual USB host one emulation chunk.
bool	board_usb_configured (void)
	Report whether enumeration reached the CONFIGURED state.
const char *	board_usb_state_string (void)
	One-line, human-readable USB device state for the board view.
void	board_usb_feed_bulk_in (const uint8_t *data, uint32_t len)
	Queue host->device bulk bytes for the CDC data OUT pipe (echo test).
uint32_t	board_usb_echo_received (void)
	Number of bulk bytes the host has read back as the device's echo.
void	board_usb_report (void)
	Print the USB section of the end-of-run summary.
void	board_usb_set_external_host (bool present)
	Declare (or withdraw) a real-firmware USB host driving the device.
bool	board_usb_dev_attached (void)
	Whether the modelled USBFS device has asserted its D+ pull-up (DPRPU).
void	board_usb_bridge_bus_reset (uc_engine *uc)
	Bridge a host bus reset onto the device (advance DVSQ to Default).
void	board_usb_bridge_deliver_setup (uc_engine uc, const uint8_t setup)
	Deliver an 8-byte host SETUP packet to the device (raise its CTRT).
bool	board_usb_bridge_dcp_in_ready (void)
	Whether the device has queued a control-IN response on the DCP.
uint16_t	board_usb_bridge_dcp_in_take (uint8_t *buf, uint16_t cap)
	Consume the device's queued control-IN response into `buf`.
void	board_usb_bridge_ctrl_status (uc_engine *uc)
	Drive the read-status stage of a host control-read (raise CTRT).
bool	board_usb_bridge_dev_took_ccpl (void)
	Take (consume) the device's control-transfer completion (DCPCTR.CCPL).
void	board_usb_bridge_mark_configured (uc_engine *uc)
	Mark the device configured after a host SET_CONFIGURATION.
void	board_usb_bridge_bulk_out (uc_engine uc, uint8_t dev_pipe, const uint8_t data, uint16_t len)
	Deliver a host bulk-OUT packet to a device endpoint pipe.
void	board_usb_bridge_dcp_out (uc_engine uc, const uint8_t data, uint16_t len)
	Deliver a host control-write data-stage packet to the device DCP.
bool	board_usb_bridge_dcp_out_consumed (void)
	Whether the device has drained the last host DCP control-OUT packet.
bool	board_usb_bridge_bulk_out_consumed (uint8_t dev_pipe)
	Whether the device has drained the last host bulk-OUT packet.
bool	board_usb_bridge_bulk_in_ready (uint8_t dev_pipe)
	Whether the device has queued a bulk-IN packet on `dev_pipe`.
uint16_t	board_usb_bridge_bulk_in_take (uc_engine uc, uint8_t dev_pipe, uint8_t buf, uint16_t cap)
	Consume a device bulk-IN packet from `dev_pipe` into `buf`.
bool	board_usb_roles_swapped (void)
	Whether the self-loop window roles are swapped (Config B).
void	board_usb_roles_swap (uc_engine *uc)
	Swap the self-loop window<->model bindings (enter Config B).
uint64_t	board_usb_dev_reg_read (uc_engine *uc, uint64_t off, unsigned size)
	Device-model register read by window byte offset (role routing).
void	board_usb_dev_reg_write (uc_engine *uc, uint64_t off, unsigned size, uint64_t value)
	Device-model register write by window byte offset (role routing).
uint64_t	board_usbhs_host_reg_read (uc_engine *uc, uint64_t off, unsigned size)
	Host-model register read by window byte offset (role routing).
void	board_usbhs_host_reg_write (uc_engine *uc, uint64_t off, unsigned size, uint64_t value)
	Host-model register write by window byte offset (role routing).
uint32_t	board_usbhs_host_shadow_handoff (uint16_t *dst_words, uint32_t word_capacity)
	Hand the host model's register shadow off and reset the host model.
void	board_usb_loop_latch (void)
	Latch the self-loop: the firmware brought a controller up as HOST.
bool	board_usb_loop_attached (void)
	Whether the modelled USBFS device presents its D+ pull-up.
void	board_usb_loop_bus_reset (uc_engine *uc)
	Deliver a bus reset to the modelled USBFS device (host released RST).
bool	board_usb_loop_setup (uc_engine *uc, uint16_t req, uint16_t val, uint16_t indx, uint16_t leng)
	Deliver one SETUP packet from the firmware host to the device.
bool	board_usb_loop_take_ccpl (uc_engine *uc)
	Poll the device's control-transfer completion (DCPCTR.CCPL).
uint16_t	board_usb_loop_ctrl_in_avail (void)
	Control-IN bytes the device has queued and the host not yet drained.
uint16_t	board_usb_loop_ctrl_in_read (uint8_t *dst, uint16_t cap)
	Drain up to `cap` control-IN bytes from the device's DCP staging.
void	board_usb_loop_ctrl_in_flush (void)
	Drop whatever remains of the device's control-IN staging.
void	board_usb_loop_ctrl_out (uc_engine uc, const uint8_t data, uint16_t len)
	Deliver a control-OUT data-stage packet to the device's DCP.
void	board_usb_loop_status_out_zlp (uc_engine *uc)
	Run the control-read status stage against the device (host OUT ZLP).
void	board_usb_loop_bulk_out (uc_engine uc, uint8_t ep, const uint8_t data, uint16_t len)
	Deliver one bulk-OUT packet from the firmware host to a device pipe.
uint16_t	board_usb_loop_bulk_in_avail (uint8_t ep)
	Bulk-IN bytes a device pipe has queued and the host not yet drained.
uint16_t	board_usb_loop_bulk_in_read (uc_engine uc, uint8_t ep, uint8_t dst, uint16_t cap)
	Drain up to `cap` bulk-IN bytes from a device pipe's staging.
void	board_usb_loop_bulk_in_flush (uint8_t ep)
	Drop whatever remains of a device pipe's bulk-IN staging.

Detailed Description

USBFS controller model + a virtual USB host for the board emulator.

Models the RA8D2 USB 2.0 Full-Speed controller (USBFS, base 0x40250000, HUM Ch 36) at register granularity AND drives a virtual USB host that runs the standard chapter-9 enumeration against the device-side firmware. This is the "debug USB without hardware" peripheral: the real, unmodified ThreadX + Eclipse USBX CDC-ACM firmware (port/usbx/ux_dcd_ra8_usb -> libs/ra8_hal ra8_usb*.c) runs on the emulated Cortex-M, and this module presents it a host that issues GET_DESCRIPTOR / SET_ADDRESS / SET_CONFIGURATION / CDC requests, clocks the device's descriptor responses out of the CFIFO, and advances the device state (DVSQ powered -> default -> address -> configured) until USBX's CDC-ACM activate callback fires.

Two cooperating halves live here:

Controller model – SYSCFG (DPRPU pull-up / USBE / SCKE), INTSTS0 (CTSQ control-stage, DVSQ device-state, VALID, CTRT / DVST / BRDY event bits), the CFIFO data port with its CFIFOSEL / CFIFOCTR handshake (FRDY / BVAL / BCLR / DTLN), USBREQ..USBLENG SETUP latches, DCPCTR (PID / CCPL), the PIPECTR / BRDYSTS / NRDYSTS pipe machinery, and USBADDR / FRMNUM. Reads / writes are dispatched from board_periph's MMIO callbacks (the USB window is forwarded to board_usb_read / board_usb_write).
Virtual host – a small state machine, stepped once per emulation chunk from board_usb_tick, that watches SYSCFG.DPRPU, drives a bus reset, and walks the SETUP sequence. Each control-read SETUP is latched into the controller, the device's CTRT interrupt is raised through the ICU -> NVIC path (so the real ISR ra8_usb_dispatch runs), and the descriptor bytes the device pushes into the DCP FIFO are drained back as the host's IN data before the status stage is delivered.

Design: this module owns no Unicorn engine and no AppKit dependency. The engine is passed in where the model must read / write emulated memory or raise an NVIC line; the NVIC pend itself is delegated to board_periph (which owns the ICU IELSR table and the IRQ ring) through board_usb_set_irq_raiser so all exception delivery stays in one place.

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

Since: 0.1.0

Definition in file board_usb.h.

Typedef Documentation

◆ board_usb_irq_raiser_t

typedef void(* board_usb_irq_raiser_t) (uc_engine *uc, uint16_t event)

Signature of the ICU event-raise hook board_periph installs.

The USB host model raises the USBFS controller interrupt by asserting its ELC event (0x09A); board_periph owns the IELSR event-link table, the NVIC enable shadow and the pending-IRQ ring, so it supplies this callback and the USB model never touches that state directly.

Parameters

[in,out]	uc	Unicorn engine (the ICU reads IELSR / NVIC from PPB).
[in]	event	ELC event number to assert (USBFS_INT == 0x09A).

Since: 0.1.0

Definition at line 68 of file board_usb.h.

Function Documentation

◆ board_usb_bridge_bulk_in_ready()

bool board_usb_bridge_bulk_in_ready ( uint8_t dev_pipe )

Whether the device has queued a bulk-IN packet on dev_pipe.

Parameters

[in] dev_pipe Device pipe number to probe (1..9).

Returns: true when the device has staged bytes for the host to read.

Since: 0.1.0

Whether the device has queued a bulk-in packet on dev_pipe; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

true	The board USB bridge bulk in ready condition holds or completed successfully; false otherwise.

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

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

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

Definition at line 189 of file board_usb_bridge.c.

References k_usb_pipe_count, and s_usb.

Referenced by internal_hs_brdysts_read().

◆ board_usb_bridge_bulk_in_take()

uint16_t board_usb_bridge_bulk_in_take	(	uc_engine *	uc,
		uint8_t	dev_pipe,
		uint8_t *	buf,
		uint16_t	cap )

Consume a device bulk-IN packet from dev_pipe into buf.

Copies the device's queued IN bytes out and raises the pipe's BEMP interrupt so the device firmware can stage the next packet.

Parameters

[in,out]	uc	Unicorn engine (to pend the device USB interrupt).
[in]	dev_pipe	Device pipe number to drain (1..9).
[out]	buf	Destination buffer.
[in]	cap	Capacity of `buf` in bytes.

Returns: The number of bytes copied (0 if none were queued).

Since: 0.1.0

Return values

value The operation-specific board USB bridge bulk in take value.

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

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

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

Definition at line 195 of file board_usb_bridge.c.

References internal_usb_word(), k_ra8_int0_bit_bemp, k_ra8_usb_off_bempsts, k_usb_pipe_count, memcpy(), priv_usb_intsts0_set(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_hs_brdysts_read().

◆ board_usb_bridge_bulk_out()

void board_usb_bridge_bulk_out	(	uc_engine *	uc,
		uint8_t	dev_pipe,
		const uint8_t *	data,
		uint16_t	len )

Deliver a host bulk-OUT packet to a device endpoint pipe.

Stages len bytes into the device's OUT pipe buffer and raises the pipe's BRDY interrupt, so the device firmware's bulk-OUT receive path (e.g. the CDC-ACM read, or the MSC CBW/data receive) completes.

Parameters

[in,out]	uc	Unicorn engine (to pend the device USB interrupt).
[in]	dev_pipe	Device pipe number the endpoint maps to (1..9).
[in]	data	Payload bytes (host -> device).
[in]	len	Payload length in bytes.

Returns: Nothing.

Since: 0.1.0

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

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

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

Definition at line 159 of file board_usb_bridge.c.

References internal_usb_word(), k_ra8_int0_bit_brdy, k_ra8_usb_off_brdysts, k_usb_pipe_count, memcpy(), priv_usb_intsts0_set(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_hs_bulk_out_commit().

◆ board_usb_bridge_bulk_out_consumed()

bool board_usb_bridge_bulk_out_consumed ( uint8_t dev_pipe )

Whether the device has drained the last host bulk-OUT packet.

The USBHS host model gates a bulk-OUT pipe's buffer-empty (BEMP) completion on this so a multi-packet data stage (e.g. a WRITE(10) payload) hands the device one packet at a time: the polled host does not push the next OUT packet until the device firmware has drained the current one from its CFIFO, otherwise the fresh packet would overwrite the undrained bank.

Parameters

[in] dev_pipe Device pipe number the endpoint maps to (1..9).

Returns: true once the device has fully drained the staged OUT packet.

Since: 0.1.0

Return values

true	The board USB bridge bulk out consumed condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for board USB bridge bulk out consumed.; The call executes on the emulator's single owning thread.

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

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

Definition at line 179 of file board_usb_bridge.c.

References k_usb_pipe_count, and s_usb.

Referenced by internal_hs_bempsts_read().

◆ board_usb_bridge_bus_reset()

void board_usb_bridge_bus_reset ( uc_engine * uc )

Bridge a host bus reset onto the device (advance DVSQ to Default).

Mirrors the physical USB reset the host drives on DVSTCTR0.USBRST: returns the device to the Default state and raises its DVST interrupt so the device firmware re-arms its DCP, exactly as the built-in virtual host's reset phase does.

Parameters

[in,out] uc Unicorn engine (to pend the device USB interrupt).

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB bridge bus reset.; The call executes on the emulator's single owning thread.

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

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

Definition at line 81 of file board_usb_bridge.c.

References k_ra8_dvsq_default, k_ra8_int0_bit_dvst, priv_usb_intsts0_set(), priv_usb_log_line(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_hs_dvstctr0_write().

◆ board_usb_bridge_ctrl_status()

void board_usb_bridge_ctrl_status ( uc_engine * uc )

Drive the read-status stage of a host control-read (raise CTRT).

Advertises the read status stage (CTSQ) and raises the device CTRT so the device firmware closes its side of a completed control-read transfer.

Parameters

[in,out] uc Unicorn engine (to pend the device USB interrupt).

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB bridge ctrl status.; The call executes on the emulator's single owning thread.

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

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

Definition at line 141 of file board_usb_bridge.c.

References k_ra8_ctsq_rdss, k_ra8_int0_bit_ctrt, priv_usb_intsts0_set(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_hs_ccpl_status().

◆ board_usb_bridge_dcp_in_ready()

bool board_usb_bridge_dcp_in_ready ( void )

Whether the device has queued a control-IN response on the DCP.

Returns: true when the device armed its DCP (PID=BUF) with valid IN data for the host to read (e.g. a GET_DESCRIPTOR response).

Since: 0.1.0

Whether the device has queued a control-in response on the dcp; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

true	The board USB bridge default control pipe in ready condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for board USB bridge default control pipe in ready.; The call executes on the emulator's single owning thread.

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

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

Definition at line 108 of file board_usb_bridge.c.

References priv_host_dcp_pid_buf(), and s_usb.

Referenced by internal_hs_brdysts_read().

◆ board_usb_bridge_dcp_in_take()

uint16_t board_usb_bridge_dcp_in_take	(	uint8_t *	buf,
		uint16_t	cap )

Consume the device's queued control-IN response into buf.

Parameters

[out]	buf	Destination for the device's DCP IN bytes.
[in]	cap	Capacity of `buf` in bytes.

Returns: The number of bytes copied (0 if none were queued).

Postcondition: The device DCP IN buffer is cleared and ready for the next transfer.

Since: 0.1.0

Consume the device's queued control-in response into buf; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

value The operation-specific board USB bridge default control pipe in take value.

Precondition: Arguments satisfy the ranges documented for board USB bridge default control pipe in take.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 113 of file board_usb_bridge.c.

References k_usb_log_width, k_usb_trace_dump_max, memcpy(), priv_emu_io_errf(), priv_usb_detect_class(), priv_usb_log_count(), s_trace, and s_usb.

Referenced by internal_hs_brdysts_read().

◆ board_usb_bridge_dcp_out()

void board_usb_bridge_dcp_out	(	uc_engine *	uc,
		const uint8_t *	data,
		uint16_t	len )

Deliver a host control-write data-stage packet to the device DCP.

Stages len bytes of a control-OUT data stage (e.g. a DFU_DNLOAD firmware block) into the device's DCP (EP0) OUT buffer and raises the device DCP BRDY so the device firmware's control-OUT receive path drains it. The companion pump in board_usb_tick re-asserts BRDY until the device – which arms its DCP off its own IRQ – has actually received the packet, mirroring the SIE's OUT-token retry on real silicon.

Parameters

[in,out]	uc	Unicorn engine (to pend the device USB interrupt).
[in]	data	Payload bytes (host -> device); ignored if NULL.
[in]	len	Payload length in bytes.

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB bridge default control pipe out.; The call executes on the emulator's single owning thread.

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

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

Definition at line 215 of file board_usb_bridge.c.

References memcpy(), s_dcp_hold, s_dcp_hold_len, and s_dcp_hold_pending.

Referenced by internal_hs_bulk_out_commit().

◆ board_usb_bridge_dcp_out_consumed()

bool board_usb_bridge_dcp_out_consumed ( void )

Whether the device has drained the last host DCP control-OUT packet.

The USBHS host model gates a control-write data stage's buffer-empty (BEMP) completion on this, exactly as it does for a bulk-OUT pipe, so the polled host hands the device one control-OUT packet at a time.

Returns: true once the device has fully drained the staged DCP OUT packet.

Since: 0.1.0

Return values

true	The board USB bridge default control pipe out consumed condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for board USB bridge default control pipe out consumed.; The call executes on the emulator's single owning thread.

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

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

Definition at line 233 of file board_usb_bridge.c.

References s_dcp_hold_pending, and s_usb.

Referenced by internal_hs_bempsts_read().

◆ board_usb_bridge_deliver_setup()

void board_usb_bridge_deliver_setup	(	uc_engine *	uc,
		const uint8_t *	setup )

Deliver an 8-byte host SETUP packet to the device (raise its CTRT).

Latches the packet into the device's USBREQ..USBLENG mirror registers, sets the control-transfer stage (CTSQ) from the request direction, and raises the device CTRT interrupt so the real device ISR decodes it. A SET_ADDRESS additionally applies the SIE side effect the hardware performs (USBADDR latched, DVSQ -> Address).

Parameters

[in,out]	uc	Unicorn engine (to pend the device USB interrupt).
[in]	setup	Eight SETUP bytes (bmRequestType, bRequest, wValue, wIndex, wLength, little-endian) to deliver.

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB bridge deliver setup.; The call executes on the emulator's single owning thread.

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

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

Definition at line 89 of file board_usb_bridge.c.

References priv_host_apply_no_data(), and priv_host_deliver_setup().

Referenced by internal_hs_setup_launch().

◆ board_usb_bridge_dev_took_ccpl()

bool board_usb_bridge_dev_took_ccpl ( void )

Take (consume) the device's control-transfer completion (DCPCTR.CCPL).

The device firmware pulses DCPCTR.CCPL once it has finished processing a no-data host-to-device control transfer (e.g. after SET_CONFIGURATION has activated its class and armed the class endpoints). The USBHS host model gates a no-data control-write status stage on this so the polled host does not race past a request the device is still applying – the same completion the built-in virtual host waits on. Returns true exactly once per device CCPL pulse, then clears it so the next transfer starts clean.

Returns: true if the device had pulsed CCPL since the last call, else false.

Postcondition: Any observed CCPL latch is cleared.

Since: 0.1.0

Return values

true	The board USB bridge dev took ccpl condition holds or completed successfully; false otherwise.

Precondition: Arguments satisfy the ranges documented for board USB bridge dev took ccpl.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 149 of file board_usb_bridge.c.

References priv_host_take_ccpl().

Referenced by internal_hs_brdysts_read(), and internal_hs_setup_launch().

◆ board_usb_bridge_mark_configured()

void board_usb_bridge_mark_configured ( uc_engine * uc )

Mark the device configured after a host SET_CONFIGURATION.

Parameters

[in,out] uc Unicorn engine (to pend the device USB interrupt).

Returns: Nothing.

Postcondition: The device DVSQ reaches Configured and DVST is raised.

Since: 0.1.0

Mark the device configured after a host set_configuration; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Precondition: Arguments satisfy the ranges documented for board USB bridge mark configured.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 154 of file board_usb_bridge.c.

References priv_host_mark_configured().

Referenced by internal_hs_ctrl_status_complete().

◆ board_usb_configured()

bool board_usb_configured ( void )

Report whether enumeration reached the CONFIGURED state.

Returns: true once the host has issued SET_CONFIGURATION and the controller's DVSQ has advanced to Configured.

Since: 0.1.0

Report whether enumeration reached the configured state; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

true	The board USB configured condition holds or completed successfully; false otherwise.

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

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

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

Definition at line 191 of file board_usb.c.

References s_configured.

Referenced by internal_run_stop_usb().

◆ board_usb_dev_attached()

bool board_usb_dev_attached ( void )

Whether the modelled USBFS device has asserted its D+ pull-up (DPRPU).

Returns: true once the device firmware called ra8_usb_device_attach (SYSCFG.DPRPU set), i.e. a device is electrically present for the host to enumerate.

Since: 0.1.0

Whether the modelled usbfs device has asserted its d+ pull-up (dprpu); this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

true	The board USB dev attached condition holds or completed successfully; false otherwise.

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

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

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

Definition at line 76 of file board_usb_bridge.c.

References priv_host_device_attached().

Referenced by internal_hs_read().

◆ board_usb_dev_reg_read()

uint64_t board_usb_dev_reg_read	(	uc_engine *	uc,
		uint64_t	off,
		unsigned	size )

Device-model register read by window byte offset (role routing).

Offset-addressed twin of the USBFS-window claim inside board_usb_read, exported so the USBHS window block can route its reads into the device model when the roles are swapped (Config B: the DCD drives the USBHS controller in device role).

Parameters

[in,out]	uc	Unicorn engine (unused; kept for handler symmetry).
[in]	off	Byte offset inside the controller register window (0 .. 0xFE; the device model spans 0x100 bytes).
[in]	size	Access width in bytes (1 or 2).

Returns: The register value, zero-extended to 64 bits.

Precondition: off is inside the modelled 0x100-byte device register span.; board_usb_init has run (model state is live).

Postcondition: Read side effects (CFIFO drain cursors) match the device model's.

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usb_dev_reg_write

Since: 0.1.0

Return values

value The operation-specific board USB dev reg read value.

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 64 of file board_usb_bridge.c.

References priv_usb_reg_read().

Referenced by internal_usbhs_block_read().

◆ board_usb_dev_reg_write()

void board_usb_dev_reg_write	(	uc_engine *	uc,
		uint64_t	off,
		unsigned	size,
		uint64_t	value )

Device-model register write by window byte offset (role routing).

Offset-addressed twin of the USBFS-window claim inside board_usb_write, exported so the USBHS window block can route its writes into the device model when the roles are swapped (Config B).

Parameters

[in,out]	uc	Unicorn engine (unused; kept for handler symmetry).
[in]	off	Byte offset inside the controller register window (0 .. 0xFE; the device model spans 0x100 bytes).
[in]	size	Access width in bytes (1 or 2).
[in]	value	Value the firmware wrote.

Returns: Nothing.

Precondition: off is inside the modelled 0x100-byte device register span.; board_usb_init has run (model state is live).

Postcondition: Write side effects (CFIFO staging, W0C status) match the device model's.

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usb_dev_reg_read

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 70 of file board_usb_bridge.c.

References priv_usb_reg_write().

Referenced by internal_usbhs_block_write().

◆ board_usb_echo_received()

uint32_t board_usb_echo_received ( void )

Number of bulk bytes the host has read back as the device's echo.

Returns: Count of echoed bytes received on the bulk IN pipe.

Since: 0.1.0

Number of bulk bytes the host has read back as the device's echo; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

value The operation-specific board USB echo received value.

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

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

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

Definition at line 206 of file board_usb.c.

References s_echo_in_got.

◆ board_usb_feed_bulk_in()

void board_usb_feed_bulk_in	(	const uint8_t *	data,
		uint32_t	len )

Queue host->device bulk bytes for the CDC data OUT pipe (echo test).

Used by the secondary CDC-echo check: once the device is configured the host delivers these bytes to the bulk OUT pipe and then reads the bytes the device echoes back on the bulk IN pipe. Bytes beyond the staging capacity are dropped.

Parameters

[in]	data	Source bytes (copied); ignored if NULL.
[in]	len	Number of bytes to queue.

Returns: Nothing.

Postcondition: Up to the staging capacity of data is delivered after CONFIGURED.

Since: 0.1.0

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

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 196 of file board_usb.c.

References k_usb_echo_cap, memcpy(), s_echo_out, and s_echo_out_len.

Referenced by internal_main_feed_inputs().

◆ board_usb_init()

void board_usb_init ( bool trace )

Reset the USBFS controller model and the virtual host state machine.

Clears every modelled register, the CFIFO staging buffers, the host enumeration step machine and the observability counters. Call once after the memory map is created and before the run loop.

Parameters

[in] trace When true, each enumeration step and raised USB interrupt is logged to injected error sink as it happens (the –trace flag).

Returns: Nothing.

Postcondition: The model is in its power-on reset state; the host is idle, waiting for the firmware to assert SYSCFG.DPRPU.

Since: 0.1.0

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

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 165 of file board_usb.c.

References g_dev_irq_event, k_phase_idle, k_ra8_dvsq_powered, k_ra8_elc_event_usbfs_int, k_sub_deliver, s_configured, s_dcp_hold_len, s_dcp_hold_pending, s_echo_in_got, s_echo_out_len, s_echo_out_sent, s_host_phase, s_host_step, s_host_substate, s_host_wait, s_log_n, s_roles_swapped, s_trace, s_usb, and s_usb_irqs.

Referenced by board_periph_init().

◆ board_usb_loop_attached()

bool board_usb_loop_attached ( void )

Whether the modelled USBFS device presents its D+ pull-up.

Returns: true when the device firmware set SYSCFG.DPRPU (attach), else false.

Since: 0.1.0

Whether the modelled usbfs device presents its d+ pull-up; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

true	The board USB loop attached condition holds or completed successfully; false otherwise.

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

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

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

Definition at line 92 of file board_usb_loop.c.

References priv_host_device_attached().

Referenced by internal_usbhs_do_setup(), internal_usbhs_dvstctr_write(), and internal_usbhs_reg_read().

◆ board_usb_loop_bulk_in_avail()

uint16_t board_usb_loop_bulk_in_avail ( uint8_t ep )

Bulk-IN bytes a device pipe has queued and the host not yet drained.

Parameters

[in] ep Device endpoint number (1..9).

Returns: Byte count remaining in that pipe's IN staging (0 when none).

Since: 0.1.0

Bulk-in bytes a device pipe has queued and the host not yet drained; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

value The operation-specific board USB loop bulk in avail value.

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

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

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

Definition at line 248 of file board_usb_loop.c.

References k_usb_pipe_count, s_loop_pipe_rd, and s_usb.

Referenced by board_usb_loop_bulk_in_read(), internal_usbhs_brdysts_value(), and internal_usbhs_cfifoctr_value().

◆ board_usb_loop_bulk_in_flush()

void board_usb_loop_bulk_in_flush ( uint8_t ep )

Drop whatever remains of a device pipe's bulk-IN staging.

Parameters

[in] ep Device endpoint number (1..9).

Returns: Nothing.

Since: 0.1.0

Drop whatever remains of a device pipe's bulk-in staging; this step is contained within the board USB model and uses bounded caller or module-owned storage.

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

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

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

Definition at line 282 of file board_usb_loop.c.

References k_usb_pipe_count, s_loop_pipe_rd, and s_usb.

Referenced by internal_usbhs_cfifoctr_write().

◆ board_usb_loop_bulk_in_read()

uint16_t board_usb_loop_bulk_in_read	(	uc_engine *	uc,
		uint8_t	ep,
		uint8_t *	dst,
		uint16_t	cap )

Drain up to cap bulk-IN bytes from a device pipe's staging.

Once the staging is fully drained the device's BEMP for that pipe is raised (transmit buffer empty) so the device firmware can queue the next packet – exactly what the built-in host's echo reader does.

Parameters

[in,out]	uc	Unicorn engine (to pend the device's USB interrupt).
[in]	ep	Device endpoint number (1..9).
[out]	dst	Destination buffer.
[in]	cap	Capacity of `dst` in bytes.

Returns: Number of bytes copied (0 when nothing is staged).

Since: 0.1.0

Return values

value The operation-specific board USB loop bulk in read value.

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

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

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

Definition at line 257 of file board_usb_loop.c.

References board_usb_loop_bulk_in_avail(), internal_usb_word(), k_ra8_int0_bit_bemp, k_ra8_usb_off_bempsts, k_usb_pipe_count, priv_usb_intsts0_set(), priv_usb_raise_irq(), s_loop_bulk_in_pkts, s_loop_pipe_rd, and s_usb.

Referenced by internal_usbhs_cfifo_read().

◆ board_usb_loop_bulk_out()

void board_usb_loop_bulk_out	(	uc_engine *	uc,
		uint8_t	ep,
		const uint8_t *	data,
		uint16_t	len )

Deliver one bulk-OUT packet from the firmware host to a device pipe.

Stages the packet in the device pipe's OUT buffer and raises the pipe's BRDY, mirroring the built-in host's echo path. The device pipe is addressed by ENDPOINT number: the ux_dcd_ra8_usb bridge maps device endpoint n onto controller pipe n, the same fixed mapping the built-in virtual host encodes.

Parameters

[in,out]	uc	Unicorn engine (to pend the device's USB interrupt).
[in]	ep	Device endpoint number (1..9).
[in]	data	Packet bytes.
[in]	len	Packet length (clamped to the pipe staging size).

Returns: Nothing.

Since: 0.1.0

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

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

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

Definition at line 230 of file board_usb_loop.c.

References internal_usb_word(), k_ra8_int0_bit_brdy, k_ra8_usb_off_brdysts, k_usb_pipe_count, memcpy(), priv_usb_intsts0_set(), priv_usb_raise_irq(), s_loop_bulk_out_pkts, and s_usb.

Referenced by internal_usbhs_cfifoctr_write().

◆ board_usb_loop_bus_reset()

void board_usb_loop_bus_reset ( uc_engine * uc )

Deliver a bus reset to the modelled USBFS device (host released RST).

Drops any staged control / bulk data (a bus reset empties the FIFOs), forces the device state to Default, and raises the DVST interrupt so the device firmware re-arms its DCP – the same sequence the built-in virtual host performs at the start of its enumeration.

Parameters

[in,out] uc Unicorn engine (to pend the device's USB interrupt).

Returns: Nothing.

Postcondition: Device DVSQ = Default; stale staging buffers are cleared.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB loop bus reset.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 97 of file board_usb_loop.c.

References internal_loop_reset_dcp(), internal_loop_reset_pipe(), k_ra8_ctsq_idle, k_ra8_dvsq_default, k_ra8_int0_bit_dvst, k_usb_pipe_count, priv_usb_intsts0_set(), priv_usb_log_line(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_usbhs_dvstctr_write().

◆ board_usb_loop_ctrl_in_avail()

uint16_t board_usb_loop_ctrl_in_avail ( void )

Control-IN bytes the device has queued and the host not yet drained.

Returns: Byte count remaining in the device's DCP IN staging (0 when none is committed).

Since: 0.1.0

Control-in bytes the device has queued and the host not yet drained; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

value The operation-specific board USB loop ctrl in avail value.

Precondition: Arguments satisfy the ranges documented for board USB loop ctrl in avail.; The call executes on the emulator's single owning thread.

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

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

Definition at line 174 of file board_usb_loop.c.

References s_loop_dcp_rd, and s_usb.

Referenced by board_usb_loop_ctrl_in_read(), internal_usbhs_brdysts_value(), and internal_usbhs_cfifoctr_value().

◆ board_usb_loop_ctrl_in_flush()

void board_usb_loop_ctrl_in_flush ( void )

Drop whatever remains of the device's control-IN staging.

The host-side equivalent of a DCP read-window BCLR: any undrained response bytes are discarded and the staging is released.

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB loop ctrl in flush.; The call executes on the emulator's single owning thread.

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

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

Definition at line 199 of file board_usb_loop.c.

References s_loop_dcp_rd, and s_usb.

Referenced by internal_usbhs_cfifoctr_write().

◆ board_usb_loop_ctrl_in_read()

uint16_t board_usb_loop_ctrl_in_read	(	uint8_t *	dst,
		uint16_t	cap )

Drain up to cap control-IN bytes from the device's DCP staging.

The host-side read cursor advances; once the staging is fully drained it is released so the device can queue the next response.

Parameters

[out]	dst	Destination buffer.
[in]	cap	Capacity of `dst` in bytes.

Returns: Number of bytes copied (0 when nothing is staged).

Since: 0.1.0

Return values

value The operation-specific board USB loop ctrl in read value.

Precondition: Arguments satisfy the ranges documented for board USB loop ctrl in read.; The call executes on the emulator's single owning thread.

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

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

Definition at line 182 of file board_usb_loop.c.

References board_usb_loop_ctrl_in_avail(), priv_usb_detect_class(), s_loop_dcp_rd, and s_usb.

Referenced by internal_usbhs_cfifo_read().

◆ board_usb_loop_ctrl_out()

void board_usb_loop_ctrl_out	(	uc_engine *	uc,
		const uint8_t *	data,
		uint16_t	len )

Deliver a control-OUT data-stage packet to the device's DCP.

Stages the bytes in the device's DCP OUT buffer and raises the device's DCP BRDY – the packet a device-side ra8_usb_dcp_out_read then drains.

Parameters

[in,out]	uc	Unicorn engine (to pend the device's USB interrupt).
[in]	data	Payload bytes (host to device).
[in]	len	Payload length in bytes (clamped to the staging size).

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB loop ctrl out.; The call executes on the emulator's single owning thread.

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

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

Definition at line 206 of file board_usb_loop.c.

References internal_usb_word(), k_ra8_int0_bit_brdy, k_ra8_usb_dcp_brdy_bit, k_ra8_usb_off_brdysts, memcpy(), priv_usb_intsts0_set(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_usbhs_cfifoctr_write().

◆ board_usb_loop_latch()

void board_usb_loop_latch ( void )

Latch the self-loop: the firmware brought a controller up as HOST.

Called by the USBHS host model when the firmware selects host mode (SYSCFG.DCFM on the HS instance). From then on the bench topology is the loop cable – the firmware host owns the bus – so the built-in virtual host parks for the remainder of the run (its tick returns immediately) instead of competing for the device's control pipe and stealing bulk-IN data. One-way for the run; a later host deinit leaves the cable in place, exactly like the physical bench.

Returns: Nothing.

Postcondition: board_usb_tick is inert; the loop calls below drive the device.

Since: 0.1.0

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

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 83 of file board_usb_loop.c.

References priv_usb_log_line(), and s_loop_latched.

Referenced by board_usb_host_write().

◆ board_usb_loop_setup()

bool board_usb_loop_setup	(	uc_engine *	uc,
		uint16_t	req,
		uint16_t	val,
		uint16_t	indx,
		uint16_t	leng )

Deliver one SETUP packet from the firmware host to the device.

Latches the four SETUP half-words into USBREQ..USBLENG, marks the SETUP valid with the matching control-stage code (CTSQ), and raises the device's CTRT interrupt. SET_ADDRESS is applied SIE-style (USBADDR latch + DVSQ Address + DVST) exactly as the built-in host does; SET_CONFIGURATION arms the configured-state transition for the device's CCPL.

Parameters

[in,out]	uc	Unicorn engine (to pend the device's USB interrupt).
[in]	req	USBREQ word (bmRequestType \| bRequest << 8).
[in]	val	wValue.
[in]	indx	wIndex.
[in]	leng	wLength.

Returns: true when the device SIE completes the whole transfer itself (SET_ADDRESS): the host's status stage needs no device CCPL.

Return values

true	SIE-handled request; treat the status stage as already done.
false	Normal request; the device firmware will end it with CCPL.

Since: 0.1.0

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

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

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

Definition at line 111 of file board_usb_loop.c.

References internal_loop_reset_dcp(), internal_usb_word(), k_loop_req_bm_mask, k_ra8_ctsq_rdds, k_ra8_ctsq_wrds, k_ra8_ctsq_wrnd, k_ra8_dvsq_address, k_ra8_int0_bit_ctrt, k_ra8_int0_bit_dvst, k_ra8_usb_off_usbaddr, k_ra8_usb_off_usbindx, k_ra8_usb_off_usbleng, k_ra8_usb_off_usbreq, k_ra8_usb_off_usbval, k_ra8_usbaddr_addr_mask, k_usb_byte_bits, k_usb_dir_device_to_host, k_usb_dir_host_to_device, k_usb_log_width, k_usb_req_set_address, k_usb_req_set_config, priv_host_take_ccpl(), priv_usb_intsts0_set(), priv_usb_log_line(), priv_usb_raise_irq(), s_loop_pending_cfg, s_loop_setups, and s_usb.

Referenced by internal_usbhs_do_setup().

◆ board_usb_loop_status_out_zlp()

void board_usb_loop_status_out_zlp ( uc_engine * uc )

Run the control-read status stage against the device (host OUT ZLP).

Advances the device's control stage to "read status" and raises CTRT so the device firmware completes the transfer with CCPL – what the host's zero-length status OUT causes on hardware.

Parameters

[in,out] uc Unicorn engine (to pend the device's USB interrupt).

Returns: Nothing.

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB loop status out zlp.; The call executes on the emulator's single owning thread.

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

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

Definition at line 222 of file board_usb_loop.c.

References k_ra8_ctsq_rdss, k_ra8_int0_bit_ctrt, priv_usb_intsts0_set(), priv_usb_raise_irq(), and s_usb.

Referenced by internal_usbhs_do_ccpl().

◆ board_usb_loop_take_ccpl()

bool board_usb_loop_take_ccpl ( uc_engine * uc )

Poll the device's control-transfer completion (DCPCTR.CCPL).

Observes – and consumes – the device firmware's CCPL write, which on hardware makes the device SIE hand the host its status-stage ZLP. When the completed request was SET_CONFIGURATION the device state advances to Configured (DVST raised), mirroring the built-in host's flow.

Parameters

[in,out] uc Unicorn engine (to pend the device's USB interrupt).

Returns: true when the device had asserted CCPL since the last poll.

Return values

true	Transfer complete; the host's status ZLP is available.
false	No completion yet (device firmware still processing).

Since: 0.1.0

Precondition: Arguments satisfy the ranges documented for board USB loop take ccpl.; The call executes on the emulator's single owning thread.

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

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

Definition at line 162 of file board_usb_loop.c.

References priv_host_mark_configured(), priv_host_take_ccpl(), and s_loop_pending_cfg.

Referenced by internal_usbhs_brdysts_value().

◆ board_usb_read()

uint64_t board_usb_read	(	uc_engine *	uc,
		uint64_t	addr,
		unsigned	size,
		bool *	handled )

Dispatch an MMIO read inside the USBFS register window.

Parameters

[in,out]	uc	Unicorn engine (unused today; kept for symmetry).
[in]	addr	Absolute peripheral address being read.
[in]	size	Access width in bytes (1 / 2 / 4).
[out]	handled	True iff `addr` is inside the USBFS window.

Returns: The register value when *handled is true, else 0.

Since: 0.1.0

Dispatch an mmio read inside the usbfs register window; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Return values

value The operation-specific board USB read value.

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

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

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

Definition at line 282 of file board_usb_dev.c.

References board_usbhs_host_reg_read(), k_usb_base, k_usb_span, priv_usb_reg_read(), and s_roles_swapped.

Referenced by board_periph_read().

◆ board_usb_report()

void board_usb_report ( void )

Print the USB section of the end-of-run summary.

Reports each enumeration step taken (host SETUP -> device stage), a clear "USB: device CONFIGURED (CDC-ACM active)" marker when reached, the final device state and USB interrupt count, and – when bulk echo was driven – the OUT / echoed-IN byte totals.

Returns: Nothing.

Since: 0.1.0

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

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

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

Definition at line 250 of file board_usb.c.

References internal_usb_dvsq_name(), priv_emu_io_errf(), priv_usb_class_active_str(), s_configured, s_echo_in_got, s_echo_out_len, s_echo_out_sent, s_hid_buttons, s_hid_cx, s_hid_cy, s_hid_reports, s_log, s_log_n, s_loop_bulk_in_pkts, s_loop_bulk_out_pkts, s_loop_latched, s_loop_setups, s_msc_block_len, s_msc_blocks, s_msc_inquiry_ok, s_msc_read_ok, s_usb, and s_usb_irqs.

Referenced by board_periph_report().

◆ board_usb_roles_swap()

void board_usb_roles_swap ( uc_engine * uc )

Swap the self-loop window<->model bindings (enter Config B).

One-shot and sticky until board_usb_init: migrates the USBHS window's accumulated register shadow out of the host model into the device model (the device firmware's PHY + module-init writes landed there before its role became knowable), resets the host model for its fresh life behind the USBFS window, and retargets the device interrupt at the USBHS ICU event (USBHS_USB_INT_RESUME) instead of USBFS_INT. Idempotent: a second call in the same run is a no-op.

Parameters

[in,out] uc Unicorn engine (unused today; kept for symmetry with the other bridge mutators, which pend device IRQs through it).

Returns: Nothing.

Precondition: board_usb_set_external_host declared the self-loop bridge active.; No USB traffic has crossed the loop yet (both roles still initializing).

Postcondition: board_usb_roles_swapped reports true.; The device model raises the USBHS interrupt event from now on.

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usb_roles_swapped

Since: 0.1.0

Definition at line 44 of file board_usb_bridge.c.

References board_usbhs_host_shadow_handoff(), g_dev_irq_event, k_ra8_elc_event_usbhs_int_resume, k_usb_reg_words, priv_usb_log_line(), s_roles_swapped, and s_usb.

Referenced by board_usb_write(), and internal_usbhs_block_write().

◆ board_usb_roles_swapped()

bool board_usb_roles_swapped ( void )

Whether the self-loop window roles are swapped (Config B).

false (default): USBFS window = device model, USBHS window = host model (Config A). true: the firmware declared the opposite polarity (FS SYSCFG.DCFM=1 or HS SYSCFG.DPRPU=1), so the USBFS window routes to the host model and the USBHS window routes to the device model (Config B).

Returns: true when the bindings are swapped for this run.

Precondition: None; safe at any time (reset to false by board_usb_init).

Postcondition: No model state is modified (read-only accessor).

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usb_roles_swap

Since: 0.1.0

Return values

true	The board USB roles swapped condition holds or completed successfully; false otherwise.

Precondition: The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 39 of file board_usb_bridge.c.

References s_roles_swapped.

Referenced by internal_usbhs_block_read(), internal_usbhs_block_write(), and internal_usbhs_report().

◆ board_usb_set_external_host()

void board_usb_set_external_host ( bool present )

Declare (or withdraw) a real-firmware USB host driving the device.

When present is true the built-in virtual chapter-9 host stops driving the device from board_usb_tick, because the emulated USBHS host controller (board_periph_usbhs_host.c) now enumerates and talks to the device through the bridge primitives below. Set once at startup for a self-loop app.

Parameters

[in] present true to hand the device over to the external host bridge.

Returns: Nothing.

Postcondition: board_usb_tick no longer advances the built-in virtual host.

Since: 0.1.0

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

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 34 of file board_usb_bridge.c.

References s_external_host.

Referenced by internal_main_bringup_peripherals().

◆ board_usb_set_irq_raiser()

void board_usb_set_irq_raiser ( board_usb_irq_raiser_t raise )

Install the ICU event-raise hook used to pend the USBFS interrupt.

Parameters

[in] raise Callback board_periph supplies to assert an ELC event, or NULL to detach (the host then cannot raise USB IRQs).

Returns: Nothing.

Postcondition: Subsequent host steps raise USBFS_INT through raise.

Since: 0.1.0

Install the icu event-raise hook used to pend the usbfs interrupt; this step is contained within the board USB model and uses bounded caller or module-owned storage.

Precondition: Arguments satisfy the ranges documented for board USB set interrupt raiser.; The call executes on the emulator's single owning thread.

Postcondition: Ownership of caller-supplied storage is unchanged.

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

Definition at line 186 of file board_usb.c.

References s_raise.

Referenced by board_periph_init().

◆ board_usb_state_string()

const char * board_usb_state_string ( void )

One-line, human-readable USB device state for the board view.

Returns a short static string describing the live enumeration state of the modelled USBFS device – the INTSTS0.DVSQ stage name ("Powered" / "Default" / "Address" / "Configured" / "Suspended"), upgraded to "CONFIGURED (CDC-ACM active)" once SET_CONFIGURATION has completed and USBX's CDC-ACM activate callback has fired. ra8_emulator's graphical board view shows this verbatim on its "USB:" status line so a non-display USB example (e.g. threadx_usbx_cdc_demo) is observable as it enumerates. The returned pointer is to static storage and must not be freed; it is valid until the next call.

Returns: NUL-terminated state string (never NULL).

Since: 0.1.0

Definition at line 228 of file board_usb.c.

References internal_usb_dvsq_name(), k_usb_class_cdc, k_usb_class_hid, k_usb_class_msc, k_usb_class_printer, k_usb_class_unknown, k_usb_class_vendor, s_configured, s_dev_class, and s_usb.

Referenced by internal_fill_status_hw().

◆ board_usb_tick()

void board_usb_tick ( uc_engine * uc )

Advance the virtual USB host one emulation chunk.

Stepped once per run-loop chunk (the SysTick cadence). The host polls for the device pull-up, performs the bus reset, and clocks the chapter-9 SETUP sequence forward one micro-step per call – delivering a SETUP and raising CTRT, waiting for the device's descriptor response or status-stage completion, then advancing. Idle once the device is configured (and, with bulk data queued, while echo traffic is in flight).

Parameters

[in,out] uc Unicorn engine (the model reads back the device's CFIFO / DCPCTR writes from its own state and pends the USB IRQ through the installed raiser).

Returns: Nothing.

Since: 0.1.0

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

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

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

Definition at line 116 of file board_usb.c.

References k_phase_configured, k_phase_done, k_phase_idle, k_phase_reset, k_phase_setup, k_ra8_dvsq_configured, priv_bridge_pump_device(), priv_host_echo_read_in(), priv_host_run_configured_phase(), priv_host_run_idle_phase(), priv_host_run_reset_phase(), priv_host_run_setup_phase(), s_configured, s_external_host, s_host_phase, s_loop_latched, and s_usb.

Referenced by board_periph_tick().

◆ board_usb_write()

void board_usb_write	(	uc_engine *	uc,
		uint64_t	addr,
		unsigned	size,
		uint64_t	value,
		bool *	handled )

Dispatch an MMIO write inside the USBFS register window.

Parameters

[in,out]	uc	Unicorn engine (unused today; kept for symmetry).
[in]	addr	Absolute peripheral address being written.
[in]	size	Access width in bytes (1 / 2 / 4).
[in]	value	Value being written.
[out]	handled	True iff `addr` is inside the USBFS window.

Returns: Nothing.

Since: 0.1.0

Dispatch an mmio write inside the usbfs register window; this step is contained within the board USB model and uses bounded caller or module-owned storage.

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

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

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

Definition at line 297 of file board_usb_dev.c.

References board_usb_roles_swap(), board_usbhs_host_reg_write(), k_ra8_syscfg_bit_dcfm, k_ra8_usb_off_syscfg, k_usb_base, k_usb_span, priv_usb_reg_write(), s_external_host, and s_roles_swapped.

Referenced by board_periph_write().

◆ board_usbhs_host_reg_read()

uint64_t board_usbhs_host_reg_read	(	uc_engine *	uc,
		uint64_t	off,
		unsigned	size )

Host-model register read by window byte offset (role routing).

Exported by board_periph_usbhs_host.c so the USBFS window claim in board_usb.c can route its reads into the host model when the roles are swapped (Config B: the polled ra8_usb_host_* driver runs on the USBFS controller).

Parameters

[in,out]	uc	Unicorn engine (bulk/control latching pends device IRQs).
[in]	off	Byte offset inside the controller register window.
[in]	size	Access width in bytes (1, 2 or 4).

Returns: The register value, zero-extended to 64 bits.

Precondition: off is inside the host model's 0x200-byte register span.; The self-loop bridge is active (–usbhs-loop).

Postcondition: Read side effects (status latch, FIFO cursors) match the host model's.

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usbhs_host_reg_write

Since: 0.1.0

Return values

value The operation-specific board usbhs host reg read value.

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 818 of file board_periph_usbhs_host.c.

References internal_hs_read().

Referenced by board_usb_read().

◆ board_usbhs_host_reg_write()

void board_usbhs_host_reg_write	(	uc_engine *	uc,
		uint64_t	off,
		unsigned	size,
		uint64_t	value )

Host-model register write by window byte offset (role routing).

Exported by board_periph_usbhs_host.c so the USBFS window claim in board_usb.c can route its writes into the host model when the roles are swapped (Config B).

Parameters

[in,out]	uc	Unicorn engine (transfer launches drive the device model).
[in]	off	Byte offset inside the controller register window.
[in]	size	Access width in bytes (1, 2 or 4).
[in]	value	Value the firmware wrote.

Returns: Nothing.

Precondition: off is inside the host model's 0x200-byte register span.; The self-loop bridge is active (–usbhs-loop).

Postcondition: Write side effects (SETUP launch, FIFO commits) match the host model's.

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usbhs_host_reg_read

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 823 of file board_periph_usbhs_host.c.

References internal_hs_write().

Referenced by board_usb_write().

◆ board_usbhs_host_shadow_handoff()

uint32_t board_usbhs_host_shadow_handoff	(	uint16_t *	dst_words,
		uint32_t	word_capacity )

Hand the host model's register shadow off and reset the host model.

Role-swap migration primitive (board_periph_usbhs_host.c): copies up to word_capacity 16-bit shadow words – the USBHS window's accumulated writes, i.e. the device firmware's PHY + module-init register state – into dst_words, then resets the entire host model so it starts virgin behind the USBFS window. Called exactly once, by board_usb_roles_swap.

Parameters

[out]	dst_words	Destination for the 16-bit shadow words.
[in]	word_capacity	Capacity of `dst_words` in 16-bit words.

Returns: The number of 16-bit words copied.

Precondition: dst_words is non-NULL with room for word_capacity words.; No host-side USB traffic has occurred yet (bring-up phase only).

Postcondition: The host model is fully reset (power-on state).

Note: Not thread-safe; single-threaded emulation loop use.

See also: board_usb_roles_swap

Since: 0.1.0

Return values

value The operation-specific board usbhs host shadow handoff value.

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 828 of file board_periph_usbhs_host.c.

References k_usbhs_dev_span, k_usbhs_words, memcpy(), and s_hs.

Referenced by board_usb_roles_swap().

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ board_usb_irq_raiser_t

Function Documentation

◆ board_usb_bridge_bulk_in_ready()

◆ board_usb_bridge_bulk_in_take()

◆ board_usb_bridge_bulk_out()

◆ board_usb_bridge_bulk_out_consumed()

◆ board_usb_bridge_bus_reset()

◆ board_usb_bridge_ctrl_status()

◆ board_usb_bridge_dcp_in_ready()

◆ board_usb_bridge_dcp_in_take()

◆ board_usb_bridge_dcp_out()

◆ board_usb_bridge_dcp_out_consumed()

◆ board_usb_bridge_deliver_setup()

◆ board_usb_bridge_dev_took_ccpl()

◆ board_usb_bridge_mark_configured()

◆ board_usb_configured()

◆ board_usb_dev_attached()

◆ board_usb_dev_reg_read()

◆ board_usb_dev_reg_write()

◆ board_usb_echo_received()

◆ board_usb_feed_bulk_in()

◆ board_usb_init()

◆ board_usb_loop_attached()

◆ board_usb_loop_bulk_in_avail()

◆ board_usb_loop_bulk_in_flush()

◆ board_usb_loop_bulk_in_read()

◆ board_usb_loop_bulk_out()

◆ board_usb_loop_bus_reset()

◆ board_usb_loop_ctrl_in_avail()

◆ board_usb_loop_ctrl_in_flush()

◆ board_usb_loop_ctrl_in_read()

◆ board_usb_loop_ctrl_out()

◆ board_usb_loop_latch()

◆ board_usb_loop_setup()

◆ board_usb_loop_status_out_zlp()

◆ board_usb_loop_take_ccpl()

◆ board_usb_read()

◆ board_usb_report()

◆ board_usb_roles_swap()

◆ board_usb_roles_swapped()

◆ board_usb_set_external_host()

◆ board_usb_set_irq_raiser()

◆ board_usb_state_string()

◆ board_usb_tick()

◆ board_usb_write()

◆ board_usbhs_host_reg_read()

◆ board_usbhs_host_reg_write()

◆ board_usbhs_host_shadow_handoff()