Native USB CDC ACM (Communications Device Class - AbstractControl Model) class layer. More...

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

Include dependency graph for ra8_usb_cdc.h:

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

Data Structures
struct	ra8_usb_cdc_line_coding_t
	7-byte payload of SET_LINE_CODING / GET_LINE_CODING. More...

Enumerations
enum	ra8_usb_cdc_pipe_t : uint8_t { k_ra8_cdc_pipe_bulk_in = 1U , k_ra8_cdc_pipe_bulk_out = 2U , k_ra8_cdc_pipe_intr_in = 6U }
	PIPE numbers used by the CDC ACM function. More...
enum	ra8_usb_cdc_ep_t : uint8_t { k_ra8_cdc_ep_bulk_in_addr = 1U , k_ra8_cdc_ep_bulk_out_addr = 2U , k_ra8_cdc_ep_intr_in_addr = 3U }
	USB endpoint addresses used by the CDC ACM function. More...
enum	ra8_usb_cdc_packet_t : uint16_t { k_ra8_cdc_bulk_max_packet_fs = 64U , k_ra8_cdc_bulk_max_packet_hs = 512U , k_ra8_cdc_intr_max_packet = 8U }
	Packet sizing for the CDC ACM bulk + interrupt pipes. More...
enum	ra8_usb_cdc_request_t : uint8_t { k_ra8_cdc_req_set_line_coding = 0x20U , k_ra8_cdc_req_get_line_coding = 0x21U , k_ra8_cdc_req_set_control_line_state = 0x22U }
	CDC class-specific request codes carried in bRequest. More...
enum	ra8_usb_cdc_line_state_t : uint16_t { k_ra8_cdc_line_state_dtr = 0x0001U , k_ra8_cdc_line_state_rts = 0x0002U }
	Bits inside wValue for SET_CONTROL_LINE_STATE. More...

Functions
ra8_err_t	ra8_usb_cdc_init (ra8_usb_speed_t speed)
	Bring up the CDC ACM function on a chosen USB controller.
ra8_err_t	ra8_usb_cdc_deinit (void)
	Tear down the CDC function and release the underlying controller.
ra8_err_t	ra8_usb_cdc_attach (bool attached)
	Raise / drop the D+ pull-up to advertise the CDC function.
ra8_err_t	ra8_usb_cdc_send (const uint8_t *data, uint16_t len)
	Send a chunk of bytes IN (device -> host).
ra8_err_t	ra8_usb_cdc_recv (uint8_t out_buf, uint16_t inout_len)
	Drain a chunk of bytes OUT (host -> device).
ra8_err_t	ra8_usb_cdc_handle_setup (const ra8_usb_setup_t *setup)
	Process a class-specific SETUP packet.
ra8_err_t	ra8_usb_cdc_get_line_coding (ra8_usb_cdc_line_coding_t *out)
	Get the most recently negotiated line coding.
ra8_err_t	ra8_usb_cdc_get_line_state (bool out_dtr, bool out_rts)
	Get the most recently received DTR / RTS bits.

Detailed Description

Native USB CDC ACM (Communications Device Class - Abstract

Control Model) class layer.

Glues the device-mode ra8_usb controller driver to a USB CDC ACM function so the host enumerates the board as a serial port (/dev/ttyACM0 on Linux / macOS; COMn on Windows). The implementation is from-scratch – no FSP r_usb_pcdc.c, no CherryUSB cdc_acm.c, no TinyUSB. It mirrors the surface FSP's peripheral CDC class exposes: line-coding storage, DTR / RTS tracking, and a bulk IN / bulk OUT byte pipe.

The descriptor table built by ra8_usb_cdc_init advertises:

One configuration with two interfaces (CDC control + data).
EP0 64-byte default control pipe.
EP1 IN, bulk, 64 bytes (data IN).
EP2 OUT, bulk, 64 bytes (data OUT).
EP3 IN, interrupt, 8 bytes (notification, unused but required).

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

Definition in file ra8_usb_cdc.h.

Enumeration Type Documentation

◆ ra8_usb_cdc_ep_t

enum ra8_usb_cdc_ep_t : uint8_t

USB endpoint addresses used by the CDC ACM function.

Enumerator
k_ra8_cdc_ep_bulk_in_addr	EP1 IN address.
k_ra8_cdc_ep_bulk_out_addr	EP2 OUT address.
k_ra8_cdc_ep_intr_in_addr	EP3 IN address.

Definition at line 63 of file ra8_usb_cdc.h.

