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

#include "ra8_usb_hhid.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 "ra8_usb_regs.h"

Include dependency graph for ra8_usb_hhid.c:

Data Structures
struct	ra8_usb_hhid_state_t
	Singleton shadow state for the host-HID driver. More...

Enumerations
enum	ra8_usb_hhid_step_t : uint8_t { k_ra8_hhid_step_idle = 0U , k_ra8_hhid_step_bus_reset = 1U , k_ra8_hhid_step_set_address = 2U , k_ra8_hhid_step_get_dev_desc = 3U , k_ra8_hhid_step_get_cfg_desc = 4U , k_ra8_hhid_step_set_config = 5U , k_ra8_hhid_step_set_interface = 6U , k_ra8_hhid_step_walk_desc = 7U , k_ra8_hhid_step_get_report_desc = 8U , k_ra8_hhid_step_done = 9U }
	Enumeration step machine states. More...
enum	ra8_usb_hhid_setup_field_t : uint8_t { k_ra8_hhid_bm_std_dev_in = 0x80U , k_ra8_hhid_bm_std_dev_out = 0x00U , k_ra8_hhid_bm_std_iface_in = 0x81U , k_ra8_hhid_bm_std_iface_out = 0x01U , k_ra8_hhid_breq_get_descriptor = 0x06U , k_ra8_hhid_breq_set_address = 0x05U , k_ra8_hhid_breq_set_config = 0x09U , k_ra8_hhid_breq_set_interface = 0x0BU , k_ra8_hhid_bm_class_iface_in = 0xA1U , k_ra8_hhid_bm_class_iface_out = 0x21U , k_ra8_hhid_desc_device = 0x01U , k_ra8_hhid_desc_configuration = 0x02U , k_ra8_hhid_desc_interface = 0x04U , k_ra8_hhid_desc_endpoint = 0x05U }
	Standard chapter-9 + HID class request encodings. More...
enum	ra8_usb_hhid_size_t : uint16_t { k_ra8_hhid_dev_desc_len = 18U , k_ra8_hhid_cfg_desc_len = 9U , k_ra8_hhid_iface_desc_len = 9U , k_ra8_hhid_ep_desc_len = 7U , k_ra8_hhid_hid_desc_len = 9U , k_ra8_hhid_assigned_address = 1U , k_ra8_hhid_default_config = 1U }
	Standard descriptor sizes and request payload sizes. More...
enum	ra8_usb_hhid_byte_shift_t : uint8_t { k_ra8_hhid_shift_byte0 = 0U , k_ra8_hhid_shift_byte1 = 8U }
	Per-byte left-shift constants for wValue layout. More...
enum	ra8_usb_hhid_dcp_t : uint16_t { k_ra8_hhid_dcp_pipe_dcp = 0U , k_ra8_hhid_fifo_poll_lim = 4096U }
	CFIFO programming constants used by the EP0 IN drain helper. More...

Functions
static uint16_t	internal_intr_max_packet (ra8_usb_speed_t speed)
	Pick the interrupt-max-packet ceiling for the negotiated speed.
static ra8_err_t	internal_configure_pipes (void)
	Configure the host-HID interrupt-IN pipe against the attached device's endpoint.
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_set_interface (void)
	Stage a SET_INTERFACE (alt 0, iface 0) SETUP request.
static ra8_err_t	internal_setup_get_report_descriptor (uint16_t length)
	Stage a GET_DESCRIPTOR (Report descriptor) SETUP request.
static void	internal_walk_config_descriptor (void)
	Populate s_state.device with stub descriptor data.
static ra8_err_t	internal_do_idle (void)
	Step handler – bus-reset assert.
static ra8_err_t	internal_do_bus_reset (void)
	Step handler – bus-reset release + SETUP for SET_ADDRESS.
static ra8_err_t	internal_do_set_address (void)
	Step handler – store assigned address + SETUP for GET_DEVICE_DESCRIPTOR.
static ra8_err_t	internal_do_get_dev_desc (void)
	Step handler – SETUP for GET_CONFIGURATION_DESCRIPTOR.
static ra8_err_t	internal_do_get_cfg_desc (void)
	Step handler – SETUP for SET_CONFIGURATION.
