Native USB host-side HUB class layer. More...

#include <stdint.h>
#include "ra8_err.h"
#include "ra8_usb.h"

Include dependency graph for ra8_usb_hhub.h:

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

Data Structures
struct	ra8_usb_hhub_device_t
	Snapshot of the attached HUB device, passed to the attach callback. More...

Typedefs
typedef void(*	ra8_usb_hhub_attach_fn_t) (void ctx, const ra8_usb_hhub_device_t device)
	Attach-callback signature.

Enumerations
enum	ra8_usb_hhub_class_t : uint8_t { k_ra8_hhub_class_hub = 0x09U }
	HUB class code per USB 2.0 sec 11.24.1. More...
enum	ra8_usb_hhub_desc_t : uint8_t { k_ra8_hhub_desc_hub = 0x29U }
	HUB descriptor types (USB 2.0 sec 11.23.2). More...
enum	ra8_usb_hhub_request_t : uint8_t { k_ra8_hhub_req_get_status = 0x00U , k_ra8_hhub_req_clear_feature = 0x01U , k_ra8_hhub_req_set_feature = 0x03U , k_ra8_hhub_req_get_descriptor = 0x06U , k_ra8_hhub_req_set_descriptor = 0x07U , k_ra8_hhub_req_clear_tt_buffer = 0x08U , k_ra8_hhub_req_reset_tt = 0x09U }
	HUB class-specific request codes (USB 2.0 sec 11.24.2). More...
enum	ra8_usb_hhub_feature_t : uint16_t { k_ra8_hhub_feature_port_connection = 0U , k_ra8_hhub_feature_port_enable = 1U , k_ra8_hhub_feature_port_suspend = 2U , k_ra8_hhub_feature_port_overcurrent = 3U , k_ra8_hhub_feature_port_reset = 4U , k_ra8_hhub_feature_port_power = 8U , k_ra8_hhub_feature_port_low_speed = 9U , k_ra8_hhub_feature_c_port_connection = 16U , k_ra8_hhub_feature_c_port_enable = 17U , k_ra8_hhub_feature_c_port_suspend = 18U , k_ra8_hhub_feature_c_port_overcurr = 19U , k_ra8_hhub_feature_c_port_reset = 20U }
	HUB port feature selectors (USB 2.0 Table 11-17). More...
enum	ra8_usb_hhub_port_status_bits_t : uint8_t { k_ra8_hhub_status_bit_connection = 0U , k_ra8_hhub_status_bit_enable = 1U , k_ra8_hhub_status_bit_suspend = 2U , k_ra8_hhub_status_bit_overcurrent = 3U , k_ra8_hhub_status_bit_reset = 4U , k_ra8_hhub_status_bit_power = 8U , k_ra8_hhub_status_bit_low_speed = 9U , k_ra8_hhub_status_bit_high_speed = 10U }
	Bit positions in the 32-bit port status word (USB 2.0 Table 11-21). More...
enum	ra8_usb_hhub_limits_t : uint8_t { k_ra8_hhub_max_ports = 16U , k_ra8_hhub_first_port = 1U }
	Hard ceilings on hub topology this driver tracks. More...

Functions
ra8_err_t	ra8_usb_hhub_init (ra8_usb_speed_t speed)
	Bring up the host-HUB driver on a chosen USB controller.
ra8_err_t	ra8_usb_hhub_close (void)
	Tear down the host-HUB driver and release the controller.
ra8_err_t	ra8_usb_hhub_attach_callback (ra8_usb_hhub_attach_fn_t on_attach, void *ctx)
	Register (or detach) the HUB attach callback.
ra8_err_t	ra8_usb_hhub_get_port_count (uint8_t *count)
	Read the cached downstream port count from the HUB descriptor.
ra8_err_t	ra8_usb_hhub_get_port_status (uint8_t port, uint32_t *status)
	Issue GET_PORT_STATUS (USB 2.0 sec 11.24.2.7) over the DCP.