◆ ra8_usb_cdc_line_state_t

enum ra8_usb_cdc_line_state_t : uint16_t

Bits inside wValue for SET_CONTROL_LINE_STATE.

Enumerator
k_ra8_cdc_line_state_dtr	Data terminal ready.
k_ra8_cdc_line_state_rts	Request to send.

Definition at line 95 of file ra8_usb_cdc.h.

◆ ra8_usb_cdc_packet_t

enum ra8_usb_cdc_packet_t : uint16_t

Packet sizing for the CDC ACM bulk + interrupt pipes.

Enumerator
k_ra8_cdc_bulk_max_packet_fs	Bulk size at full speed.
k_ra8_cdc_bulk_max_packet_hs	Bulk size at high speed.
k_ra8_cdc_intr_max_packet	Notification pipe size.

Definition at line 73 of file ra8_usb_cdc.h.

◆ ra8_usb_cdc_pipe_t

enum ra8_usb_cdc_pipe_t : uint8_t

PIPE numbers used by the CDC ACM function.

FSP / RA8D2 PIPE assignment rules constrain bulk pipes to PIPE1..PIPE5 and interrupt pipes to PIPE6..PIPE9. We keep the mapping deterministic to make wireshark / Linux dmesg traces easier to follow.

Enumerator
k_ra8_cdc_pipe_bulk_in	PIPE1 -> EP1 IN (bulk).
k_ra8_cdc_pipe_bulk_out	PIPE2 -> EP2 OUT (bulk).
k_ra8_cdc_pipe_intr_in	PIPE6 -> EP3 IN (interrupt).

Definition at line 53 of file ra8_usb_cdc.h.

◆ ra8_usb_cdc_request_t

enum ra8_usb_cdc_request_t : uint8_t

CDC class-specific request codes carried in bRequest.

Numbered from the USB CDC PSTN subclass spec rev 1.20.

Enumerator
k_ra8_cdc_req_set_line_coding	7-byte payload.
k_ra8_cdc_req_get_line_coding	7-byte payload.
k_ra8_cdc_req_set_control_line_state	0-byte payload.

Definition at line 85 of file ra8_usb_cdc.h.

Function Documentation

◆ ra8_usb_cdc_attach()

ra8_err_t ra8_usb_cdc_attach ( bool attached )

nodiscard

Raise / drop the D+ pull-up to advertise the CDC function.

Parameters

[in] attached true to attach, false to detach.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	State updated.
k_ra8_err_invalid_state	CDC not initialized.

Precondition: ra8_usb_cdc_init succeeded.

Postcondition: On success, the controller's SYSCFG.DPRPU matches attached.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 290 of file ra8_usb_cdc.c.

References k_ra8_err_invalid_state, ra8_usb_device_attach(), and s_state.

◆ ra8_usb_cdc_deinit()

ra8_err_t ra8_usb_cdc_deinit ( void )

nodiscard

Tear down the CDC function and release the underlying controller.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Released.
k_ra8_err_invalid_state	CDC was never initialized.

Precondition: Single-threaded shutdown context.

Postcondition: Subsequent CDC API calls return k_ra8_err_invalid_state.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 277 of file ra8_usb_cdc.c.

References k_ra8_err_invalid_state, ra8_usb_device_attach(), ra8_usb_device_deinit(), and s_state.

◆ ra8_usb_cdc_get_line_coding()

ra8_err_t ra8_usb_cdc_get_line_coding ( ra8_usb_cdc_line_coding_t * out )

nodiscard

Get the most recently negotiated line coding.

Parameters

[out] out Receives the 7-byte coding payload.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Copied.
k_ra8_err_invalid_arg	out was NULL.
k_ra8_err_invalid_state	CDC not initialized.

Precondition: out non-NULL.

Postcondition: No internal state mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 457 of file ra8_usb_cdc.c.

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

◆ ra8_usb_cdc_get_line_state()

ra8_err_t ra8_usb_cdc_get_line_state	(	bool *	out_dtr,
		bool *	out_rts )

nodiscard

Get the most recently received DTR / RTS bits.

Parameters

[out]	out_dtr	true if DTR asserted.
[out]	out_rts	true if RTS asserted.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	State copied.
k_ra8_err_invalid_arg	out_dtr / out_rts were NULL.
k_ra8_err_invalid_state	CDC not initialized.

Precondition: Output pointers non-NULL.

Postcondition: No internal state mutated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 467 of file ra8_usb_cdc.c.

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

◆ ra8_usb_cdc_handle_setup()