static ra8_err_t	internal_do_set_config (void)
	Step handler – SETUP for SET_INTERFACE.
static ra8_err_t	internal_do_set_interface (void)
	Step handler – pure software descriptor walk.
static ra8_err_t	internal_do_walk_desc (void)
	Step handler – configure pipes + SETUP GET_DESCRIPTOR(Report).
static ra8_err_t	internal_do_get_report_desc (void)
	Step handler – finalise + fire attach callback.
static ra8_err_t	internal_step_advance (void)
	Drive the enumeration step machine forward by one step.
static bool	internal_report_type_ok (ra8_usb_hhid_report_type_t t)
	Validate that a ra8_usb_hhid_report_type_t value is in range.
ra8_err_t	ra8_usb_hhid_init (ra8_usb_speed_t speed)
	Bring up the host-HID driver on a chosen USB controller.
ra8_err_t	ra8_usb_hhid_close (void)
	Tear down the host-HID driver and release the controller.
ra8_err_t	ra8_usb_hhid_attach_callback (ra8_usb_hhid_attach_fn_t on_attach, void *ctx)
	Register (or detach) the attach callback.
static volatile r_usb_regs_t *	internal_pick_regs (ra8_usb_speed_t speed)
	Pick the controller register window for the active speed.
static uint16_t	internal_dcp_in_drain (volatile r_usb_regs_t reg, uint8_t out, uint16_t max_len)
	Drain the DCP (EP0) IN FIFO after a class GET_REPORT SETUP.
ra8_err_t	ra8_usb_hhid_get_report (ra8_usb_hhid_report_type_t target_report_type, uint8_t target_report_id, uint8_t out_buf, uint16_t max_len, uint16_t got_len)
	Issue GET_REPORT (USB HID 1.11 sec 7.2.1) over the DCP.
ra8_err_t	ra8_usb_hhid_set_report (ra8_usb_hhid_report_type_t target_report_type, uint8_t target_report_id, const uint8_t *in_buf, uint16_t len)
	Issue SET_REPORT (USB HID 1.11 sec 7.2.2) over the DCP.
ra8_err_t	ra8_usb_hhid_set_idle (uint8_t duration, uint8_t report_id)
	Issue SET_IDLE (USB HID 1.11 sec 7.2.4) over the DCP.
ra8_err_t	ra8_usb_hhid_set_protocol (ra8_usb_hhid_protocol_select_t boot_or_report)
	Issue SET_PROTOCOL (USB HID 1.11 sec 7.2.6) over the DCP.
ra8_err_t	ra8_usb_hhid_get_input_report (uint8_t out_buf, uint16_t max_len, uint16_t got_len)
	Drain the next input report from the interrupt-IN pipe.
ra8_err_t	ra8_usb_hhid_step (void)
	Drive the enumeration step machine forward by one step.

Variables
static const char *	s_tag = "USBHHID"
static ra8_usb_hhid_state_t	s_state = {}

Detailed Description

Native USB host-side HID class layer implementation.

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

Glues the host-mode bring-up paths in ra8_usb to a USB HID peripheral - keyboard, mouse, gamepad - attached on the EK-RA8D2's USB-host port. This file is the native host-HID class layer; FSP's r_usb_hhid_driver.c and r_usb_hhid.c are reference material only – nothing is pulled in verbatim.

Mapping vs FSP (FSP function -> our entry point):

usb_hhid_class_request_init -> ra8_usb_hhid_init
usb_hhid_enumeration -> internal_enum_* step machine driven by ra8_usb_hhid_step.
usb_hhid_pipe_info -> internal_walk_config_descriptor
usb_hhid_set_report -> ra8_usb_hhid_set_report
usb_hhid_get_report -> ra8_usb_hhid_get_report
usb_hhid_set_idle -> ra8_usb_hhid_set_idle
usb_hhid_set_protocol -> ra8_usb_hhid_set_protocol
R_USB_HHID_DeviceInfoGet -> attach-callback device payload