ra8_err_t	ra8_usb_hhub_set_port_feature (uint8_t port, ra8_usb_hhub_feature_t feature)
	Issue SET_PORT_FEATURE (USB 2.0 sec 11.24.2.13) over the DCP.
ra8_err_t	ra8_usb_hhub_clear_port_feature (uint8_t port, ra8_usb_hhub_feature_t feature)
	Issue CLEAR_PORT_FEATURE (USB 2.0 sec 11.24.2.2) over the DCP.
ra8_err_t	ra8_usb_hhub_step (void)
	Drive the enumeration step machine forward by one step.

Detailed Description

Native USB host-side HUB class layer.

Glues the host-mode bring-up paths in ra8_usb to a USB HUB device (class code 0x09) attached to the EK-RA8D2's USB host port. Mirrors FSP's r_usb_basic hub-support pattern: detect a HUB descriptor, read the per-port descriptor, expose GET_PORT_STATUS and SET_PORT_FEATURE control transfers so the application can sequence port power-on, port reset, and child-device enumeration on downstream ports.

Lifecycle:

ra8_usb_hhub_init(speed) flips the controller to host mode and leaves the bus in the "wait for attach" state (UACT cleared).
The driver runs the chapter-9 enumeration step machine over the DCP. When the device descriptor reports bDeviceClass = 0x09 (HUB) it pulls the HUB class descriptor (bDescriptorType = 0x29) and caches bNbrPorts.
The registered attach callback fires once with the discovered port count and VID/PID.
The application then walks each downstream port: ra8_usb_hhub_set_port_feature(port, PORT_POWER) -> ra8_usb_hhub_set_port_feature(port, PORT_RESET) -> ra8_usb_hhub_get_port_status(port, &status) and waits for C_PORT_RESET to clear before initiating SET_ADDRESS on the newly attached child.
ra8_usb_hhub_close() drops bus power and releases the device.

Reference: USB 2.0 specification chapter 11 "Hub Specification" (USB-IF, 2000-04-27). Class request encoding follows USB 2.0 sec 11.24 "Hub Class Requests".

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

Definition in file ra8_usb_hhub.h.

Typedef Documentation

◆ ra8_usb_hhub_attach_fn_t

typedef void(* ra8_usb_hhub_attach_fn_t) (void *ctx, const ra8_usb_hhub_device_t *device)

Attach-callback signature.

Parameters

[in]	ctx	Caller-supplied context registered with ra8_usb_hhub_attach_callback.
[in]	device	Snapshot of the attached HUB device. The pointer remains valid only for the duration of the call; copy out anything you need.

Definition at line 157 of file ra8_usb_hhub.h.

Enumeration Type Documentation

◆ ra8_usb_hhub_class_t

enum ra8_usb_hhub_class_t : uint8_t

HUB class code per USB 2.0 sec 11.24.1.

Enumerator
k_ra8_hhub_class_hub	bDeviceClass / bInterfaceClass = HUB.

Definition at line 61 of file ra8_usb_hhub.h.

◆ ra8_usb_hhub_desc_t

enum ra8_usb_hhub_desc_t : uint8_t

HUB descriptor types (USB 2.0 sec 11.23.2).

Enumerator
k_ra8_hhub_desc_hub	HUB class descriptor type.

Definition at line 69 of file ra8_usb_hhub.h.

◆ ra8_usb_hhub_feature_t

enum ra8_usb_hhub_feature_t : uint16_t

HUB port feature selectors (USB 2.0 Table 11-17).

