Native USB host-side CDC ACM class layer implementation. More...

#include "ra8_usb_hcdc.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_hcdc.c:

Data Structures
struct	ra8_usb_hcdc_state_t
	Singleton shadow state for the host-CDC driver. More...

Enumerations
enum	ra8_usb_hcdc_step_t : uint8_t { k_ra8_hcdc_step_idle = 0U , k_ra8_hcdc_step_bus_reset = 1U , k_ra8_hcdc_step_set_address = 2U , k_ra8_hcdc_step_get_dev_desc = 3U , k_ra8_hcdc_step_get_cfg_desc = 4U , k_ra8_hcdc_step_set_config = 5U , k_ra8_hcdc_step_set_interface = 6U , k_ra8_hcdc_step_walk_desc = 7U , k_ra8_hcdc_step_done = 8U }
	Enumeration step machine states. More...
enum	ra8_usb_hcdc_setup_field_t : uint8_t { k_ra8_hcdc_bm_std_dev_in = 0x80U , k_ra8_hcdc_bm_std_dev_out = 0x00U , k_ra8_hcdc_bm_std_iface_out = 0x01U , k_ra8_hcdc_breq_get_descriptor = 0x06U , k_ra8_hcdc_breq_set_address = 0x05U , k_ra8_hcdc_breq_set_config = 0x09U , k_ra8_hcdc_breq_set_interface = 0x0BU , k_ra8_hcdc_bm_class_iface_out = 0x21U , k_ra8_hcdc_desc_device = 0x01U , k_ra8_hcdc_desc_configuration = 0x02U , k_ra8_hcdc_desc_interface = 0x04U , k_ra8_hcdc_desc_endpoint = 0x05U }
	Standard chapter-9 + CDC class request encodings. More...
enum	ra8_usb_hcdc_size_t : uint16_t { k_ra8_hcdc_dev_desc_len = 18U , k_ra8_hcdc_cfg_desc_len = 9U , k_ra8_hcdc_iface_desc_len = 9U , k_ra8_hcdc_ep_desc_len = 7U , k_ra8_hcdc_line_coding_len = 7U , k_ra8_hcdc_assigned_address = 1U , k_ra8_hcdc_default_config = 1U }
	Standard descriptor sizes and request payload sizes. More...
enum	ra8_usb_hcdc_byte_shift_t : uint8_t { k_ra8_hcdc_shift_byte0 = 0U , k_ra8_hcdc_shift_byte1 = 8U , k_ra8_hcdc_shift_byte2 = 16U , k_ra8_hcdc_shift_byte3 = 24U }
	Per-byte left-shift constants for little-endian baud serialisation. More...
enum	ra8_usb_hcdc_byte_mask_t : uint32_t { k_ra8_hcdc_byte_mask = 0xFFU }
	Byte mask for little-endian baud serialisation. More...
enum	ra8_usb_hcdc_baud_min_t : uint32_t { k_ra8_hcdc_baud_min = 1U }
	Minimum legal baud the host driver allows. More...

Functions
static uint16_t	internal_bulk_max_packet (ra8_usb_speed_t speed)
	Pick the bulk-max-packet ceiling matching the negotiated speed.
static ra8_err_t	internal_configure_pipes (void)
	Configure the three host-CDC pipes against the attached device's endpoints.
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 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 – finalise pipes + fire attach callback.
static ra8_err_t	internal_step_advance (void)
	Drive the enumeration step machine forward by one step.
ra8_err_t	ra8_usb_hcdc_init (ra8_usb_speed_t speed)
	Bring up the host-CDC driver on a chosen USB controller.
ra8_err_t	ra8_usb_hcdc_close (void)
	Tear down the host-CDC driver and release the controller.
ra8_err_t	ra8_usb_hcdc_attach_callback (ra8_usb_hcdc_attach_fn_t on_attach, void *ctx)
	Register (or detach) the attach callback.
ra8_err_t	ra8_usb_hcdc_send (const uint8_t *data, uint16_t len)
	Send a chunk of bytes OUT to the attached CDC-ACM device.
ra8_err_t	ra8_usb_hcdc_recv (uint8_t out_buf, uint16_t max_len, uint16_t got_len)
	Drain a chunk of bytes IN from the attached CDC-ACM device.