The starter does CPU-FIFO, single-device, no-hub. Enumeration is driven step-by-step from the controller's CTRT interrupt path (production) or directly via ra8_usb_hhid_step (tests). Each step issues exactly one chapter-9 SETUP request via ra8_usb_host_setup_request; the next CTRT advances the step.

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

Definition in file ra8_usb_hhid.c.

Enumeration Type Documentation

◆ ra8_usb_hhid_byte_shift_t

enum ra8_usb_hhid_byte_shift_t : uint8_t

Per-byte left-shift constants for wValue layout.

Enumerator
k_ra8_hhid_shift_byte0	RA8 hhid shift byte0.
k_ra8_hhid_shift_byte1	RA8 hhid shift byte1.

Definition at line 118 of file ra8_usb_hhid.c.

◆ ra8_usb_hhid_dcp_t

enum ra8_usb_hhid_dcp_t : uint16_t

CFIFO programming constants used by the EP0 IN drain helper.

Enumerator
k_ra8_hhid_dcp_pipe_dcp	DCP / EP0 select.
k_ra8_hhid_fifo_poll_lim	FRDY-poll budget.

Definition at line 719 of file ra8_usb_hhid.c.

◆ ra8_usb_hhid_setup_field_t

enum ra8_usb_hhid_setup_field_t : uint8_t

Standard chapter-9 + HID class request encodings.

Enumerator
k_ra8_hhid_bm_std_dev_in	Std \| Device \| In.
k_ra8_hhid_bm_std_dev_out	Std \| Device \| Out.
k_ra8_hhid_bm_std_iface_in	Std \| Interface \| In.
k_ra8_hhid_bm_std_iface_out	Std \| Interface \| Out.
k_ra8_hhid_breq_get_descriptor	GET_DESCRIPTOR.
k_ra8_hhid_breq_set_address	SET_ADDRESS.
k_ra8_hhid_breq_set_config	SET_CONFIGURATION.
k_ra8_hhid_breq_set_interface	SET_INTERFACE.
k_ra8_hhid_bm_class_iface_in	Class \| Interface \| In.
k_ra8_hhid_bm_class_iface_out	Class \| Interface \| Out.
k_ra8_hhid_desc_device	DEVICE descriptor.
k_ra8_hhid_desc_configuration	CONFIGURATION descriptor.
k_ra8_hhid_desc_interface	INTERFACE descriptor.
k_ra8_hhid_desc_endpoint	ENDPOINT descriptor.

Definition at line 80 of file ra8_usb_hhid.c.

◆ ra8_usb_hhid_size_t

enum ra8_usb_hhid_size_t : uint16_t

Standard descriptor sizes and request payload sizes.

Enumerator
k_ra8_hhid_dev_desc_len	USB DEVICE descriptor.
k_ra8_hhid_cfg_desc_len	CONFIGURATION descriptor hdr.
k_ra8_hhid_iface_desc_len	INTERFACE descriptor.
k_ra8_hhid_ep_desc_len	ENDPOINT descriptor.
k_ra8_hhid_hid_desc_len	HID class descriptor (min).
k_ra8_hhid_assigned_address	First assigned device addr.
k_ra8_hhid_default_config	bConfigurationValue = 1.

Definition at line 104 of file ra8_usb_hhid.c.

◆ ra8_usb_hhid_step_t

enum ra8_usb_hhid_step_t : uint8_t

Enumeration step machine states.

Mirrors FSP's host-HID enumeration sequence in r_usb_hhid_driver.c. Each step issues exactly one SETUP via ra8_usb_host_setup_request; the next CTRT interrupt advances.

Enumerator
k_ra8_hhid_step_idle	Pre-attach.
k_ra8_hhid_step_bus_reset	Drive USBRST then release.
k_ra8_hhid_step_set_address	SET_ADDRESS to assigned 1.
k_ra8_hhid_step_get_dev_desc	GET_DEVICE_DESCRIPTOR (18 B).
k_ra8_hhid_step_get_cfg_desc	GET_CONFIGURATION_DESCRIPTOR.
k_ra8_hhid_step_set_config	SET_CONFIGURATION (1).
k_ra8_hhid_step_set_interface	SET_INTERFACE (0).
k_ra8_hhid_step_walk_desc	Find HID IF; populate pipes.
k_ra8_hhid_step_get_report_desc	GET_DESCRIPTOR (Report).
k_ra8_hhid_step_done	Attach callback fires.