Enumerator
k_ra8_hhub_feature_port_connection	C_PORT_CONNECTION cleared.
k_ra8_hhub_feature_port_enable	PORT_ENABLE.
k_ra8_hhub_feature_port_suspend	PORT_SUSPEND.
k_ra8_hhub_feature_port_overcurrent	PORT_OVER_CURRENT.
k_ra8_hhub_feature_port_reset	PORT_RESET.
k_ra8_hhub_feature_port_power	PORT_POWER.
k_ra8_hhub_feature_port_low_speed	PORT_LOW_SPEED.
k_ra8_hhub_feature_c_port_connection	C_PORT_CONNECTION (change).
k_ra8_hhub_feature_c_port_enable	C_PORT_ENABLE (change).
k_ra8_hhub_feature_c_port_suspend	C_PORT_SUSPEND (change).
k_ra8_hhub_feature_c_port_overcurr	C_PORT_OVER_CURRENT (change).
k_ra8_hhub_feature_c_port_reset	C_PORT_RESET (change).

Definition at line 91 of file ra8_usb_hhub.h.

◆ ra8_usb_hhub_limits_t

enum ra8_usb_hhub_limits_t : uint8_t

Hard ceilings on hub topology this driver tracks.

FSP's r_usb_basic hub support tracks up to 16 downstream ports per hub; we mirror that ceiling.

Enumerator
k_ra8_hhub_max_ports	FSP-aligned downstream port ceiling.
k_ra8_hhub_first_port	Port numbering starts at 1.

Definition at line 130 of file ra8_usb_hhub.h.

◆ ra8_usb_hhub_port_status_bits_t

enum ra8_usb_hhub_port_status_bits_t : uint8_t

Bit positions in the 32-bit port status word (USB 2.0 Table 11-21).

Low 16 bits = wPortStatus, high 16 bits = wPortChange.

Enumerator
k_ra8_hhub_status_bit_connection	Current connect status.
k_ra8_hhub_status_bit_enable	Port enabled.
k_ra8_hhub_status_bit_suspend	Suspend state.
k_ra8_hhub_status_bit_overcurrent	Over-current latch.
k_ra8_hhub_status_bit_reset	Reset in progress.
k_ra8_hhub_status_bit_power	Port power on.
k_ra8_hhub_status_bit_low_speed	Low-speed device.
k_ra8_hhub_status_bit_high_speed	High-speed device.

Definition at line 112 of file ra8_usb_hhub.h.

◆ ra8_usb_hhub_request_t

enum ra8_usb_hhub_request_t : uint8_t

HUB class-specific request codes (USB 2.0 sec 11.24.2).

Enumerator
k_ra8_hhub_req_get_status	GET_STATUS.
k_ra8_hhub_req_clear_feature	CLEAR_FEATURE.
k_ra8_hhub_req_set_feature	SET_FEATURE.
k_ra8_hhub_req_get_descriptor	GET_DESCRIPTOR.
k_ra8_hhub_req_set_descriptor	SET_DESCRIPTOR.
k_ra8_hhub_req_clear_tt_buffer	CLEAR_TT_BUFFER.
k_ra8_hhub_req_reset_tt	RESET_TT.

Definition at line 77 of file ra8_usb_hhub.h.

Function Documentation

◆ ra8_usb_hhub_attach_callback()

ra8_err_t ra8_usb_hhub_attach_callback	(	ra8_usb_hhub_attach_fn_t	on_attach,
		void *	ctx )

nodiscard

Register (or detach) the HUB attach callback.

Parameters

[in]	on_attach	Callback. NULL detaches.
[in]	ctx	Context pointer threaded back into on_attach.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Callback installed.
k_ra8_err_invalid_state	Driver was never initialized.

Precondition: ra8_usb_hhub_init has run.

Postcondition: On a subsequent attach, on_attach(ctx, &device) fires once.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 514 of file ra8_usb_hhub.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_usb_hhub_clear_port_feature()

ra8_err_t ra8_usb_hhub_clear_port_feature	(	uint8_t	port,
		ra8_usb_hhub_feature_t	feature )

nodiscard

Issue CLEAR_PORT_FEATURE (USB 2.0 sec 11.24.2.2) over the DCP.

