USBX host-controller-driver bridge to ra8_usb – implementation. More...

#include "ux_hcd_ra8_usb.h"
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_log.h"
#include "ux_api.h"

Include dependency graph for ux_hcd_ra8_usb.c:

Data Structures
struct	ra8_usb_hcd_t
	Bridge-singleton state. More...

Macros
#define	UX_SOURCE_CODE

Enumerations
enum	ra8_usb_hcd_ep_addr_field_t : uint8_t { k_ra8_usb_hcd_ep_addr_dir_in_bit = 0x80U , k_ra8_usb_hcd_ep_addr_num_mask = 0x0FU }
	Bit fields of a USB endpoint address (bEndpointAddress). More...
enum	ra8_usb_hcd_pipe_t : uint8_t { k_ra8_usb_hcd_pipe_count = 10U }
	Pipe-index bounds for the host bridge. More...
enum	ra8_usb_hcd_ctrl_id_t : uint8_t { k_ra8_usb_hcd_controller_id = 99U }
	Private USBX controller-type id reported by this HCD bridge. More...

Functions
static uint8_t	internal_ep_to_pipe (uint8_t ep_addr)
	Ep to pipe.
static unsigned int	internal_endpoint_create (struct UX_ENDPOINT_STRUCT *ep)
	Endpoint create.
static unsigned int	internal_control_xfer (struct UX_TRANSFER_STRUCT *tr)
	Drive the EP0 control transfer SETUP + optional data stage.
static unsigned int	internal_bulk_xfer (struct UX_TRANSFER_STRUCT *tr, uint8_t ep_addr, uint8_t pipe)
	Drive a bulk / interrupt transfer on a non-EP0 pipe.
static unsigned int	internal_transfer_request (struct UX_TRANSFER_STRUCT *tr)
	Transfer request.
static unsigned int	internal_port_reset (void)
	Pulse the root-hub port reset (assert then deassert).
static unsigned int	internal_port_set_enabled (bool enable)
	Enable or disable the root-hub port via DVSTCTR0.UACT.
unsigned int	_ux_hcd_ra8_usb_function (struct UX_HCD_STRUCT hcd, unsigned int function, void parameter)
	USBX host-side HCD function dispatcher.
ra8_err_t	ux_hcd_ra8_usb_initialize (ra8_usb_speed_t speed)
	Ux hcd ra usb initialize.
ra8_err_t	ux_hcd_ra8_usb_uninitialize (void)
	Ux hcd ra usb uninitialize.
ra8_usb_hcd_state_t	ux_hcd_ra8_usb_state (void)
	Ux hcd ra usb state.

Variables
static const char *const	s_tag = "ux_hcd_ra8_usb"
static ra8_usb_hcd_t	s_hcd
	Bridge instance.

Detailed Description

USBX host-controller-driver bridge to ra8_usb – implementation.

Tag: [Ring 5 / PORT] {World: S}

Counterpart to ux_dcd_ra8_usb.c: routes USBX host-stack dispatch into the ra8_usb_host_* register-level driver. Mirrors the surface of upstream USBX HCD ports (e.g. ux_hcd_ehci_entry).

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

Since: 0.1.0

Definition in file ux_hcd_ra8_usb.c.

Macro Definition Documentation

◆ UX_SOURCE_CODE

#define UX_SOURCE_CODE

Definition at line 19 of file ux_hcd_ra8_usb.c.

Enumeration Type Documentation

◆ ra8_usb_hcd_ctrl_id_t

enum ra8_usb_hcd_ctrl_id_t : uint8_t

Private USBX controller-type id reported by this HCD bridge.

Enumerator
k_ra8_usb_hcd_controller_id	RA-USB private controller id.

Definition at line 83 of file ux_hcd_ra8_usb.c.

◆ ra8_usb_hcd_ep_addr_field_t

enum ra8_usb_hcd_ep_addr_field_t : uint8_t

Bit fields of a USB endpoint address (bEndpointAddress).

USB 2.0 sec 9.6.6: bit 7 is the direction bit (1 = IN) and bits 3:0 carry the endpoint number. The same direction bit also appears as bit 7 of bmRequestType in a SETUP packet (USB 2.0 sec 9.3).

Enumerator
k_ra8_usb_hcd_ep_addr_dir_in_bit	Direction bit set => IN.
k_ra8_usb_hcd_ep_addr_num_mask	Endpoint-number field (bits 3:0).

Definition at line 62 of file ux_hcd_ra8_usb.c.

◆ ra8_usb_hcd_pipe_t

enum ra8_usb_hcd_pipe_t : uint8_t

Pipe-index bounds for the host bridge.

