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

#include "ra8_usb_hhub.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_usb.h"

Include dependency graph for ra8_usb_hhub.c:

Data Structures
struct	ra8_usb_hhub_state_t
	Singleton shadow state for the host-HUB driver. More...

Enumerations
enum	ra8_usb_hhub_step_t : uint8_t { k_ra8_hhub_step_idle = 0U , k_ra8_hhub_step_bus_reset = 1U , k_ra8_hhub_step_set_address = 2U , k_ra8_hhub_step_get_dev_desc = 3U , k_ra8_hhub_step_get_cfg_desc = 4U , k_ra8_hhub_step_set_config = 5U , k_ra8_hhub_step_get_hub_desc = 6U , k_ra8_hhub_step_done = 7U }
	Enumeration step machine states. More...
enum	ra8_usb_hhub_setup_field_t : uint8_t { k_ra8_hhub_bm_std_dev_in = 0x80U , k_ra8_hhub_bm_std_dev_out = 0x00U , k_ra8_hhub_breq_get_desc = 0x06U , k_ra8_hhub_breq_set_address = 0x05U , k_ra8_hhub_breq_set_config = 0x09U , k_ra8_hhub_bm_class_dev_in = 0xA0U , k_ra8_hhub_bm_class_other_in = 0xA3U , k_ra8_hhub_bm_class_other_out = 0x23U , k_ra8_hhub_desc_device = 0x01U , k_ra8_hhub_desc_configuration = 0x02U }
	Standard chapter-9 + HUB class request encodings. More...
enum	ra8_usb_hhub_size_t : uint16_t { k_ra8_hhub_dev_desc_len = 18U , k_ra8_hhub_cfg_desc_len = 9U , k_ra8_hhub_hub_desc_len = 9U , k_ra8_hhub_port_status_len = 4U , k_ra8_hhub_assigned_address = 1U , k_ra8_hhub_default_config = 1U , k_ra8_hhub_default_ports = 4U }
	Standard descriptor sizes / payload sizes. More...
enum	ra8_usb_hhub_byte_shift_t : uint8_t { k_ra8_hhub_shift_byte1 = 8U }
	Per-byte left-shift constants for wValue layout. More...

Functions
static ra8_err_t	internal_setup_get_descriptor (uint8_t desc_type, uint16_t length)
	Stage a chapter-9 GET_DESCRIPTOR SETUP request.
static ra8_err_t	internal_setup_set_address (uint8_t address)
	Stage a SET_ADDRESS SETUP request.
static ra8_err_t	internal_setup_set_config (uint8_t config_value)
	Stage a SET_CONFIGURATION SETUP request.
static ra8_err_t	internal_setup_get_hub_descriptor (void)
	Stage a GET_DESCRIPTOR(HUB) class request.
static void	internal_populate_device_defaults (void)
	Populate s_state.device with stub descriptor data.
static bool	internal_port_ok (uint8_t port)
	Validate port is within [1, port_count].
static ra8_err_t	internal_do_idle (void)
	Internal helper.
static ra8_err_t	internal_do_bus_reset (void)
	Internal helper.
static ra8_err_t	internal_do_set_address (void)
	Internal helper.
static ra8_err_t	internal_do_get_dev_desc (void)
	Internal helper.
static ra8_err_t	internal_do_get_cfg_desc (void)
	Internal helper.
static ra8_err_t	internal_do_set_config (void)
	Internal helper.
static ra8_err_t	internal_do_get_hub_desc (void)
	Internal helper.
static ra8_err_t	internal_step_advance (void)
	Drive the enumeration step machine forward by one step.
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.

Variables
static const char *	s_tag = "USBHHUB"
static ra8_usb_hhub_state_t	s_state = {}

Detailed Description

Native USB host-side HUB class layer implementation.

Tag: [Ring 3 / HAL] {World: NS}

Glues the host-mode bring-up paths in ra8_usb to a HUB peripheral (class 0x09) attached on the EK-RA8D2's USB host port. Mirrors FSP's r_usb_basic hub-support pattern – enumerate the HUB itself, cache bNbrPorts, and expose the GET_PORT_STATUS / SET_PORT_FEATURE / CLEAR_PORT_FEATURE class transfers used by the application to sequence per-port reset, power, and child enumeration.

Each enumeration step issues exactly one chapter-9 SETUP request via ra8_usb_host_setup_request; the next CTRT advances the step.

Reference: USB 2.0 specification chapter 11 "Hub Specification" (sec 11.23 descriptors, sec 11.24 class requests). Class request envelope encoding follows USB 2.0 Table 11-15.

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

Definition in file ra8_usb_hhub.c.

Enumeration Type Documentation

◆ ra8_usb_hhub_byte_shift_t

enum ra8_usb_hhub_byte_shift_t : uint8_t

Per-byte left-shift constants for wValue layout.

Enumerator
k_ra8_hhub_shift_byte1	Shift to high byte of a 16-bit field.

Definition at line 97 of file ra8_usb_hhub.c.

