Native USB host-side CDC ACM (Communications Device Class -Abstract Control Model) class layer. More...

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

Include dependency graph for ra8_usb_hcdc.h:

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

Data Structures
struct	ra8_usb_hcdc_device_t
	Snapshot of the attached CDC-ACM device, passed to the attach callback. More...

Typedefs
typedef void(*	ra8_usb_hcdc_attach_fn_t) (void ctx, const ra8_usb_hcdc_device_t device)
	Attach-callback signature.

Enumerations
enum	ra8_usb_hcdc_pipe_t : uint8_t { k_ra8_hcdc_pipe_bulk_in = 1U , k_ra8_hcdc_pipe_bulk_out = 2U , k_ra8_hcdc_pipe_intr_in = 6U }
	PIPE numbers used by the host-CDC driver for the attached peripheral's endpoints. More...
enum	ra8_usb_hcdc_packet_t : uint16_t { k_ra8_hcdc_bulk_max_packet_fs = 64U , k_ra8_hcdc_bulk_max_packet_hs = 512U , k_ra8_hcdc_intr_max_packet = 8U }
	Packet sizing for the attached device's bulk + interrupt endpoints (these are the maxima the host pipes are sized for; the actual values come from the device's descriptors). More...
enum	ra8_usb_hcdc_class_t : uint8_t { k_ra8_hcdc_class_comms = 0x02U , k_ra8_hcdc_subclass_acm = 0x02U , k_ra8_hcdc_protocol_at_v25 = 0x01U , k_ra8_hcdc_class_data = 0x0AU , k_ra8_hcdc_subclass_zero = 0x00U , k_ra8_hcdc_protocol_zero = 0x00U }
	Class / subclass / protocol triplets that identify a CDC ACM function within an attached USB device's descriptor walk. More...
enum	ra8_usb_hcdc_request_t : uint8_t { k_ra8_hcdc_req_set_line_coding = 0x20U , k_ra8_hcdc_req_get_line_coding = 0x21U , k_ra8_hcdc_req_set_control_line_state = 0x22U }
	CDC class-specific request codes the host issues to the attached device. More...
enum	ra8_usb_hcdc_parity_t : uint8_t { k_ra8_hcdc_parity_none = 0U , k_ra8_hcdc_parity_odd = 1U , k_ra8_hcdc_parity_even = 2U , k_ra8_hcdc_parity_mark = 3U , k_ra8_hcdc_parity_space = 4U }
	Parity selector used by ra8_usb_hcdc_set_line_coding. More...
enum	ra8_usb_hcdc_stop_bits_t : uint8_t { k_ra8_hcdc_stop_1 = 0U , k_ra8_hcdc_stop_1_5 = 1U , k_ra8_hcdc_stop_2 = 2U }
	Stop-bit selector used by ra8_usb_hcdc_set_line_coding. More...

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

Detailed Description

Native USB host-side CDC ACM (Communications Device Class -

Abstract Control Model) class layer.

Glues the host-mode bring-up paths in ra8_usb to a CDC-ACM peripheral attached on the EK-RA8D2's USB-host port. Mirrors FSP's r_usb_hcdc host-CDC class flow but compiled as part of this tree with no FSP / CherryUSB / TinyUSB binaries pulled in.

Lifecycle:

ra8_usb_hcdc_init(speed) flips the controller to host mode, enables SOF generation and waits for SYSSTS0.LNST to report a J-state attach.
The driver runs the chapter-9 enumeration step machine (Reset -> SET_ADDRESS -> GET_DEVICE_DESCRIPTOR -> GET_CONFIG_DESCRIPTOR -> SET_CONFIG -> SET_INTERFACE) over the DCP and walks the configuration descriptor for the CDC control + data interfaces.
When enumeration completes, the registered attach callback fires once with the bulk-IN / bulk-OUT pipe handles.
ra8_usb_hcdc_send / ra8_usb_hcdc_recv move bytes through the bulk pipes, mirroring the device-side ra8_usb_cdc_send / ra8_usb_cdc_recv surface.
ra8_usb_hcdc_set_line_coding issues the CDC class control transfer to update the attached device's line coding.
ra8_usb_hcdc_close() drops bus power and releases the device.

The starter does not support hubs; it tracks a single attached CDC-ACM device. Hub class enumeration is tracked as a deferred follow-up.

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

Definition in file ra8_usb_hcdc.h.

Typedef Documentation

◆ ra8_usb_hcdc_attach_fn_t

typedef void(* ra8_usb_hcdc_attach_fn_t) (void *ctx, const ra8_usb_hcdc_device_t *device)