Definition at line 63 of file ra8_usb_hhid.c.

Function Documentation

◆ internal_configure_pipes()

ra8_err_t internal_configure_pipes ( void )

static

Configure the host-HID interrupt-IN pipe against the attached device's endpoint.

Mirrors FSP's usb_hhid_pipe_info. Only PIPE6 is mandatory (interrupt-IN). PIPE7 (interrupt-OUT) is configured only if the attached device advertises one.

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 191 of file ra8_usb_hhid.c.

References k_ra8_hhid_pipe_intr_in, k_ra8_hhid_pipe_intr_out, k_ra8_usb_ep_dir_in, k_ra8_usb_ep_dir_out, k_ra8_usb_ep_type_intr, RA8_RETURN_ON_ERROR, ra8_usb_configure_endpoint(), s_state, and s_tag.

Referenced by internal_do_walk_desc().

◆ internal_dcp_in_drain()

uint16_t internal_dcp_in_drain	(	volatile r_usb_regs_t *	reg,
		uint8_t *	out,
		uint16_t	max_len )

static

Drain the DCP (EP0) IN FIFO after a class GET_REPORT SETUP.

Mirrors the FIFO-read path inside ra8_usb_queue_out but targets pipe 0 (the DCP), which the public API rejects.

Flow:

Select CFIFO -> DCP, IN direction (CFIFOSEL.ISEL=1, MBW=16).
Wait for CFIFOCTR.FRDY (bounded poll).
Read CFIFOCTR.DTLN to get the available byte count.
16-bit LE drain into out, capped at max_len.
Write CFIFOCTR.BCLR to release the buffer.

See HUM Ch 36.2.5 "CFIFO" p 1973 and Ch 36.2.8 "CFIFOCTR" p 1979.

Parameters

[in]	reg	See implementation.
[in]	out	See implementation.
[in]	max_len	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

< Byte bits.

< Byte mask.

Definition at line 768 of file ra8_usb_hhid.c.

References r_usb_regs_t::CFIFO, r_usb_regs_t::CFIFOCTR, r_usb_regs_t::CFIFOSEL, k_byte_bits, k_byte_mask, k_ra8_fifoctr_bclr, k_ra8_fifoctr_dtln, k_ra8_fifoctr_frdy, k_ra8_fifosel_curpipe, k_ra8_fifosel_isel, k_ra8_fifosel_mbw_16, k_ra8_hhid_dcp_pipe_dcp, and k_ra8_hhid_fifo_poll_lim.

Referenced by ra8_usb_hhid_get_report().

◆ internal_do_bus_reset()

ra8_err_t internal_do_bus_reset ( void )

static

Step handler – bus-reset release + SETUP for SET_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 424 of file ra8_usb_hhid.c.

References internal_setup_set_address(), k_ra8_hhid_assigned_address, k_ra8_hhid_step_set_address, RA8_RETURN_ON_ERROR, ra8_usb_host_bus_reset(), s_state, and s_tag.

Referenced by internal_step_advance().

◆ internal_do_get_cfg_desc()

ra8_err_t internal_do_get_cfg_desc ( void )

static

Step handler – SETUP for SET_CONFIGURATION.

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 493 of file ra8_usb_hhid.c.

References internal_setup_set_config(), k_ra8_hhid_default_config, k_ra8_hhid_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

Step handler – SETUP for GET_CONFIGURATION_DESCRIPTOR.

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 473 of file ra8_usb_hhid.c.

References internal_setup_get_descriptor(), k_ra8_hhid_cfg_desc_len, k_ra8_hhid_desc_configuration, k_ra8_hhid_step_get_cfg_desc, and s_state.

Referenced by internal_step_advance().

◆ internal_do_get_report_desc()

ra8_err_t internal_do_get_report_desc ( void )

static

Step handler – finalise + fire attach callback.

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 576 of file ra8_usb_hhid.c.

References k_ra8_hhid_step_done, k_ra8_ok, and s_state.