Builds an 8-byte SETUP packet with bmRequestType = 0x23 (H2D | Class | Other), bRequest = 0x01 (CLEAR_FEATURE), wValue = feature, wIndex = port, wLength = 0. Most commonly used to acknowledge change bits like C_PORT_RESET / C_PORT_CONNECTION.

Parameters

[in]	port	Downstream port number.
[in]	feature	Feature selector.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Control transfer queued.
k_ra8_err_invalid_state	Driver not initialized, or no HUB attached.
k_ra8_err_invalid_arg	port out of range.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhub_init succeeded.; Attach callback already fired.

Postcondition: On success the SETUP mirror registers hold the CLEAR_FEATURE request envelope.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 607 of file ra8_usb_hhub.c.

References internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhub_bm_class_other_out, k_ra8_hhub_req_clear_feature, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_hhub_close()

ra8_err_t ra8_usb_hhub_close ( void )

nodiscard

Tear down the host-HUB driver and release the controller.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Released.
k_ra8_err_invalid_state	Driver was never initialized.

Precondition: Single-threaded shutdown context.

Postcondition: ra8_usb_host_deinit ran, SOF generation halted, bus power dropped; subsequent host-HUB API calls return k_ra8_err_invalid_state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 494 of file ra8_usb_hhub.c.

References k_ra8_err_invalid_state, k_ra8_hhub_step_idle, ra8_usb_host_deinit(), ra8_usb_host_set_uact(), and s_state.

◆ ra8_usb_hhub_get_port_count()

ra8_err_t ra8_usb_hhub_get_port_count ( uint8_t * count )

nodiscard

Read the cached downstream port count from the HUB descriptor.

Returns the value of bNbrPorts collected during enumeration (USB 2.0 sec 11.23.2.1). Does NOT issue a fresh GET_DESCRIPTOR(HUB) on every call – the descriptor is cached at attach time.

Parameters

[out] count Receives port count, in range [k_ra8_hhub_first_port .. k_ra8_hhub_max_ports].

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Count copied to *count.
k_ra8_err_null_ptr	count was NULL.
k_ra8_err_invalid_state	Driver not initialized, or no HUB attached.

Precondition: ra8_usb_hhub_init succeeded.; Attach callback already fired.

Postcondition: *count <= k_ra8_hhub_max_ports on success.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 529 of file ra8_usb_hhub.c.

References k_ra8_err_invalid_state, k_ra8_ok, RA8_CHECK_NULL_PTR, s_state, and s_tag.

◆ ra8_usb_hhub_get_port_status()

ra8_err_t ra8_usb_hhub_get_port_status	(	uint8_t	port,
		uint32_t *	status )

nodiscard

Issue GET_PORT_STATUS (USB 2.0 sec 11.24.2.7) over the DCP.

Builds an 8-byte SETUP packet with bmRequestType = 0xA3 (D2H | Class | Other), bRequest = 0x00 (GET_STATUS), wValue = 0, wIndex = port, wLength = 4. The data stage delivers a 32-bit word whose low half is wPortStatus and high half is wPortChange.

Parameters

[in]	port	Downstream port number, in [k_ra8_hhub_first_port .. k_ra8_hhub_max_ports].
[out]	status	Receives the 32-bit status word once the data stage lands. The starter zeroes this on entry; the production path overwrites it from the data stage handler.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Control transfer queued.
k_ra8_err_null_ptr	status was NULL.
k_ra8_err_invalid_state	Driver not initialized, or no HUB attached.
k_ra8_err_invalid_arg	port out of range.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhub_init succeeded.; Attach callback already fired.

Postcondition: On success the SETUP mirror registers hold the GET_STATUS request envelope.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 549 of file ra8_usb_hhub.c.

References internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhub_bm_class_other_in, k_ra8_hhub_port_status_len, k_ra8_hhub_req_get_status, RA8_CHECK_NULL_PTR, ra8_usb_host_setup_request(), s_state, and s_tag.

