USBFS controller model + virtual USB host (chapter-9 enumeration). More...

#include "board_usb.h"
#include <stdio.h>
#include <string.h>
#include "board_console.h"
#include "board_usb_internal.h"
#include "emu_host_io_internal.h"
#include "ra8_elc_regs.h"
#include "ra8_usb_regs.h"

Include dependency graph for board_usb.c:

Functions
void	priv_usb_log_line (const char *msg)
	Append one already-formatted line to the enumeration-step log.
void	priv_usb_log_count (const char *label, unsigned n)
	Append a "<label>: <n> byte(s)"-style line built from one count.
void	board_usb_tick (uc_engine *uc)
	Advance the virtual USB host one emulation chunk.
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.
bool	board_usb_configured (void)
	Report whether enumeration reached the CONFIGURED state.
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.
static const char *	internal_usb_dvsq_name (uint16_t dvsq)
	Print the device-state name for the report line.
const char *	board_usb_state_string (void)
	One-line, human-readable USB device state for the board view.
void	board_usb_report (void)
	Print the USB section of the end-of-run summary.

Variables
usb_state_t	s_usb
	Controller + FIFO state (core).
bool	s_trace
	–trace verbose logging (core).
board_usb_irq_raiser_t	s_raise
	ICU pend callback (core).
bool	s_external_host
	Bridge host owns the bus (core).
bool	s_roles_swapped
	Self-loop role polarity (core).
uint16_t	g_dev_irq_event = (uint16_t)k_ra8_elc_event_usbfs_int
	Device ICU event number (core).
uint8_t	s_dcp_hold [k_usb_in_cap]
	Held control-OUT wire bytes.
uint16_t	s_dcp_hold_len
	Held byte count.
bool	s_dcp_hold_pending
	Held bytes await the device arm.
uint8_t	s_host_phase
	Current host state-machine phase.
uint8_t	s_host_step
	Index into the enumeration script.
uint8_t	s_host_substate
	Sub-state within one SETUP step.
uint32_t	s_host_wait
	Ticks spent waiting in a sub-state.
bool	s_configured
	Device reached CONFIGURED.
uint32_t	s_usb_irqs
	USB interrupts the host raised.
uint8_t	s_echo_out [k_usb_echo_cap]
	Host bulk-OUT payload.
uint32_t	s_echo_out_len
	Bytes queued by –usb-in.
uint32_t	s_echo_out_sent
	Bytes delivered to device.
uint32_t	s_echo_in_got
	Echoed bytes read back.
static char	s_log [k_usb_log_cap][k_usb_log_width]
static uint32_t	s_log_n

Detailed Description

USBFS controller model + virtual USB host (chapter-9 enumeration).

Implements the model declared in board_usb.h. The RA8D2 USBFS controller (base 0x40250000, HUM Ch 36) is modelled register-by-register with real staging buffers for the control (DCP) and bulk pipe FIFOs, and a virtual USB host walks the standard chapter-9 enumeration against the real device-side firmware (port/usbx/ux_dcd_ra8_usb -> ra8_usb*.c). The host delivers each SETUP by latching USBREQ..USBLENG and raising the controller's CTRT interrupt through board_periph's ICU -> NVIC path, then drains the descriptor bytes the device pushes into the CFIFO and advances the device state machine (DVSQ powered -> default -> address -> configured) until USBX activates its CDC-ACM class.

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

Since: 0.1.0

Definition in file board_usb.c.

Function Documentation

◆ 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_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_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_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.