ra8_err_t	ra8_usb_hcdc_set_line_coding (uint32_t baud, ra8_usb_hcdc_parity_t parity, ra8_usb_hcdc_stop_bits_t stop_bits)
	Issue SET_LINE_CODING to the attached CDC-ACM device.
ra8_err_t	ra8_usb_hcdc_step (void)
	Drive the enumeration step machine forward by one step.

Variables
static const char *	s_tag = "USBHCDC"
static ra8_usb_hcdc_state_t	s_state = {}

Detailed Description

Native USB host-side CDC ACM class layer implementation.

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

Glues the host-mode bring-up paths in ra8_usb to a CDC-ACM peripheral attached on the EK-RA8D2's USB-host port. This file is the native host-CDC class layer; FSP's r_usb_hcdc_driver.c and r_usb_hcdc.c are reference material only – nothing is pulled in verbatim.

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

usb_hcdc_init -> ra8_usb_hcdc_init
usb_hcdc_enumeration -> internal_enum_* step machine driven by ra8_usb_hcdc_step.
usb_hcdc_pipe_info -> internal_walk_config_descriptor
R_USB_HCDC_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_hcdc_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_hcdc.c.

Enumeration Type Documentation

◆ ra8_usb_hcdc_baud_min_t

enum ra8_usb_hcdc_baud_min_t : uint32_t

Minimum legal baud the host driver allows.

Enumerator
k_ra8_hcdc_baud_min	0 baud is rejected as bogus.

Definition at line 131 of file ra8_usb_hcdc.c.

◆ ra8_usb_hcdc_byte_mask_t

enum ra8_usb_hcdc_byte_mask_t : uint32_t

Byte mask for little-endian baud serialisation.

Enumerator
k_ra8_hcdc_byte_mask	Single-byte extraction mask.

Definition at line 123 of file ra8_usb_hcdc.c.

◆ ra8_usb_hcdc_byte_shift_t

enum ra8_usb_hcdc_byte_shift_t : uint8_t

Per-byte left-shift constants for little-endian baud serialisation.

Enumerator
k_ra8_hcdc_shift_byte0	RA8 hcdc shift byte0.
k_ra8_hcdc_shift_byte1	RA8 hcdc shift byte1.
k_ra8_hcdc_shift_byte2	RA8 hcdc shift byte2.
k_ra8_hcdc_shift_byte3	RA8 hcdc shift byte3.

Definition at line 112 of file ra8_usb_hcdc.c.

◆ ra8_usb_hcdc_setup_field_t

enum ra8_usb_hcdc_setup_field_t : uint8_t

Standard chapter-9 + CDC class request encodings.

Enumerator
k_ra8_hcdc_bm_std_dev_in	Std \| Device \| In.
k_ra8_hcdc_bm_std_dev_out	Std \| Device \| Out.
k_ra8_hcdc_bm_std_iface_out	Std \| Interface \| Out.
k_ra8_hcdc_breq_get_descriptor	GET_DESCRIPTOR.
k_ra8_hcdc_breq_set_address	SET_ADDRESS.
k_ra8_hcdc_breq_set_config	SET_CONFIGURATION.
k_ra8_hcdc_breq_set_interface	SET_INTERFACE.
k_ra8_hcdc_bm_class_iface_out	Class \| Interface \| Out.
k_ra8_hcdc_desc_device	DEVICE descriptor.
k_ra8_hcdc_desc_configuration	CONFIGURATION descriptor.
k_ra8_hcdc_desc_interface	INTERFACE descriptor.
k_ra8_hcdc_desc_endpoint	ENDPOINT descriptor.

Definition at line 75 of file ra8_usb_hcdc.c.

◆ ra8_usb_hcdc_size_t

enum ra8_usb_hcdc_size_t : uint16_t

Standard descriptor sizes and request payload sizes.

Enumerator
k_ra8_hcdc_dev_desc_len	USB DEVICE descriptor.
k_ra8_hcdc_cfg_desc_len	CONFIGURATION descriptor hdr.
k_ra8_hcdc_iface_desc_len	INTERFACE descriptor.
k_ra8_hcdc_ep_desc_len	ENDPOINT descriptor.
k_ra8_hcdc_line_coding_len	SET_LINE_CODING payload.
k_ra8_hcdc_assigned_address	First assigned device addr.
k_ra8_hcdc_default_config	bConfigurationValue = 1.