◆ ra8_usb_hhub_init()

ra8_err_t ra8_usb_hhub_init ( ra8_usb_speed_t speed )

nodiscard

Bring up the host-HUB driver on a chosen USB controller.

Initialises the underlying ra8_usb driver in HOST mode for speed, leaves the bus in the "wait for attach" state (UACT cleared), and arms the internal enumeration step machine so the next CTRT interrupt advances enumeration.

Parameters

[in] speed Which USB controller (FS or HS).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Host-HUB ready, awaiting attach.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_hw_init_failed	Underlying ra8_usb_host_init failed.

Precondition: Single-threaded init context.; ra8_mstp_init and ra8_pwr_init already ran.

Postcondition: ra8_usb_host_init succeeded for speed.; Internal step machine armed; attach callback has not fired.

Note: Not thread-safe.

See also: ra8_usb_hhub_attach_callback; ra8_usb_hhub_close

Since: 0.1.0

Definition at line 471 of file ra8_usb_hhub.c.

References k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_hhub_step_idle, k_ra8_ok, k_ra8_usb_speed_fs, k_ra8_usb_speed_hs, ra8_log_error_val, ra8_log_info_val, ra8_usb_host_init(), s_state, and s_tag.

◆ ra8_usb_hhub_set_port_feature()

ra8_err_t ra8_usb_hhub_set_port_feature	(	uint8_t	port,
		ra8_usb_hhub_feature_t	feature )

nodiscard

Issue SET_PORT_FEATURE (USB 2.0 sec 11.24.2.13) over the DCP.

Builds an 8-byte SETUP packet with bmRequestType = 0x23 (H2D | Class | Other), bRequest = 0x03 (SET_FEATURE), wValue = feature, wIndex = port, wLength = 0. Used to drive PORT_POWER, PORT_RESET, PORT_SUSPEND, PORT_ENABLE, etc.

Parameters

[in]	port	Downstream port number.
[in]	feature	Feature selector (see ra8_usb_hhub_feature_t).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Control transfer queued.
k_ra8_err_invalid_state	Driver not initialized, or no HUB attached.
k_ra8_err_invalid_arg	port out of range.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhub_init succeeded.; Attach callback already fired.

Postcondition: On success the SETUP mirror registers hold the SET_FEATURE request envelope.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 579 of file ra8_usb_hhub.c.

References internal_port_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhub_bm_class_other_out, k_ra8_hhub_req_set_feature, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_hhub_step()

ra8_err_t ra8_usb_hhub_step ( void )

nodiscard

Drive the enumeration step machine forward by one step.

Test / debug entry point. Production drives this from the ra8_usb_dispatch callback when the controller fires a CTRT or BRDY interrupt; tests call it directly to walk the state machine deterministically.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Step advanced.
k_ra8_err_invalid_state	Driver not initialized.

Precondition: ra8_usb_hhub_init succeeded.

Postcondition: Internal enumeration step counter advances by one. On the terminal step the registered attach callback fires.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 633 of file ra8_usb_hhub.c.

References internal_step_advance(), k_ra8_err_invalid_state, and s_state.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_usb_hhub_attach_fn_t

Enumeration Type Documentation

◆ ra8_usb_hhub_class_t

◆ ra8_usb_hhub_desc_t

◆ ra8_usb_hhub_feature_t

◆ ra8_usb_hhub_limits_t

◆ ra8_usb_hhub_port_status_bits_t

◆ ra8_usb_hhub_request_t

Function Documentation

◆ ra8_usb_hhub_attach_callback()

◆ ra8_usb_hhub_clear_port_feature()

◆ ra8_usb_hhub_close()

◆ ra8_usb_hhub_get_port_count()

◆ ra8_usb_hhub_get_port_status()

◆ ra8_usb_hhub_init()

◆ ra8_usb_hhub_set_port_feature()

◆ ra8_usb_hhub_step()