Referenced by internal_step_advance().

◆ internal_do_idle()

ra8_err_t internal_do_idle ( void )

static

Step handler – bus-reset assert.

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 404 of file ra8_usb_hhid.c.

References k_ra8_hhid_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

Step handler – store assigned address + SETUP for GET_DEVICE_DESCRIPTOR.

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 449 of file ra8_usb_hhid.c.

References internal_setup_get_descriptor(), k_ra8_hhid_assigned_address, k_ra8_hhid_desc_device, k_ra8_hhid_dev_desc_len, k_ra8_hhid_step_get_dev_desc, RA8_RETURN_ON_ERROR, ra8_usb_set_address(), s_state, and s_tag.

Referenced by internal_step_advance().

◆ internal_do_set_config()

ra8_err_t internal_do_set_config ( void )

static

Step handler – SETUP for SET_INTERFACE.

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 513 of file ra8_usb_hhid.c.

References internal_setup_set_interface(), k_ra8_hhid_step_set_interface, and s_state.

Referenced by internal_step_advance().

◆ internal_do_set_interface()

ra8_err_t internal_do_set_interface ( void )

static

Step handler – pure software descriptor walk.

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 533 of file ra8_usb_hhid.c.

References internal_walk_config_descriptor(), k_ra8_hhid_step_walk_desc, k_ra8_ok, and s_state.

Referenced by internal_step_advance().

◆ internal_do_walk_desc()

ra8_err_t internal_do_walk_desc ( void )

static

Step handler – configure pipes + SETUP GET_DESCRIPTOR(Report).

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 554 of file ra8_usb_hhid.c.

References internal_configure_pipes(), internal_setup_get_report_descriptor(), k_ra8_hhid_report_desc_max, k_ra8_hhid_step_get_report_desc, RA8_RETURN_ON_ERROR, s_state, and s_tag.

Referenced by internal_step_advance().

◆ internal_intr_max_packet()

uint16_t internal_intr_max_packet ( ra8_usb_speed_t speed )

static

Pick the interrupt-max-packet ceiling for the negotiated speed.

Selects the USBHS ceiling for HS and the USBFS ceiling otherwise.

Parameters

[in] speed Negotiated controller speed.

Returns: Interrupt endpoint maximum packet size in bytes.

Return values

k_ra8_hhid_intr_max_packet_hs	HS controller ceiling.
k_ra8_hhid_intr_max_packet_default	FS controller ceiling.

Precondition: speed is a validated FS or HS controller selection.; The packet-size constants match their controller endpoint limits.

Postcondition: The result matches the ceiling for speed.; No state is modified.

Note: Pure and thread-safe.

Since: 0.1.0

Definition at line 167 of file ra8_usb_hhid.c.

References k_ra8_hhid_intr_max_packet_default, k_ra8_hhid_intr_max_packet_hs, and k_ra8_usb_speed_hs.

Referenced by internal_walk_config_descriptor().

◆ internal_pick_regs()

volatile r_usb_regs_t * internal_pick_regs ( ra8_usb_speed_t speed )

static

Pick the controller register window for the active speed.

Definition at line 728 of file ra8_usb_hhid.c.

References k_ra8_usb_speed_fs, k_ra8_usb_speed_hs, ra8_usb_fs(), and ra8_usb_hs().

Referenced by ra8_usb_hhid_get_report().

◆ internal_report_type_ok()

bool internal_report_type_ok ( ra8_usb_hhid_report_type_t t )

static

Validate that a ra8_usb_hhid_report_type_t value is in range.

See implementation.

Parameters

[in] t 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 645 of file ra8_usb_hhid.c.

References k_ra8_hhid_report_type_feature, k_ra8_hhid_report_type_input, and k_ra8_hhid_report_type_output.

Referenced by ra8_usb_hhid_get_report(), and ra8_usb_hhid_set_report().

◆ 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 228 of file ra8_usb_hhid.c.

References k_ra8_hhid_bm_std_dev_in, k_ra8_hhid_breq_get_descriptor, k_ra8_hhid_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_report_descriptor()

ra8_err_t internal_setup_get_report_descriptor ( uint16_t length )

static