Hardware exposes the DCP (pipe 0) plus PIPE1..PIPE9, so a valid pipe index is 0..9; the value 10 is both the count of valid pipes and the out-of-range sentinel returned by internal_ep_to_pipe.

Enumerator
k_ra8_usb_hcd_pipe_count	Valid pipes 0..9; 10 == out-of-range.

Definition at line 75 of file ux_hcd_ra8_usb.c.

Function Documentation

◆ _ux_hcd_ra8_usb_function()

unsigned int _ux_hcd_ra8_usb_function	(	struct UX_HCD_STRUCT *	hcd,
		unsigned int	function,
		void *	parameter )

USBX host-side HCD function dispatcher.

ux hcd ra usb function.

Stamped into UX_HCD::ux_hcd_entry_function during ux_hcd_ra8_usb_initialize. The USBX host stack calls this with a UX_HCD_* selector to request endpoint create/destroy/reset, transfer request, transfer abort, and root-hub port management (reset / enable / disable). The trampoline routes each selector to the matching internal_* helper.

Parameters

[in,out]	hcd	USBX HCD ownership block (currently unused; the bridge keeps its own static state in s_hcd).
[in]	function	USBX UX_HCD_* selector (e.g. UX_HCD_TRANSFER_REQUEST, UX_HCD_RESET_PORT).
[in,out]	parameter	Selector-dependent argument (UX_TRANSFER* / UX_ENDPOINT* / opaque).

Returns: USBX result code from the dispatched helper.

Return values

UX_SUCCESS	Function handled.
UX_CONTROLLER_UNKNOWN	Bridge has not been initialized.
UX_ERROR	Selector unsupported, or helper rejected the call.

Precondition: Bridge is past ux_hcd_ra8_usb_initialize (or call returns UX_CONTROLLER_UNKNOWN).; Caller is the USBX host stack.

Postcondition: s_hcd updated per the dispatched selector.; Wire-side state may have been mutated (port reset / UACT toggle).

Note: Runs on the USBX host task context; not ISR-safe.

Since: 0.1.0

Definition at line 427 of file ux_hcd_ra8_usb.c.

References internal_endpoint_create(), internal_port_reset(), internal_port_set_enabled(), internal_transfer_request(), k_ux_hcd_ra8_usb_state_uninit, and s_hcd.

Referenced by ux_hcd_ra8_usb_initialize().

◆ internal_bulk_xfer()

unsigned int internal_bulk_xfer	(	struct UX_TRANSFER_STRUCT *	tr,
		uint8_t	ep_addr,
		uint8_t	pipe )

static

Drive a bulk / interrupt transfer on a non-EP0 pipe.

IN endpoints (ep_addr & 0x80U) read from the device and fill the caller buffer via ra8_usb_queue_out (the host-side OUT direction is "data flowing out of the chip into caller memory"). OUT endpoints write caller bytes to the device via ra8_usb_queue_in.

Parameters

[in,out]	tr	USBX transfer request.
[in]	ep_addr	Endpoint address (bit 7 = direction).
[in]	pipe	Pipe index in 1..9.

Returns: UX_SUCCESS or UX_TRANSFER_ERROR.

Return values

UX_SUCCESS	Bytes queued; actual_length updated.
UX_TRANSFER_ERROR	Underlying queue call failed.

Precondition: tr non-null with a valid data pointer.; pipe in 1..9 (caller already filtered EP0 / out-of-range).

Postcondition: actual_length reflects bytes queued on success.; No state change on failure.

Note: Runs on the USBX host task context.

Since: 0.1.0

Definition at line 269 of file ux_hcd_ra8_usb.c.

References k_ra8_ok, k_ra8_usb_hcd_ep_addr_dir_in_bit, ra8_usb_queue_in(), ra8_usb_queue_out(), and s_hcd.

Referenced by internal_transfer_request().

◆ internal_control_xfer()

unsigned int internal_control_xfer ( struct UX_TRANSFER_STRUCT * tr )

static

Drive the EP0 control transfer SETUP + optional data stage.

Builds an ra8_usb_setup_t from the USBX transfer request, fires the SETUP token via ra8_usb_host_setup_request, then for the optional data stage routes IN (D2H) through ra8_usb_queue_out (chip reads from device, fills caller buffer) and OUT (H2D) through ra8_usb_queue_in (chip writes caller buffer onto wire).

Parameters

[in,out] tr USBX EP0 control transfer request.

Returns: UX_SUCCESS on accept, UX_TRANSFER_ERROR if the SIE rejected the token or the data-stage queue failed.

Return values

UX_SUCCESS	Token accepted; data stage (if any) queued.
UX_TRANSFER_ERROR	ra8_usb_host_setup_request or queue failed.

Precondition: tr is non-null and points to an EP0 transfer.; HCD bridge is past ux_hcd_ra8_usb_initialize.