ra8_err_t ra8_usb_cdc_handle_setup ( const ra8_usb_setup_t * setup )

nodiscard

Process a class-specific SETUP packet.

Switches on b_request and either updates the stored line coding, returns the line coding payload, or stores the DTR / RTS bits. Standard (non-class) SETUPs are rejected with k_ra8_err_not_supported so the caller can fall back to its own standard-request handler.

Parameters

[in] setup The SETUP packet returned by ra8_usb_read_setup_if_valid.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SETUP handled (status stage queued internally).
k_ra8_err_invalid_state	CDC not initialized.
k_ra8_err_invalid_arg	setup was NULL.
k_ra8_err_not_supported	bRequest is not a CDC ACM request this layer cares about.

Precondition: ra8_usb_cdc_init succeeded.

Postcondition: Stored line coding / line state updated.

Note: Call from the CTRT ISR path of ra8_usb.

Since: 0.1.0

Definition at line 444 of file ra8_usb_cdc.c.

References ra8_usb_setup_t::bm_request_type, internal_dispatch_class_setup(), k_ra8_cdc_bm_class_recip_iface, k_ra8_cdc_bm_class_recip_in, k_ra8_err_invalid_state, k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, s_state, and s_tag.

◆ ra8_usb_cdc_init()

ra8_err_t ra8_usb_cdc_init ( ra8_usb_speed_t speed )

nodiscard

Bring up the CDC ACM function on a chosen USB controller.

Initialises the underlying ra8_usb driver for speed, configures PIPE1 (bulk IN), PIPE2 (bulk OUT), PIPE6 (interrupt IN), seeds a default 9600/8/N/1 line coding, and stores DTR/RTS = 0. The D+ pull-up stays down – the caller raises it via ra8_usb_cdc_attach once it is ready to enumerate.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	CDC function ready.
k_ra8_err_invalid_arg	speed out of range.
k_ra8_err_hw_init_failed	Underlying ra8_usb_device_init failed.

Precondition: Single-threaded init context.

Postcondition: ra8_usb_cdc_get_line_coding returns 9600/8/N/1.; Bulk + interrupt pipes are configured but not attached.

Note: Not thread-safe.

See also: ra8_usb_cdc_attach

Since: 0.1.0

Definition at line 251 of file ra8_usb_cdc.c.

References internal_configure_pipes(), internal_default_coding(), k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_usb_speed_fs, k_ra8_usb_speed_hs, ra8_log_error_val, ra8_log_info, ra8_usb_device_deinit(), ra8_usb_device_init(), s_state, and s_tag.

◆ ra8_usb_cdc_recv()

ra8_err_t ra8_usb_cdc_recv	(	uint8_t *	out_buf,
		uint16_t *	inout_len )

nodiscard

Drain a chunk of bytes OUT (host -> device).

Parameters

[out]	out_buf	Destination buffer.
[in,out]	inout_len	On entry: capacity. On exit: bytes received.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes received.
k_ra8_err_no_data	Pipe was empty.
k_ra8_err_invalid_state	CDC not initialized.
k_ra8_err_invalid_arg	Bad pointers / capacity.

Precondition: out_buf, inout_len non-NULL, *inout_len > 0.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 314 of file ra8_usb_cdc.c.

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

◆ ra8_usb_cdc_send()

ra8_err_t ra8_usb_cdc_send	(	const uint8_t *	data,
		uint16_t	len )

nodiscard

Send a chunk of bytes IN (device -> host).

Parameters

[in]	data	Buffer to send.
[in]	len	Byte count, 0..bulk_max_packet of the speed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer queued.
k_ra8_err_invalid_state	CDC not initialized.
k_ra8_err_invalid_arg	Bad data / len.

Precondition: ra8_usb_cdc_init succeeded.

Postcondition: Bytes are visible on the host's TTY after the next IN token.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 303 of file ra8_usb_cdc.c.

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

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_usb_cdc_ep_t

◆ ra8_usb_cdc_line_state_t

◆ ra8_usb_cdc_packet_t

◆ ra8_usb_cdc_pipe_t

◆ ra8_usb_cdc_request_t

Function Documentation

◆ ra8_usb_cdc_attach()

◆ ra8_usb_cdc_deinit()

◆ ra8_usb_cdc_get_line_coding()

◆ ra8_usb_cdc_get_line_state()

◆ ra8_usb_cdc_handle_setup()

◆ ra8_usb_cdc_init()

◆ ra8_usb_cdc_recv()

◆ ra8_usb_cdc_send()