◆ ra8_usb_hhub_setup_field_t

enum ra8_usb_hhub_setup_field_t : uint8_t

Standard chapter-9 + HUB class request encodings.

Enumerator
k_ra8_hhub_bm_std_dev_in	Std \| Device \| In.
k_ra8_hhub_bm_std_dev_out	Std \| Device \| Out.
k_ra8_hhub_breq_get_desc	GET_DESCRIPTOR.
k_ra8_hhub_breq_set_address	SET_ADDRESS.
k_ra8_hhub_breq_set_config	SET_CONFIGURATION.
k_ra8_hhub_bm_class_dev_in	Class \| Device \| In.
k_ra8_hhub_bm_class_other_in	Class \| Other \| In.
k_ra8_hhub_bm_class_other_out	Class \| Other \| Out.
k_ra8_hhub_desc_device	DEVICE descriptor.
k_ra8_hhub_desc_configuration	CONFIG descriptor.

Definition at line 63 of file ra8_usb_hhub.c.

◆ ra8_usb_hhub_size_t

enum ra8_usb_hhub_size_t : uint16_t

Standard descriptor sizes / payload sizes.

Enumerator
k_ra8_hhub_dev_desc_len	USB DEVICE descriptor.
k_ra8_hhub_cfg_desc_len	CONFIG descriptor header.
k_ra8_hhub_hub_desc_len	Min HUB class descriptor.
k_ra8_hhub_port_status_len	GET_PORT_STATUS data length.
k_ra8_hhub_assigned_address	First assigned device addr.
k_ra8_hhub_default_config	bConfigurationValue = 1.
k_ra8_hhub_default_ports	Stub default port count.

Definition at line 83 of file ra8_usb_hhub.c.

◆ ra8_usb_hhub_step_t

enum ra8_usb_hhub_step_t : uint8_t

Enumeration step machine states.

Enumerator
k_ra8_hhub_step_idle	Pre-attach.
k_ra8_hhub_step_bus_reset	Drive USBRST then release.
k_ra8_hhub_step_set_address	SET_ADDRESS to assigned 1.
k_ra8_hhub_step_get_dev_desc	GET_DEVICE_DESCRIPTOR.
k_ra8_hhub_step_get_cfg_desc	GET_CONFIGURATION_DESCRIPTOR.
k_ra8_hhub_step_set_config	SET_CONFIGURATION (1).
k_ra8_hhub_step_get_hub_desc	GET_DESCRIPTOR(HUB) class.
k_ra8_hhub_step_done	Attach callback fires.

Definition at line 48 of file ra8_usb_hhub.c.

Function Documentation

◆ internal_do_bus_reset()

ra8_err_t internal_do_bus_reset ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 316 of file ra8_usb_hhub.c.

References internal_setup_set_address(), k_ra8_hhub_assigned_address, k_ra8_hhub_step_set_address, ra8_usb_host_bus_reset(), and s_state.

Referenced by internal_step_advance().

◆ internal_do_get_cfg_desc()

ra8_err_t internal_do_get_cfg_desc ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 380 of file ra8_usb_hhub.c.

References internal_setup_set_config(), k_ra8_hhub_default_config, k_ra8_hhub_step_set_config, and s_state.

Referenced by internal_step_advance().

◆ internal_do_get_dev_desc()

ra8_err_t internal_do_get_dev_desc ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 361 of file ra8_usb_hhub.c.

References internal_setup_get_descriptor(), k_ra8_hhub_cfg_desc_len, k_ra8_hhub_desc_configuration, k_ra8_hhub_step_get_cfg_desc, and s_state.

Referenced by internal_step_advance().

◆ internal_do_get_hub_desc()

ra8_err_t internal_do_get_hub_desc ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 418 of file ra8_usb_hhub.c.

References internal_populate_device_defaults(), k_ra8_hhub_step_done, k_ra8_ok, and s_state.

Referenced by internal_step_advance().

◆ internal_do_idle()

ra8_err_t internal_do_idle ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 297 of file ra8_usb_hhub.c.

References k_ra8_hhub_step_bus_reset, ra8_usb_host_bus_reset(), and s_state.

Referenced by internal_step_advance().

◆ internal_do_set_address()

ra8_err_t internal_do_set_address ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 339 of file ra8_usb_hhub.c.

References internal_setup_get_descriptor(), k_ra8_hhub_assigned_address, k_ra8_hhub_desc_device, k_ra8_hhub_dev_desc_len, k_ra8_hhub_step_get_dev_desc, ra8_usb_set_address(), and s_state.

Referenced by internal_step_advance().

◆ internal_do_set_config()

ra8_err_t internal_do_set_config ( void )

static

Internal helper.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 399 of file ra8_usb_hhub.c.

References internal_setup_get_hub_descriptor(), k_ra8_hhub_step_get_hub_desc, and s_state.

Referenced by internal_step_advance().

◆ internal_populate_device_defaults()

void internal_populate_device_defaults ( void )

static