Postcondition: On success ux_transfer_request_actual_length reflects bytes queued for the data stage.; On failure the wire state is left to the controller's recovery (status-stage NAK / STALL).

Note: Runs on the USBX host task context.

Since: 0.1.0

Definition at line 212 of file ux_hcd_ra8_usb.c.

References ra8_usb_setup_t::bm_request_type, k_ra8_ok, k_ra8_usb_hcd_ep_addr_dir_in_bit, RA8_INTERNAL, ra8_usb_host_setup_request(), ra8_usb_queue_in(), ra8_usb_queue_out(), and s_hcd.

Referenced by internal_transfer_request().

◆ internal_endpoint_create()

unsigned int internal_endpoint_create ( struct UX_ENDPOINT_STRUCT * ep )

static

Endpoint create.

See implementation for details.

Parameters

[in,out] ep See function signature for type and usage.

Returns: Result code or value; see implementation.

Return values

0	Success or default value.

Precondition: Caller has validated arguments.; Module has been initialized.

Postcondition: Side effects bounded to documented state.; Returned value reflects current state.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 141 of file ux_hcd_ra8_usb.c.

References internal_ep_to_pipe(), k_ra8_ok, k_ra8_usb_ep_dir_in, k_ra8_usb_ep_dir_out, k_ra8_usb_ep_type_bulk, k_ra8_usb_ep_type_intr, k_ra8_usb_ep_type_iso, k_ra8_usb_hcd_ep_addr_dir_in_bit, k_ra8_usb_hcd_ep_addr_num_mask, k_ra8_usb_hcd_pipe_count, RA8_INTERNAL, ra8_usb_configure_endpoint(), and s_hcd.

Referenced by _ux_hcd_ra8_usb_function().

◆ internal_ep_to_pipe()

uint8_t internal_ep_to_pipe ( uint8_t ep_addr )

static

Ep to pipe.

See implementation for details.

Parameters

[in,out] ep_addr See function signature for type and usage.

Returns: Result code or value; see implementation.

Return values

0	Success or default value.

Precondition: Caller has validated arguments.; Module has been initialized.

Postcondition: Side effects bounded to documented state.; Returned value reflects current state.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 110 of file ux_hcd_ra8_usb.c.

References k_ra8_usb_hcd_ep_addr_num_mask, k_ra8_usb_hcd_pipe_count, and RA8_INTERNAL.

Referenced by internal_endpoint_create(), and internal_transfer_request().

◆ internal_port_reset()

unsigned int internal_port_reset ( void )

static

Pulse the root-hub port reset (assert then deassert).

USBX leaves the spec-required 10 ms hold between the assert and deassert edges to the caller (it issues two separate UX_HCD_RESET_PORT calls with the hold in between for some hosts, or expects the HCD to short-circuit it for others). Here we just trampoline both edges into ra8_usb_host_bus_reset.

Returns: UX_SUCCESS or UX_ERROR.

Return values

UX_SUCCESS	Both edges accepted.
UX_ERROR	Either edge rejected by the controller.

Precondition: HCD bridge is past ux_hcd_ra8_usb_initialize.; Caller observes the USB 2.0 timing requirements.

Postcondition: Bus reset signalling has completed on the wire.; No bridge-side state mutated.

Note: Runs on the USBX host task context.

Since: 0.1.0

Definition at line 351 of file ux_hcd_ra8_usb.c.

References k_ra8_ok, RA8_INTERNAL, ra8_usb_host_bus_reset(), and s_hcd.

Referenced by _ux_hcd_ra8_usb_function().

◆ internal_port_set_enabled()

unsigned int internal_port_set_enabled ( bool enable )

static

Enable or disable the root-hub port via DVSTCTR0.UACT.

Wraps ra8_usb_host_set_uact so the dispatcher's enable/disable cases collapse to a one-line call. On enable the bridge moves into active; on disable it returns to ready.

Parameters

[in] enable True to assert UACT (SOF generation, downstream bus activity), false to deassert.

Returns: UX_SUCCESS or UX_ERROR.

Return values

UX_SUCCESS	UACT toggled and state updated.
UX_ERROR	ra8_usb_host_set_uact rejected the change.

Precondition: HCD bridge is past ux_hcd_ra8_usb_initialize.; Caller serializes port-state mutations.

Postcondition: s_hcd.state reflects the new enable bit on success.; Wire is gated by UACT after this returns.

Note: Runs on the USBX host task context.

Since: 0.1.0

Definition at line 384 of file ux_hcd_ra8_usb.c.

References k_ra8_ok, k_ux_hcd_ra8_usb_state_active, k_ux_hcd_ra8_usb_state_ready, RA8_INTERNAL, ra8_usb_host_set_uact(), and s_hcd.