Definition at line 97 of file ra8_usb_hcdc.c.

◆ ra8_usb_hcdc_step_t

enum ra8_usb_hcdc_step_t : uint8_t

Enumeration step machine states.

Mirrors FSP's g_usb_hcdc_smpl_class_seq step indices in r_usb_hcdc_driver.c. Each step issues exactly one SETUP via ra8_usb_host_setup_request; the next CTRT interrupt advances to the next step.

Enumerator
k_ra8_hcdc_step_idle	Pre-attach.
k_ra8_hcdc_step_bus_reset	Drive USBRST then release.
k_ra8_hcdc_step_set_address	SET_ADDRESS to assigned 1.
k_ra8_hcdc_step_get_dev_desc	GET_DEVICE_DESCRIPTOR (18 B).
k_ra8_hcdc_step_get_cfg_desc	GET_CONFIGURATION_DESCRIPTOR.
k_ra8_hcdc_step_set_config	SET_CONFIGURATION (1).
k_ra8_hcdc_step_set_interface	SET_INTERFACE (0).
k_ra8_hcdc_step_walk_desc	Find CDC IFs; populate pipes.
k_ra8_hcdc_step_done	Attach callback fires.

Definition at line 59 of file ra8_usb_hcdc.c.

Function Documentation

◆ internal_bulk_max_packet()

uint16_t internal_bulk_max_packet ( ra8_usb_speed_t speed )

static

Pick the bulk-max-packet ceiling matching the negotiated speed.

See implementation.

Parameters

[in] speed 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 176 of file ra8_usb_hcdc.c.

References k_ra8_hcdc_bulk_max_packet_fs, k_ra8_hcdc_bulk_max_packet_hs, and k_ra8_usb_speed_hs.

Referenced by internal_configure_pipes(), and internal_walk_config_descriptor().

◆ internal_configure_pipes()

ra8_err_t internal_configure_pipes ( void )

static

Configure the three host-CDC pipes against the attached device's endpoints.

Mirrors FSP's usb_hcdc_pipe_info (r_usb_hcdc_driver.c). Bulk pipes are PIPE1 / PIPE2; the notification pipe is PIPE6.

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 200 of file ra8_usb_hcdc.c.

References internal_bulk_max_packet(), k_ra8_hcdc_intr_max_packet, k_ra8_hcdc_pipe_bulk_in, k_ra8_hcdc_pipe_bulk_out, k_ra8_hcdc_pipe_intr_in, k_ra8_usb_ep_dir_in, k_ra8_usb_ep_dir_out, k_ra8_usb_ep_type_bulk, 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_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 406 of file ra8_usb_hcdc.c.

References internal_setup_set_address(), k_ra8_hcdc_assigned_address, k_ra8_hcdc_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 475 of file ra8_usb_hcdc.c.

References internal_setup_set_config(), k_ra8_hcdc_default_config, k_ra8_hcdc_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 455 of file ra8_usb_hcdc.c.

References internal_setup_get_descriptor(), k_ra8_hcdc_cfg_desc_len, k_ra8_hcdc_desc_configuration, k_ra8_hcdc_step_get_cfg_desc, 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 386 of file ra8_usb_hcdc.c.

References k_ra8_hcdc_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 431 of file ra8_usb_hcdc.c.

References internal_setup_get_descriptor(), k_ra8_hcdc_assigned_address, k_ra8_hcdc_desc_device, k_ra8_hcdc_dev_desc_len, k_ra8_hcdc_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 495 of file ra8_usb_hcdc.c.

References internal_setup_set_interface(), k_ra8_hcdc_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 515 of file ra8_usb_hcdc.c.

References internal_walk_config_descriptor(), k_ra8_hcdc_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 – finalise pipes + 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 536 of file ra8_usb_hcdc.c.

References internal_configure_pipes(), k_ra8_hcdc_step_done, k_ra8_ok, RA8_RETURN_ON_ERROR, s_state, and s_tag.

Referenced by internal_step_advance().

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