Populate s_state.device with stub descriptor data.

In production this routine consumes the HUB class descriptor data stage and reads bNbrPorts (USB 2.0 sec 11.23.2.1). The starter populates a sensible default (4 ports, no VID/PID) so tests can exercise the API surface deterministically.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 254 of file ra8_usb_hhub.c.

References k_ra8_hhub_assigned_address, k_ra8_hhub_default_ports, and s_state.

Referenced by internal_do_get_hub_desc().

◆ internal_port_ok()

bool internal_port_ok ( uint8_t port )

static

Validate port is within [1, port_count].

See implementation.

Parameters

[in] port See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 277 of file ra8_usb_hhub.c.

References k_ra8_hhub_first_port, and s_state.

Referenced by ra8_usb_hhub_clear_port_feature(), ra8_usb_hhub_get_port_status(), and ra8_usb_hhub_set_port_feature().

◆ internal_setup_get_descriptor()

ra8_err_t internal_setup_get_descriptor	(	uint8_t	desc_type,
		uint16_t	length )

static

Stage a chapter-9 GET_DESCRIPTOR SETUP request.

See implementation.

Parameters

[in]	desc_type	See implementation.
[in]	length	See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 143 of file ra8_usb_hhub.c.

References k_ra8_hhub_bm_std_dev_in, k_ra8_hhub_breq_get_desc, k_ra8_hhub_shift_byte1, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_get_dev_desc(), and internal_do_set_address().

◆ internal_setup_get_hub_descriptor()

ra8_err_t internal_setup_get_hub_descriptor ( void )

static

Stage a GET_DESCRIPTOR(HUB) class request.

Per USB 2.0 sec 11.24.2.5 GET_HUB_DESCRIPTOR uses bmRequestType = 0xA0 (Class | Device | In), bRequest = 0x06, wValue.high = 0x29 (HUB), wIndex = 0, wLength = descriptor length.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 226 of file ra8_usb_hhub.c.

References k_ra8_hhub_bm_class_dev_in, k_ra8_hhub_desc_hub, k_ra8_hhub_hub_desc_len, k_ra8_hhub_req_get_descriptor, k_ra8_hhub_shift_byte1, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_set_config().

◆ internal_setup_set_address()

ra8_err_t internal_setup_set_address ( uint8_t address )

static

Stage a SET_ADDRESS SETUP request.

See implementation.

Parameters

[in] address See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 170 of file ra8_usb_hhub.c.

References k_ra8_hhub_bm_std_dev_out, k_ra8_hhub_breq_set_address, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_bus_reset().

◆ internal_setup_set_config()

ra8_err_t internal_setup_set_config ( uint8_t config_value )

static

Stage a SET_CONFIGURATION SETUP request.

See implementation.

Parameters

[in] config_value See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 197 of file ra8_usb_hhub.c.

References k_ra8_hhub_bm_std_dev_out, k_ra8_hhub_breq_set_config, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_get_cfg_desc().

◆ internal_step_advance()

ra8_err_t internal_step_advance ( void )

static

Drive the enumeration step machine forward by one step.

See implementation.

Returns: Result code.

Return values

k_ra8_ok Operation succeeded.

Precondition: Module state is consistent.; Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.; Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Since: 0.1.0

Definition at line 443 of file ra8_usb_hhub.c.

References internal_do_bus_reset(), internal_do_get_cfg_desc(), internal_do_get_dev_desc(), internal_do_get_hub_desc(), internal_do_idle(), internal_do_set_address(), internal_do_set_config(), k_ra8_hhub_step_bus_reset, k_ra8_hhub_step_get_cfg_desc, k_ra8_hhub_step_get_dev_desc, k_ra8_hhub_step_get_hub_desc, k_ra8_hhub_step_idle, k_ra8_hhub_step_set_address, k_ra8_hhub_step_set_config, k_ra8_ok, and s_state.

Referenced by ra8_usb_hhub_step().

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

Variable Documentation

◆ s_state

ra8_usb_hhub_state_t s_state = {}

static

Definition at line 120 of file ra8_usb_hhub.c.

◆ s_tag

const char* s_tag = "USBHHUB"

static

Definition at line 37 of file ra8_usb_hhub.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_usb_hhub_byte_shift_t

◆ ra8_usb_hhub_setup_field_t

◆ ra8_usb_hhub_size_t

◆ ra8_usb_hhub_step_t

Function Documentation

◆ internal_do_bus_reset()

◆ internal_do_get_cfg_desc()

◆ internal_do_get_dev_desc()

◆ internal_do_get_hub_desc()

◆ internal_do_idle()

◆ internal_do_set_address()

◆ internal_do_set_config()

◆ internal_populate_device_defaults()

◆ internal_port_ok()

◆ internal_setup_get_descriptor()

◆ internal_setup_get_hub_descriptor()

◆ internal_setup_set_address()

◆ internal_setup_set_config()

◆ internal_step_advance()

◆ 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()

Variable Documentation

◆ s_state

◆ s_tag