Referenced by _ux_hcd_ra8_usb_function().

◆ internal_transfer_request()

unsigned int internal_transfer_request ( struct UX_TRANSFER_STRUCT * tr )

static

Transfer request.

See implementation for details.

Parameters

[in,out] tr See function signature for type and usage.

Returns: Result code or value; see implementation.

Return values

0	Success or default value.

Precondition: Caller has validated arguments.; Module has been initialized.

Postcondition: Side effects bounded to documented state.; Returned value reflects current state.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 308 of file ux_hcd_ra8_usb.c.

References internal_bulk_xfer(), internal_control_xfer(), internal_ep_to_pipe(), k_ra8_usb_hcd_pipe_count, and RA8_INTERNAL.

Referenced by _ux_hcd_ra8_usb_function().

◆ ux_hcd_ra8_usb_initialize()

ra8_err_t ux_hcd_ra8_usb_initialize ( ra8_usb_speed_t speed )

nodiscard

Ux hcd ra usb initialize.

Register the ra8_usb host bridge as the active USBX HCD.

See implementation for details.

Parameters

[in,out] speed See function signature for type and usage.

Returns: Result code or value; see implementation.

Return values

0	Success or default value.

Precondition: Caller has validated arguments.; Module has been initialized.

Postcondition: Side effects bounded to documented state.; Returned value reflects current state.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 501 of file ux_hcd_ra8_usb.c.

References _ux_hcd_ra8_usb_function(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_ok, k_ra8_usb_hcd_controller_id, k_ra8_usb_speed_hs, k_ux_hcd_ra8_usb_state_ready, ra8_log_info, RA8_RETURN_ON_ERROR, ra8_usb_host_init(), s_hcd, and s_tag.

◆ ux_hcd_ra8_usb_state()

ra8_usb_hcd_state_t ux_hcd_ra8_usb_state ( void )

Ux hcd ra usb state.

Read the bridge run-state.

See implementation for details.

Returns: Result code or value; see implementation.

Return values

0	Success or default value.

Precondition: Caller has validated arguments.; Module has been initialized.

Postcondition: Side effects bounded to documented state.; Returned value reflects current state.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 586 of file ux_hcd_ra8_usb.c.

References s_hcd.

◆ ux_hcd_ra8_usb_uninitialize()

ra8_err_t ux_hcd_ra8_usb_uninitialize ( void )

nodiscard

Ux hcd ra usb uninitialize.

Tear down the ra8_usb HCD bridge.

See implementation for details.

Returns: Result code or value; see implementation.

Return values

0	Success or default value.

Precondition: Caller has validated arguments.; Module has been initialized.

Postcondition: Side effects bounded to documented state.; Returned value reflects current state.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 553 of file ux_hcd_ra8_usb.c.

References k_ra8_err_invalid_state, k_ra8_ok, k_ux_hcd_ra8_usb_state_uninit, ra8_usb_host_deinit(), ra8_usb_host_set_uact(), and s_hcd.

Variable Documentation

◆ s_hcd

ra8_usb_hcd_t s_hcd

static

Initial value:

                           = {
  .state = k_ux_hcd_ra8_usb_state_uninit,
  .speed = k_ra8_usb_speed_fs,
  .owner = nullptr,
}

Bridge instance.

RA8 has two USB controllers but USBX only ever drives one root-hub-style host at a time in this app.

Definition at line 48 of file ux_hcd_ra8_usb.c.

Referenced by _ux_hcd_ra8_usb_function(), internal_bulk_xfer(), internal_control_xfer(), internal_endpoint_create(), internal_port_reset(), internal_port_set_enabled(), ux_hcd_ra8_usb_initialize(), ux_hcd_ra8_usb_state(), and ux_hcd_ra8_usb_uninitialize().

◆ s_tag

const char* const s_tag = "ux_hcd_ra8_usb"

static

Definition at line 31 of file ux_hcd_ra8_usb.c.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ UX_SOURCE_CODE

Enumeration Type Documentation

◆ ra8_usb_hcd_ctrl_id_t

◆ ra8_usb_hcd_ep_addr_field_t

◆ ra8_usb_hcd_pipe_t

Function Documentation

◆ _ux_hcd_ra8_usb_function()

◆ internal_bulk_xfer()

◆ internal_control_xfer()

◆ internal_endpoint_create()

◆ internal_ep_to_pipe()

◆ internal_port_reset()

◆ internal_port_set_enabled()

◆ internal_transfer_request()

◆ ux_hcd_ra8_usb_initialize()

◆ ux_hcd_ra8_usb_state()

◆ ux_hcd_ra8_usb_uninitialize()

Variable Documentation

◆ s_hcd

◆ s_tag