Attach-callback signature.

Parameters

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

Note: Invoked from the dispatch site (typically ISR context) after enumeration completes successfully.

Definition at line 174 of file ra8_usb_hcdc.h.

Enumeration Type Documentation

◆ ra8_usb_hcdc_class_t

enum ra8_usb_hcdc_class_t : uint8_t

Class / subclass / protocol triplets that identify a CDC ACM function within an attached USB device's descriptor walk.

Numbered from the USB CDC PSTN subclass spec rev 1.20 and the USB-IF "Class Codes" registry.

Enumerator
k_ra8_hcdc_class_comms	CDC control interface class.
k_ra8_hcdc_subclass_acm	Abstract Control Model.
k_ra8_hcdc_protocol_at_v25	AT command set (V.25ter).
k_ra8_hcdc_class_data	CDC data interface class.
k_ra8_hcdc_subclass_zero	Data subclass = 0.
k_ra8_hcdc_protocol_zero	Data protocol = 0.

Definition at line 90 of file ra8_usb_hcdc.h.

◆ ra8_usb_hcdc_packet_t

enum ra8_usb_hcdc_packet_t : uint16_t

Packet sizing for the attached device's bulk + interrupt endpoints (these are the maxima the host pipes are sized for; the actual values come from the device's descriptors).

Enumerator
k_ra8_hcdc_bulk_max_packet_fs	Bulk size at full speed.
k_ra8_hcdc_bulk_max_packet_hs	Bulk size at high speed.
k_ra8_hcdc_intr_max_packet	Notification pipe size.

Definition at line 76 of file ra8_usb_hcdc.h.

◆ ra8_usb_hcdc_parity_t

enum ra8_usb_hcdc_parity_t : uint8_t

Parity selector used by ra8_usb_hcdc_set_line_coding.

Wire-level value matches USB CDC PSTN spec rev 1.20 table 17 (SET_LINE_CODING bParityType field).

Enumerator
k_ra8_hcdc_parity_none	No parity.
k_ra8_hcdc_parity_odd	Odd parity.
k_ra8_hcdc_parity_even	Even parity.
k_ra8_hcdc_parity_mark	Mark parity.
k_ra8_hcdc_parity_space	Space parity.

Definition at line 117 of file ra8_usb_hcdc.h.

◆ ra8_usb_hcdc_pipe_t

enum ra8_usb_hcdc_pipe_t : uint8_t

PIPE numbers used by the host-CDC driver for the attached peripheral's endpoints.

FSP / RA8D2 PIPE assignment rules constrain bulk pipes to PIPE1..PIPE5 and interrupt pipes to PIPE6..PIPE9.

Enumerator
k_ra8_hcdc_pipe_bulk_in	PIPE1 -> attached EP bulk IN.
k_ra8_hcdc_pipe_bulk_out	PIPE2 -> attached EP bulk OUT.
k_ra8_hcdc_pipe_intr_in	PIPE6 -> attached EP intr IN.

Definition at line 64 of file ra8_usb_hcdc.h.

◆ ra8_usb_hcdc_request_t

enum ra8_usb_hcdc_request_t : uint8_t

CDC class-specific request codes the host issues to the attached device.

Enumerator
k_ra8_hcdc_req_set_line_coding	7-byte payload.
k_ra8_hcdc_req_get_line_coding	7-byte payload.
k_ra8_hcdc_req_set_control_line_state	0-byte payload.

Definition at line 104 of file ra8_usb_hcdc.h.

◆ ra8_usb_hcdc_stop_bits_t

enum ra8_usb_hcdc_stop_bits_t : uint8_t

Stop-bit selector used by ra8_usb_hcdc_set_line_coding.

Wire-level value matches USB CDC PSTN spec rev 1.20 table 17 (SET_LINE_CODING bCharFormat field).

Enumerator
k_ra8_hcdc_stop_1	1 stop bit.
k_ra8_hcdc_stop_1_5	1.5 stop bits.
k_ra8_hcdc_stop_2	2 stop bits.

Definition at line 132 of file ra8_usb_hcdc.h.

Function Documentation

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

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_usb_hcdc_attach_fn_t

Enumeration Type Documentation

◆ ra8_usb_hcdc_class_t

◆ ra8_usb_hcdc_packet_t

◆ ra8_usb_hcdc_parity_t

◆ ra8_usb_hcdc_pipe_t

◆ ra8_usb_hcdc_request_t

◆ ra8_usb_hcdc_stop_bits_t

Function Documentation

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