Stage a GET_DESCRIPTOR (Report descriptor) SETUP request.

Per USB HID 1.11 sec 7.1.1 the host fetches the HID Report descriptor with bmRequestType = 0x81 (Std | Interface | In), bRequest = 0x06 (GET_DESCRIPTOR), wValue high byte = 0x22 (Report descriptor type).

Parameters

[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 339 of file ra8_usb_hhid.c.

References k_ra8_hhid_bm_std_iface_in, k_ra8_hhid_breq_get_descriptor, k_ra8_hhid_desc_report, k_ra8_hhid_shift_byte1, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_walk_desc().

◆ 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 255 of file ra8_usb_hhid.c.

References k_ra8_hhid_bm_std_dev_out, k_ra8_hhid_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 282 of file ra8_usb_hhid.c.

References k_ra8_hhid_bm_std_dev_out, k_ra8_hhid_breq_set_config, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_get_cfg_desc().

◆ internal_setup_set_interface()

ra8_err_t internal_setup_set_interface ( void )

static

Stage a SET_INTERFACE (alt 0, iface 0) SETUP request.

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 308 of file ra8_usb_hhid.c.

References k_ra8_hhid_bm_std_iface_out, k_ra8_hhid_breq_set_interface, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_set_config().

◆ internal_step_advance()

ra8_err_t internal_step_advance ( void )

static

Drive the enumeration step machine forward by one step.

Invoked from ra8_usb_hhid_step (tests) or from the CTRT branch of ra8_usb_dispatch (production). Each call advances the step counter by one and dispatches to the appropriate handler.

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 603 of file ra8_usb_hhid.c.

References internal_do_bus_reset(), internal_do_get_cfg_desc(), internal_do_get_dev_desc(), internal_do_get_report_desc(), internal_do_idle(), internal_do_set_address(), internal_do_set_config(), internal_do_set_interface(), internal_do_walk_desc(), k_ra8_hhid_step_bus_reset, k_ra8_hhid_step_get_cfg_desc, k_ra8_hhid_step_get_dev_desc, k_ra8_hhid_step_get_report_desc, k_ra8_hhid_step_idle, k_ra8_hhid_step_set_address, k_ra8_hhid_step_set_config, k_ra8_hhid_step_set_interface, k_ra8_hhid_step_walk_desc, k_ra8_ok, and s_state.

Referenced by ra8_usb_hhid_step().

◆ internal_walk_config_descriptor()

void internal_walk_config_descriptor ( void )

static

Populate s_state.device with stub descriptor data.

In production this routine walks the configuration descriptor returned in the GET_CONFIG_DESCRIPTOR data stage and picks out the HID interface (class=0x03), its interrupt-IN endpoint, the optional interrupt-OUT endpoint, and the embedded HID class descriptor (descriptor type 0x21). The starter relies on the fact that a single boot-protocol HID device (keyboard or mouse) follows a near-universal layout: interrupt-IN at EP address 1, no interrupt- OUT, single interface 0, subclass 1 (boot), protocol 1 (kb) or 2 (mouse). If the attached device deviates, the production path will overwrite these defaults during the descriptor walk.

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 373 of file ra8_usb_hhid.c.

References internal_intr_max_packet(), k_ra8_hhid_assigned_address, k_ra8_hhid_protocol_keyboard, k_ra8_hhid_subclass_boot, and s_state.

Referenced by internal_do_set_interface().

◆ ra8_usb_hhid_attach_callback()

ra8_err_t ra8_usb_hhid_attach_callback	(	ra8_usb_hhid_attach_fn_t	on_attach,
		void *	ctx )

nodiscard

Register (or detach) the attach callback.

The supplied callback fires exactly once per attach event, after the descriptor walk identifies an HID interface (class=0x03) and the matching interrupt-IN endpoint and HID class descriptor are cached. Pass NULL to detach.

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_hhid_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 700 of file ra8_usb_hhid.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_usb_hhid_close()

ra8_err_t ra8_usb_hhid_close ( void )

nodiscard

Tear down the host-HID 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-HID API calls return k_ra8_err_invalid_state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 679 of file ra8_usb_hhid.c.

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

◆ ra8_usb_hhid_get_input_report()

ra8_err_t ra8_usb_hhid_get_input_report	(	uint8_t *	out_buf,
		uint16_t	max_len,
		uint16_t *	got_len )

nodiscard

Drain the next input report from the interrupt-IN pipe.

Polling / non-blocking. Pulls bytes from the configured PIPE6 (interrupt IN) into out_buf. Returns k_ra8_err_no_data if the pipe has no bytes ready.

Parameters

[out]	out_buf	Destination buffer.
[in]	max_len	Capacity of out_buf, > 0.
[out]	got_len	Receives the number of bytes actually placed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes drained; *got_len reflects the count.
k_ra8_err_no_data	Pipe was empty.
k_ra8_err_null_ptr	out_buf or got_len was NULL.
k_ra8_err_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_invalid_arg	max_len == 0.

Precondition: ra8_usb_hhid_init succeeded.; Attach callback already fired.

Postcondition: On success *got_len reflects the actual byte count.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 961 of file ra8_usb_hhid.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhid_pipe_intr_in, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_usb_queue_out(), s_state, and s_tag.

◆ ra8_usb_hhid_get_report()

ra8_err_t ra8_usb_hhid_get_report	(	ra8_usb_hhid_report_type_t	target_report_type,
		uint8_t	target_report_id,
		uint8_t *	out_buf,
		uint16_t	max_len,
		uint16_t *	got_len )

nodiscard

Issue GET_REPORT (USB HID 1.11 sec 7.2.1) over the DCP.

Builds an 8-byte SETUP packet with bmRequestType = 0xA1 (Class | Interface | Device-to-Host), bRequest = 0x01 (GET_REPORT), and wValue = (report_type << 8) | report_id. Hands it to ra8_usb_host_setup_request; the controller drives the data + status stages.

Parameters

[in]	target_report_type	Input / Output / Feature.
[in]	target_report_id	Report ID (0 if the device uses a single unnamed report).
[out]	out_buf	Destination buffer for the report payload.
[in]	max_len	Capacity of out_buf, > 0.
[out]	got_len	Receives the number of bytes actually received.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Control transfer queued; on completion *got_len reflects the count.
k_ra8_err_null_ptr	out_buf or got_len was NULL.
k_ra8_err_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_invalid_arg	Bogus target_report_type or max_len == 0.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhid_init succeeded.; Attach callback already fired.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 820 of file ra8_usb_hhid.c.

References internal_dcp_in_drain(), internal_pick_regs(), internal_report_type_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhid_bm_class_iface_in, k_ra8_hhid_req_get_report, k_ra8_hhid_shift_byte1, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_usb_host_setup_request(), s_state, and s_tag.

◆ ra8_usb_hhid_init()

ra8_err_t ra8_usb_hhid_init ( ra8_usb_speed_t speed )

nodiscard

Bring up the host-HID 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.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Host-HID 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_hhid_attach_callback; ra8_usb_hhid_close

Since: 0.1.0

Definition at line 656 of file ra8_usb_hhid.c.

References k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_hhid_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_hhid_set_idle()

ra8_err_t ra8_usb_hhid_set_idle	(	uint8_t	duration,
		uint8_t	report_id )

nodiscard

Issue SET_IDLE (USB HID 1.11 sec 7.2.4) over the DCP.

Tells the device how often to silently re-send an unchanged input report. duration is in 4 ms units (0 = "only report on change"). Builds bmRequestType = 0x21, bRequest = 0x0A, wValue = (duration << 8) | report_id.

Parameters

[in]	duration	Idle rate, in 4 ms ticks (0..255).
[in]	report_id	Report ID, or 0 for "all reports".

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Control transfer queued.
k_ra8_err_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhid_init succeeded.; Attach callback already fired.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 910 of file ra8_usb_hhid.c.

References k_ra8_err_invalid_state, k_ra8_hhid_bm_class_iface_out, k_ra8_hhid_req_set_idle, k_ra8_hhid_shift_byte1, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_hhid_set_protocol()

ra8_err_t ra8_usb_hhid_set_protocol ( ra8_usb_hhid_protocol_select_t boot_or_report )

nodiscard

Issue SET_PROTOCOL (USB HID 1.11 sec 7.2.6) over the DCP.

Switches the device between boot protocol (wValue = 0) and report protocol (wValue = 1). Builds bmRequestType = 0x21, bRequest = 0x0B.

Parameters

[in] boot_or_report Boot or report protocol 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 device attached.
k_ra8_err_invalid_arg	boot_or_report out of range.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhid_init succeeded.; Attach callback already fired.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 935 of file ra8_usb_hhid.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hhid_bm_class_iface_out, k_ra8_hhid_proto_boot, k_ra8_hhid_proto_report, k_ra8_hhid_req_set_protocol, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_hhid_set_report()

ra8_err_t ra8_usb_hhid_set_report	(	ra8_usb_hhid_report_type_t	target_report_type,
		uint8_t	target_report_id,
		const uint8_t *	in_buf,
		uint16_t	len )

nodiscard

Issue SET_REPORT (USB HID 1.11 sec 7.2.2) over the DCP.

Builds an 8-byte SETUP packet with bmRequestType = 0x21 (Class | Interface | Host-to-Device), bRequest = 0x09 (SET_REPORT), and wValue = (report_type << 8) | report_id. The data stage payload is in_buf[0..len-1].

Parameters

[in]	target_report_type	Input / Output / Feature.
[in]	target_report_id	Report ID.
[in]	in_buf	Report payload.
[in]	len	Payload length.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Control transfer queued.
k_ra8_err_null_ptr	in_buf was NULL with non-zero len.
k_ra8_err_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_invalid_arg	Bogus target_report_type.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_hhid_init succeeded.; Attach callback already fired.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 870 of file ra8_usb_hhid.c.

References internal_report_type_ok(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_hhid_bm_class_iface_out, k_ra8_hhid_req_set_report, k_ra8_hhid_shift_byte1, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_hhid_step()

ra8_err_t ra8_usb_hhid_step ( void )

nodiscard

Drive the enumeration step machine forward by one step.

Test / debug entry point. The production path 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_hhid_init succeeded.

Postcondition: Internal enumeration step counter advances by one. When the step machine reaches the terminal state the registered attach callback fires.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 990 of file ra8_usb_hhid.c.

References internal_step_advance(), k_ra8_err_invalid_state, and s_state.

Variable Documentation

◆ s_state

ra8_usb_hhid_state_t s_state = {}

static

Definition at line 146 of file ra8_usb_hhid.c.

◆ s_tag

const char* s_tag = "USBHHID"

static

Definition at line 48 of file ra8_usb_hhid.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_usb_hhid_byte_shift_t

◆ ra8_usb_hhid_dcp_t

◆ ra8_usb_hhid_setup_field_t

◆ ra8_usb_hhid_size_t

◆ ra8_usb_hhid_step_t

Function Documentation

◆ internal_configure_pipes()

◆ internal_dcp_in_drain()

◆ internal_do_bus_reset()

◆ internal_do_get_cfg_desc()

◆ internal_do_get_dev_desc()

◆ internal_do_get_report_desc()

◆ internal_do_idle()

◆ internal_do_set_address()

◆ internal_do_set_config()

◆ internal_do_set_interface()

◆ internal_do_walk_desc()

◆ internal_intr_max_packet()

◆ internal_pick_regs()

◆ internal_report_type_ok()

◆ internal_setup_get_descriptor()

◆ internal_setup_get_report_descriptor()

◆ internal_setup_set_address()

◆ internal_setup_set_config()

◆ internal_setup_set_interface()

◆ internal_step_advance()

◆ internal_walk_config_descriptor()

◆ ra8_usb_hhid_attach_callback()

◆ ra8_usb_hhid_close()

◆ ra8_usb_hhid_get_input_report()

◆ ra8_usb_hhid_get_report()

◆ ra8_usb_hhid_init()

◆ ra8_usb_hhid_set_idle()

◆ ra8_usb_hhid_set_protocol()

◆ ra8_usb_hhid_set_report()

◆ ra8_usb_hhid_step()

Variable Documentation

◆ s_state

◆ s_tag