Helper for internal_step_* so the step machine itself stays linear / readable.

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 247 of file ra8_usb_hcdc.c.

References k_ra8_hcdc_bm_std_dev_in, k_ra8_hcdc_breq_get_descriptor, k_ra8_hcdc_shift_byte1, ra8_usb_host_setup_request(), and s_state.

Referenced by internal_do_get_dev_desc(), and internal_do_set_address().

◆ 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 274 of file ra8_usb_hcdc.c.

References k_ra8_hcdc_bm_std_dev_out, k_ra8_hcdc_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 301 of file ra8_usb_hcdc.c.

References k_ra8_hcdc_bm_std_dev_out, k_ra8_hcdc_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 327 of file ra8_usb_hcdc.c.

References k_ra8_hcdc_bm_std_iface_out, k_ra8_hcdc_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_hcdc_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 565 of file ra8_usb_hcdc.c.

References internal_do_bus_reset(), internal_do_get_cfg_desc(), internal_do_get_dev_desc(), internal_do_idle(), internal_do_set_address(), internal_do_set_config(), internal_do_set_interface(), internal_do_walk_desc(), k_ra8_hcdc_step_bus_reset, k_ra8_hcdc_step_get_cfg_desc, k_ra8_hcdc_step_get_dev_desc, k_ra8_hcdc_step_idle, k_ra8_hcdc_step_set_address, k_ra8_hcdc_step_set_config, k_ra8_hcdc_step_set_interface, k_ra8_hcdc_step_walk_desc, k_ra8_ok, and s_state.

Referenced by ra8_usb_hcdc_step().

◆ internal_walk_config_descriptor()

void internal_walk_config_descriptor ( void )

static

Populate s_state.device with stub descriptor data.

In production this routine would walk the configuration descriptor returned in the GET_CONFIG_DESCRIPTOR data stage and pick out the CDC control + data interfaces and their bulk + intr endpoints. The starter relies on the fact that a single CDC-ACM device follows a near-universal layout: bulk-IN at EP address 1, bulk-OUT at EP address 2, notification IN at EP address 3 (also the layout the device-side CDC class in ra8_usb_cdc.c advertises). 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 360 of file ra8_usb_hcdc.c.

References internal_bulk_max_packet(), k_ra8_hcdc_assigned_address, and s_state.

Referenced by internal_do_set_interface().

◆ ra8_usb_hcdc_attach_callback()

