ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ux_hcd_ra8_usb.h File Reference

USBX host-controller-driver (HCD) bridge to ra8_usb. More...

#include "ra8_usb.h"
Include dependency graph for ux_hcd_ra8_usb.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Enumerations

enum  ra8_usb_hcd_state_t : uint8_t {
  k_ux_hcd_ra8_usb_state_uninit = 0U ,
  k_ux_hcd_ra8_usb_state_ready = 1U ,
  k_ux_hcd_ra8_usb_state_active = 2U
}
 Run-state of the HCD bridge. More...

Functions

ra8_err_t ux_hcd_ra8_usb_initialize (ra8_usb_speed_t speed)
 Register the ra8_usb host bridge as the active USBX HCD.
ra8_err_t ux_hcd_ra8_usb_uninitialize (void)
 Tear down the ra8_usb HCD bridge.
ra8_usb_hcd_state_t ux_hcd_ra8_usb_state (void)
 Read the bridge run-state.
unsigned int _ux_hcd_ra8_usb_function (struct UX_HCD_STRUCT *hcd, unsigned int function, void *parameter)
 ux hcd ra usb function.

Detailed Description

USBX host-controller-driver (HCD) bridge to ra8_usb.

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

Plumbs Eclipse USBX's host stack onto the project's hand-written ra8_usb_* register-level driver in host mode (libs/ra8_hal/inc/ra8_usb.h – ra8_usb_host_init / ra8_usb_host_setup_request / etc.). The shim implements the dispatch contract that USBX expects to find behind UX_HCD::ux_hcd_entry_function.

Surface

The dispatch table _ux_hcd_ra8_usb_function switches on the UX_HCD_* command codes:

  • UX_HCD_CREATE_ENDPOINT -> ra8_usb_configure_endpoint
  • UX_HCD_DESTROY_ENDPOINT -> NAK pipe
  • UX_HCD_TRANSFER_REQUEST -> ra8_usb_host_setup_request / ra8_usb_queue_in / ra8_usb_queue_out
  • UX_HCD_TRANSFER_ABORT -> NAK pipe
  • UX_HCD_RESET_PORT -> ra8_usb_host_bus_reset
  • UX_HCD_ENABLE_PORT -> ra8_usb_host_set_uact(true)
  • UX_HCD_DISABLE_PORT -> ra8_usb_host_set_uact(false)
  • UX_HCD_GET_PORT_STATUS -> read SYSSTS0
Copyright
Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT
Since
0.1.0

Definition in file ux_hcd_ra8_usb.h.

Enumeration Type Documentation

◆ ra8_usb_hcd_state_t

enum ra8_usb_hcd_state_t : uint8_t

Run-state of the HCD bridge.

Enumerator
k_ux_hcd_ra8_usb_state_uninit 

Bridge not yet initialized.

k_ux_hcd_ra8_usb_state_ready 

Bridge installed; bus idle.

k_ux_hcd_ra8_usb_state_active 

SOF generation enabled.

Definition at line 57 of file ux_hcd_ra8_usb.h.

Function Documentation

◆ _ux_hcd_ra8_usb_function()

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

ux hcd ra usb function.

See implementation for details.

Parameters
[in,out]hcdSee function signature for type and usage.
[in,out]functionSee function signature for type and usage.
[in,out]parameterSee function signature for type and usage.
Returns
Result code or value; see implementation.
Return values
0Success 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

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]hcdUSBX HCD ownership block (currently unused; the bridge keeps its own static state in s_hcd).
[in]functionUSBX UX_HCD_* selector (e.g. UX_HCD_TRANSFER_REQUEST, UX_HCD_RESET_PORT).
[in,out]parameterSelector-dependent argument (UX_TRANSFER* / UX_ENDPOINT* / opaque).
Returns
USBX result code from the dispatched helper.
Return values
UX_SUCCESSFunction handled.
UX_CONTROLLER_UNKNOWNBridge has not been initialized.
UX_ERRORSelector 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().

◆ ux_hcd_ra8_usb_initialize()

ra8_err_t ux_hcd_ra8_usb_initialize ( ra8_usb_speed_t speed)
nodiscard

Register the ra8_usb host bridge as the active USBX HCD.

Wraps ra8_usb_host_init and registers a UX_HCD entry into the USBX host system table so subsequent ux_host_class_*_register calls find this bridge.

Parameters
[in]speedWhich controller (FS or HS).
Returns
ra8_err_t error code.
Return values
k_ra8_okHCD installed; bus idle (UACT=0).
k_ra8_err_invalid_argspeed out of range.
k_ra8_err_hw_init_failedra8_usb_host_init failed.
Precondition
_ux_system_initialize and _ux_host_stack_initialize ran.
Postcondition
UACT=0; caller raises it via the dispatch table once a device is detected on SYSSTS0.LNST.
Note
Not thread-safe.
See also
ux_hcd_ra8_usb_uninitialize
Since
0.1.0

Register the ra8_usb host bridge as the active USBX HCD.

See implementation for details.

Parameters
[in,out]speedSee function signature for type and usage.
Returns
Result code or value; see implementation.
Return values
0Success 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 )

Read the bridge run-state.

Test-only.

Returns
Current ra8_usb_hcd_state_t.
Precondition
None.
Postcondition
No state mutated.
Note
Thread-safe (single 8-bit load).
Since
0.1.0

See implementation for details.

Return values
0Success or default value.
Precondition
Module has been initialized.
Postcondition
Side effects bounded to documented state.

Read the bridge run-state.

See implementation for details.

Returns
Result code or value; see implementation.
Return values
0Success 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

Tear down the ra8_usb HCD bridge.

Returns
ra8_err_t error code.
Return values
k_ra8_okBridge released.
k_ra8_err_invalid_stateBridge was never initialized.
Precondition
ux_hcd_ra8_usb_initialize previously succeeded.
Postcondition
Controller MSTP-gated.
Note
Not thread-safe.
Since
0.1.0

Tear down the ra8_usb HCD bridge.

See implementation for details.

Returns
Result code or value; see implementation.
Return values
0Success 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.