ra8_err_t ra8_usb_hcdc_attach_callback	(	ra8_usb_hcdc_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 a CDC-ACM control + data interface pair on the attached device. 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_hcdc_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 639 of file ra8_usb_hcdc.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_usb_hcdc_close()

ra8_err_t ra8_usb_hcdc_close ( void )

nodiscard

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 618 of file ra8_usb_hcdc.c.

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

◆ ra8_usb_hcdc_init()

ra8_err_t ra8_usb_hcdc_init ( ra8_usb_speed_t speed )

nodiscard

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

Initialises the underlying ra8_usb driver in HOST mode for speed, programs the DCP for 64-byte EP0 control transfers, leaves the bus in the "wait for attach" state (UACT cleared), and arms the internal enumeration step machine.

The ra8_usb_dispatch callback path drives enumeration once a device attaches: detection from SYSSTS0.LNST, then the chapter-9 sequence (bus reset, SET_ADDRESS, GET_DEVICE_DESCRIPTOR, GET_CONFIG_DESCRIPTOR, SET_CONFIG, SET_INTERFACE), then the CDC-class descriptor walk.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Host-CDC 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 yet.

Note: Not thread-safe.

See also: ra8_usb_hcdc_attach_callback; ra8_usb_hcdc_close

Since: 0.1.0

Definition at line 595 of file ra8_usb_hcdc.c.

References k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_hcdc_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_hcdc_recv()

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

nodiscard

Drain a chunk of bytes IN from the attached CDC-ACM device.

Polling / non-blocking. Mirrors ra8_usb_cdc_recv on the host side: pulls bytes from PIPE1 (bulk 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_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_invalid_arg	Bad out_buf / max_len / got_len.

Precondition: ra8_usb_hcdc_init succeeded.; Attach callback already fired.; out_buf, got_len non-NULL, max_len > 0.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 668 of file ra8_usb_hcdc.c.

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

◆ ra8_usb_hcdc_send()

ra8_err_t ra8_usb_hcdc_send	(	const uint8_t *	data,
		uint16_t	len )

nodiscard

Send a chunk of bytes OUT to the attached CDC-ACM device.

Mirrors ra8_usb_cdc_send but on the host side: sources the bytes from data and queues them on PIPE2 (bulk OUT) so the controller delivers them at the next OUT token. Short / zero-length packets are handled.

Parameters

[in]	data	Buffer to transmit. NULL allowed iff len == 0.
[in]	len	Byte count, 0..bulk_max_packet of the negotiated speed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer queued.
k_ra8_err_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_invalid_arg	Bad data / len.

Precondition: ra8_usb_hcdc_init succeeded.; Attach callback already fired (a device is enumerated).

Postcondition: Bytes will be delivered on the next bulk OUT token.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 654 of file ra8_usb_hcdc.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hcdc_pipe_bulk_out, ra8_usb_queue_in(), and s_state.

◆ ra8_usb_hcdc_set_line_coding()

ra8_err_t ra8_usb_hcdc_set_line_coding	(	uint32_t	baud,
		ra8_usb_hcdc_parity_t	parity,
		ra8_usb_hcdc_stop_bits_t	stop_bits )

nodiscard

Issue SET_LINE_CODING to the attached CDC-ACM device.

Builds a 7-byte SET_LINE_CODING payload (USB CDC PSTN spec rev 1.20 table 17), formats the matching SETUP packet, and hands it to ra8_usb_host_setup_request. The driver's enumeration step machine handles the data + status stages.

Parameters

[in]	baud	Bits/sec (e.g. 9600, 115200, 921600).
[in]	parity	Parity selection.
[in]	stop_bits	Stop-bit selection.

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	parity / stop_bits out of range or baud is zero.
k_ra8_err_busy	A control transfer is already in flight.

Precondition: ra8_usb_hcdc_init succeeded.; Attach callback already fired.

Postcondition: DCP control transfer queued at the controller.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 697 of file ra8_usb_hcdc.c.

References k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_hcdc_baud_min, k_ra8_hcdc_bm_class_iface_out, k_ra8_hcdc_line_coding_len, k_ra8_hcdc_parity_space, k_ra8_hcdc_req_set_line_coding, k_ra8_hcdc_stop_2, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_hcdc_step()

ra8_err_t ra8_usb_hcdc_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_hcdc_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 744 of file ra8_usb_hcdc.c.

References internal_step_advance(), k_ra8_err_invalid_state, and s_state.

Variable Documentation

◆ s_state

ra8_usb_hcdc_state_t s_state = {}

static

Definition at line 154 of file ra8_usb_hcdc.c.

◆ s_tag

const char* s_tag = "USBHCDC"

static

Definition at line 43 of file ra8_usb_hcdc.c.

Data Structures

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_usb_hcdc_baud_min_t

◆ ra8_usb_hcdc_byte_mask_t

◆ ra8_usb_hcdc_byte_shift_t

◆ ra8_usb_hcdc_setup_field_t

◆ ra8_usb_hcdc_size_t

◆ ra8_usb_hcdc_step_t

Function Documentation

◆ internal_bulk_max_packet()

◆ internal_configure_pipes()

◆ internal_do_bus_reset()

◆ internal_do_get_cfg_desc()

◆ internal_do_get_dev_desc()

◆ internal_do_idle()

◆ internal_do_set_address()

◆ internal_do_set_config()

◆ internal_do_set_interface()

◆ internal_do_walk_desc()

◆ internal_setup_get_descriptor()

◆ internal_setup_set_address()

◆ internal_setup_set_config()

◆ internal_setup_set_interface()

◆ internal_step_advance()

◆ internal_walk_config_descriptor()

◆ ra8_usb_hcdc_attach_callback()

◆ ra8_usb_hcdc_close()

◆ ra8_usb_hcdc_init()

◆ ra8_usb_hcdc_recv()

◆ ra8_usb_hcdc_send()

◆ ra8_usb_hcdc_set_line_coding()

◆ ra8_usb_hcdc_step()

Variable Documentation

◆ s_state

◆ s_tag