Native USB host-side Audio class layer (USB Audio 1.0). More...

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

Include dependency graph for ra8_usb_haud.h:

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

Data Structures
struct	ra8_usb_haud_device_t
	Snapshot of the attached audio device, passed to the attach callback. More...

Typedefs
typedef void(*	ra8_usb_haud_attach_fn_t) (void ctx, const ra8_usb_haud_device_t device)
	Attach-callback signature.

Enumerations
enum	ra8_usb_haud_pipe_t : uint8_t { k_ra8_haud_pipe_iso_in = 1U , k_ra8_haud_pipe_iso_out = 2U }
	PIPE numbers used by the host-Audio driver for the attached peripheral's isochronous endpoints. More...
enum	ra8_usb_haud_class_t : uint8_t { k_ra8_haud_class_audio = 0x01U , k_ra8_haud_subclass_undefined = 0x00U , k_ra8_haud_subclass_audiocontrol = 0x01U , k_ra8_haud_subclass_audiostreaming = 0x02U , k_ra8_haud_subclass_midistreaming = 0x03U }
	Class / subclass triplet that identifies the Audio function within an attached USB device's descriptor walk. More...
enum	ra8_usb_haud_cs_desc_t : uint8_t { k_ra8_haud_cs_desc_undefined = 0x20U , k_ra8_haud_cs_desc_device = 0x21U , k_ra8_haud_cs_desc_config = 0x22U , k_ra8_haud_cs_desc_string = 0x23U , k_ra8_haud_cs_desc_interface = 0x24U , k_ra8_haud_cs_desc_endpoint = 0x25U }
	Class-specific descriptor type values (USB Audio 1.0 sec A.4 "Audio Class-Specific Descriptor Types"). More...
enum	ra8_usb_haud_ac_subtype_t : uint8_t { k_ra8_haud_ac_header = 0x01U , k_ra8_haud_ac_input_terminal = 0x02U , k_ra8_haud_ac_output_terminal = 0x03U , k_ra8_haud_ac_mixer_unit = 0x04U , k_ra8_haud_ac_selector_unit = 0x05U , k_ra8_haud_ac_feature_unit = 0x06U , k_ra8_haud_ac_processing_unit = 0x07U , k_ra8_haud_ac_extension_unit = 0x08U }
	Class-specific AC interface descriptor subtypes (USB Audio 1.0 sec A.5 "Audio Class-Specific AC Interface Descriptor Subtypes"). More...
enum	ra8_usb_haud_as_subtype_t : uint8_t { k_ra8_haud_as_general = 0x01U , k_ra8_haud_as_format_type = 0x02U , k_ra8_haud_as_format_specific = 0x03U }
	Class-specific AS interface descriptor subtypes (USB Audio 1.0 sec A.6 "Audio Class-Specific AS Interface Descriptor Subtypes"). More...
enum	ra8_usb_haud_format_type_t : uint8_t { k_ra8_haud_format_type_undefined = 0x00U , k_ra8_haud_format_type_i = 0x01U , k_ra8_haud_format_type_ii = 0x02U , k_ra8_haud_format_type_iii = 0x03U }
	Audio-Streaming format-type codes (USB Audio Data Formats 1.0 sec 2 "Format Type Codes"). More...
enum	ra8_usb_haud_request_t : uint8_t { k_ra8_haud_req_undefined = 0x00U , k_ra8_haud_req_set_cur = 0x01U , k_ra8_haud_req_get_cur = 0x81U , k_ra8_haud_req_set_min = 0x02U , k_ra8_haud_req_get_min = 0x82U , k_ra8_haud_req_set_max = 0x03U , k_ra8_haud_req_get_max = 0x83U , k_ra8_haud_req_set_res = 0x04U , k_ra8_haud_req_get_res = 0x84U }
	Audio class-specific request codes the host issues to the attached device (USB Audio 1.0 sec A.8 "Audio Class-Specific Request Codes"). More...
enum	ra8_usb_haud_fu_control_t : uint8_t { k_ra8_haud_fu_control_undefined = 0x00U , k_ra8_haud_fu_control_mute = 0x01U , k_ra8_haud_fu_control_volume = 0x02U , k_ra8_haud_fu_control_bass = 0x03U , k_ra8_haud_fu_control_mid = 0x04U , k_ra8_haud_fu_control_treble = 0x05U , k_ra8_haud_fu_control_graphic_eq = 0x06U , k_ra8_haud_fu_control_auto_gain = 0x07U , k_ra8_haud_fu_control_delay = 0x08U , k_ra8_haud_fu_control_bass_boost = 0x09U , k_ra8_haud_fu_control_loudness = 0x0AU }
	Feature Unit control selectors (USB Audio 1.0 sec A.10.2 "Feature Unit Control Selectors"). More...
enum	ra8_usb_haud_ep_control_t : uint8_t { k_ra8_haud_ep_control_undefined = 0x00U , k_ra8_haud_ep_control_sampling_freq = 0x01U , k_ra8_haud_ep_control_pitch = 0x02U }
	Endpoint Control Selectors (USB Audio 1.0 sec A.10.5). More...
enum	ra8_usb_haud_volume_t : int32_t { k_ra8_haud_volume_silence = (int32_t)0x8000 , k_ra8_haud_volume_min_db = (int32_t)-32768 , k_ra8_haud_volume_max_db = (int32_t)32767 }
	Volume-control wire encoding helpers. More...
enum	ra8_usb_haud_packet_t : uint16_t { k_ra8_haud_iso_max_packet_default = 192U , k_ra8_haud_iso_max_packet_fs = 1023U , k_ra8_haud_iso_max_packet_hs = 1024U }
	Packet sizing for the attached device's isochronous endpoints. More...
enum	ra8_usb_haud_default_t : uint32_t { k_ra8_haud_default_sample_rate_hz = 48000U , k_ra8_haud_default_channels = 2U , k_ra8_haud_default_bits = 16U }
	Default audio format applied by the descriptor-walk stub when the attached device follows the canonical USB-headphones layout. More...
enum	ra8_usb_haud_format_limit_t : uint32_t { k_ra8_haud_min_channels = 1U , k_ra8_haud_max_channels = 8U , k_ra8_haud_min_bits = 8U , k_ra8_haud_max_bits = 32U , k_ra8_haud_min_sample_rate_hz = 8000U , k_ra8_haud_max_sample_rate_hz = 192000U }
	Range checks for ra8_usb_haud_set_format. More...

Functions
ra8_err_t	ra8_usb_haud_init (ra8_usb_speed_t speed)
	Bring up the host-Audio driver on a chosen USB controller.
ra8_err_t	ra8_usb_haud_close (void)
	Tear down the host-Audio driver and release the controller.
ra8_err_t	ra8_usb_haud_attach_callback (ra8_usb_haud_attach_fn_t on_attach, void *ctx)
	Register (or detach) the attach callback.
ra8_err_t	ra8_usb_haud_set_format (uint8_t channel_count, uint8_t bits_per_sample, uint32_t sample_rate_hz)
	Issue SET_CUR on the format-type-I descriptor (USB Audio 1.0 sec 5.2.3 "Class-Specific AS Interface Control Requests").
ra8_err_t	ra8_usb_haud_set_volume (uint8_t channel, int16_t volume)
	Issue SET_CUR on the Feature Unit Volume control (USB Audio 1.0 sec 5.2.2.4.3 "Volume Control").
ra8_err_t	ra8_usb_haud_set_mute (uint8_t channel, bool mute)
	Issue SET_CUR on the Feature Unit Mute control (USB Audio 1.0 sec 5.2.2.4.3.1 "Mute Control").
ra8_err_t	ra8_usb_haud_send_samples (const uint8_t *buf, uint16_t len_bytes)
	Push isochronous-OUT samples to a speaker / headphones.
ra8_err_t	ra8_usb_haud_recv_samples (uint8_t buf, uint16_t max_len_bytes, uint16_t got_len_bytes)
	Drain isochronous-IN samples from a microphone.
ra8_err_t	ra8_usb_haud_step (void)
	Drive the enumeration step machine forward by one step.

Detailed Description

Native USB host-side Audio class layer (USB Audio 1.0).

Glues the host-mode bring-up paths in ra8_usb to a USB Audio class peripheral - typically a USB speaker, headphones, or microphone - attached on the EK-RA8D2's USB-host port. Mirrors FSP's r_usb_haud host-Audio class flow but compiled as part of this tree with no FSP / CherryUSB / TinyUSB binaries pulled in.

Lifecycle (mirrors ra8_usb_hcdc.h / ra8_usb_hhid.h shape):

ra8_usb_haud_init(speed) flips the controller to host mode, primes the internal step machine to idle, and leaves the bus in the "wait for attach" state (UACT cleared).
The driver runs the chapter-9 enumeration step machine over the DCP, walks the configuration descriptor for the Audio-Control interface (class=0x01 / subclass=0x01), then for at least one Audio-Streaming interface (class=0x01 / subclass=0x02), and pulls out the isochronous IN / OUT endpoints. Optionally walks the class-specific AC interface descriptors (Input Terminal, Output Terminal, Feature Unit, Selector Unit) to capture the Feature Unit ID needed for volume / mute control.
When enumeration completes the registered attach callback fires once with the discovered isochronous-IN / OUT endpoints, max packet sizes, sampling-rate range, channel count, and bits-per- sample.
Audio class control transfers (_set_format, _set_volume, _set_mute) are layered on top of the DCP per USB Audio 1.0 sec 5.2 "Class-Specific Requests".
ra8_usb_haud_send_samples / ra8_usb_haud_recv_samples push and drain isochronous packets to / from a connected speaker / microphone.
ra8_usb_haud_close() drops bus power and releases the device.

The starter only tracks a single attached audio device; hubs and multi-streaming-interface composite audio devices are deferred follow-ups.

Reference: USB Device Class Definition for Audio Devices revision 1.0 (USB-IF, 1998-03-18) and USB Audio Data Formats 1.0.

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

Definition in file ra8_usb_haud.h.

Typedef Documentation

◆ ra8_usb_haud_attach_fn_t

typedef void(* ra8_usb_haud_attach_fn_t) (void *ctx, const ra8_usb_haud_device_t *device)

Attach-callback signature.

Parameters

[in]	ctx	Caller-supplied context registered with ra8_usb_haud_attach_callback.
[in]	device	Snapshot of the attached audio 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 290 of file ra8_usb_haud.h.

Enumeration Type Documentation

◆ ra8_usb_haud_ac_subtype_t

enum ra8_usb_haud_ac_subtype_t : uint8_t

Class-specific AC interface descriptor subtypes (USB Audio 1.0 sec A.5 "Audio Class-Specific AC Interface Descriptor Subtypes").

Enumerator
k_ra8_haud_ac_header	HEADER.
k_ra8_haud_ac_input_terminal	INPUT_TERMINAL.
k_ra8_haud_ac_output_terminal	OUTPUT_TERMINAL.
k_ra8_haud_ac_mixer_unit	MIXER_UNIT.
k_ra8_haud_ac_selector_unit	SELECTOR_UNIT.
k_ra8_haud_ac_feature_unit	FEATURE_UNIT.
k_ra8_haud_ac_processing_unit	PROCESSING_UNIT.
k_ra8_haud_ac_extension_unit	EXTENSION_UNIT.

Definition at line 115 of file ra8_usb_haud.h.

◆ ra8_usb_haud_as_subtype_t

enum ra8_usb_haud_as_subtype_t : uint8_t

Class-specific AS interface descriptor subtypes (USB Audio 1.0 sec A.6 "Audio Class-Specific AS Interface Descriptor Subtypes").

Enumerator
k_ra8_haud_as_general	AS_GENERAL.
k_ra8_haud_as_format_type	FORMAT_TYPE.
k_ra8_haud_as_format_specific	FORMAT_SPECIFIC.

Definition at line 132 of file ra8_usb_haud.h.

◆ ra8_usb_haud_class_t

enum ra8_usb_haud_class_t : uint8_t

Class / subclass triplet that identifies the Audio function within an attached USB device's descriptor walk.

Numbered from USB Audio 1.0 sec A "Audio Device Class Codes".

Enumerator
k_ra8_haud_class_audio	AUDIO interface class.
k_ra8_haud_subclass_undefined	SUBCLASS_UNDEFINED.
k_ra8_haud_subclass_audiocontrol	AUDIOCONTROL.
k_ra8_haud_subclass_audiostreaming	AUDIOSTREAMING.
k_ra8_haud_subclass_midistreaming	MIDISTREAMING.

Definition at line 87 of file ra8_usb_haud.h.

◆ ra8_usb_haud_cs_desc_t

enum ra8_usb_haud_cs_desc_t : uint8_t

Class-specific descriptor type values (USB Audio 1.0 sec A.4 "Audio Class-Specific Descriptor Types").

Enumerator
k_ra8_haud_cs_desc_undefined	CS_UNDEFINED.
k_ra8_haud_cs_desc_device	CS_DEVICE.
k_ra8_haud_cs_desc_config	CS_CONFIGURATION.
k_ra8_haud_cs_desc_string	CS_STRING.
k_ra8_haud_cs_desc_interface	CS_INTERFACE.
k_ra8_haud_cs_desc_endpoint	CS_ENDPOINT.

Definition at line 100 of file ra8_usb_haud.h.

◆ ra8_usb_haud_default_t

enum ra8_usb_haud_default_t : uint32_t

Default audio format applied by the descriptor-walk stub when the attached device follows the canonical USB-headphones layout.

Enumerator
k_ra8_haud_default_sample_rate_hz	48 kHz default.
k_ra8_haud_default_channels	Stereo.
k_ra8_haud_default_bits	16-bit PCM.

Definition at line 230 of file ra8_usb_haud.h.

◆ ra8_usb_haud_ep_control_t

enum ra8_usb_haud_ep_control_t : uint8_t

Endpoint Control Selectors (USB Audio 1.0 sec A.10.5).

Encoded in wValue's high byte for SET_CUR on an isochronous endpoint - this is how the sampling-frequency is changed.

Enumerator
k_ra8_haud_ep_control_undefined	EP_CONTROL_UNDEFINED.
k_ra8_haud_ep_control_sampling_freq	SAMPLING_FREQ_CONTROL.
k_ra8_haud_ep_control_pitch	PITCH_CONTROL.

Definition at line 194 of file ra8_usb_haud.h.

◆ ra8_usb_haud_format_limit_t

enum ra8_usb_haud_format_limit_t : uint32_t

Range checks for ra8_usb_haud_set_format.

Enumerator
k_ra8_haud_min_channels	Mono.
k_ra8_haud_max_channels	7.1 surround ceiling.
k_ra8_haud_min_bits	8-bit ceiling.
k_ra8_haud_max_bits	32-bit ceiling.
k_ra8_haud_min_sample_rate_hz	8 kHz min.
k_ra8_haud_max_sample_rate_hz	192 kHz max.

Definition at line 240 of file ra8_usb_haud.h.

◆ ra8_usb_haud_format_type_t

enum ra8_usb_haud_format_type_t : uint8_t

Audio-Streaming format-type codes (USB Audio Data Formats 1.0 sec 2 "Format Type Codes").

Enumerator
k_ra8_haud_format_type_undefined	FORMAT_TYPE_UNDEFINED.
k_ra8_haud_format_type_i	FORMAT_TYPE_I (PCM).
k_ra8_haud_format_type_ii	FORMAT_TYPE_II.
k_ra8_haud_format_type_iii	FORMAT_TYPE_III.

Definition at line 143 of file ra8_usb_haud.h.

◆ ra8_usb_haud_fu_control_t

enum ra8_usb_haud_fu_control_t : uint8_t

Feature Unit control selectors (USB Audio 1.0 sec A.10.2 "Feature Unit Control Selectors").

Encoded in wValue's high byte of the SET_CUR / GET_CUR request.

Enumerator
k_ra8_haud_fu_control_undefined	FU_CONTROL_UNDEFINED.
k_ra8_haud_fu_control_mute	MUTE_CONTROL.
k_ra8_haud_fu_control_volume	VOLUME_CONTROL.
k_ra8_haud_fu_control_bass	BASS_CONTROL.
k_ra8_haud_fu_control_mid	MID_CONTROL.
k_ra8_haud_fu_control_treble	TREBLE_CONTROL.
k_ra8_haud_fu_control_graphic_eq	GRAPHIC_EQ_CONTROL.
k_ra8_haud_fu_control_auto_gain	AUTOMATIC_GAIN_CONTROL.
k_ra8_haud_fu_control_delay	DELAY_CONTROL.
k_ra8_haud_fu_control_bass_boost	BASS_BOOST_CONTROL.
k_ra8_haud_fu_control_loudness	LOUDNESS_CONTROL.

Definition at line 174 of file ra8_usb_haud.h.

◆ ra8_usb_haud_packet_t

enum ra8_usb_haud_packet_t : uint16_t

Packet sizing for the attached device's isochronous endpoints.

Enumerator
k_ra8_haud_iso_max_packet_default	Common 48 kHz / 16-bit / stereo.
k_ra8_haud_iso_max_packet_fs	FS isochronous ceiling.
k_ra8_haud_iso_max_packet_hs	HS isochronous ceiling.

Definition at line 218 of file ra8_usb_haud.h.

◆ ra8_usb_haud_pipe_t

enum ra8_usb_haud_pipe_t : uint8_t

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

The RA8D2 / FSP PIPE assignment rules constrain isochronous pipes to PIPE1..PIPE2. The host-Audio class uses one isochronous-IN pipe (microphone) and one isochronous-OUT pipe (speaker). See USB Audio 1.0 sec 4.5 "Isochronous Endpoint Descriptor".

Enumerator
k_ra8_haud_pipe_iso_in	PIPE1 -> attached EP iso IN.
k_ra8_haud_pipe_iso_out	PIPE2 -> attached EP iso OUT.

Definition at line 75 of file ra8_usb_haud.h.

◆ ra8_usb_haud_request_t

enum ra8_usb_haud_request_t : uint8_t

Audio class-specific request codes the host issues to the attached device (USB Audio 1.0 sec A.8 "Audio Class-Specific Request Codes").

Enumerator
k_ra8_haud_req_undefined	REQUEST_CODE_UNDEFINED.
k_ra8_haud_req_set_cur	SET_CUR.
k_ra8_haud_req_get_cur	GET_CUR.
k_ra8_haud_req_set_min	SET_MIN.
k_ra8_haud_req_get_min	GET_MIN.
k_ra8_haud_req_set_max	SET_MAX.
k_ra8_haud_req_get_max	GET_MAX.
k_ra8_haud_req_set_res	SET_RES.
k_ra8_haud_req_get_res	GET_RES.

Definition at line 156 of file ra8_usb_haud.h.

◆ ra8_usb_haud_volume_t

enum ra8_usb_haud_volume_t : int32_t

Volume-control wire encoding helpers.

Per USB Audio 1.0 sec 5.2.2.4.3.2 "Volume Control": volume is a signed 16-bit value in 1/256 dB steps. The minimum encoded value (0x8000) is the "silence" sentinel.

Enumerator
k_ra8_haud_volume_silence	Silence sentinel.
k_ra8_haud_volume_min_db	-128.0 dB ceiling.
k_ra8_haud_volume_max_db	+127.998 dB ceiling.

Definition at line 208 of file ra8_usb_haud.h.

Function Documentation

◆ ra8_usb_haud_attach_callback()

ra8_err_t ra8_usb_haud_attach_callback	(	ra8_usb_haud_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 Audio-Control interface (class=0x01 / subclass=0x01) and at least one Audio-Streaming interface (class=0x01 / subclass=0x02), and the matching isochronous IN / OUT endpoints and Feature Unit 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_haud_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 719 of file ra8_usb_haud.c.

References k_ra8_err_invalid_state, k_ra8_ok, and s_state.

◆ ra8_usb_haud_close()

ra8_err_t ra8_usb_haud_close ( void )

nodiscard

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 698 of file ra8_usb_haud.c.

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

◆ ra8_usb_haud_init()

ra8_err_t ra8_usb_haud_init ( ra8_usb_speed_t speed )

nodiscard

Bring up the host-Audio 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. Delegates to ra8_usb_host_init.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Host-Audio 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_haud_attach_callback; ra8_usb_haud_close

Since: 0.1.0

Definition at line 675 of file ra8_usb_haud.c.

References k_ra8_err_hw_init_failed, k_ra8_err_invalid_arg, k_ra8_haud_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_haud_recv_samples()

ra8_err_t ra8_usb_haud_recv_samples	(	uint8_t *	buf,
		uint16_t	max_len_bytes,
		uint16_t *	got_len_bytes )

nodiscard

Drain isochronous-IN samples from a microphone.

Polling / non-blocking. Pulls bytes from the configured PIPE1 (isochronous IN) into buf. Returns k_ra8_err_no_data if the pipe has no bytes ready in this micro-frame.

Parameters

[out]	buf	Destination buffer.
[in]	max_len_bytes	Capacity of buf, > 0.
[out]	got_len_bytes	Receives the number of bytes actually placed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes drained; *got_len_bytes reflects the count.
k_ra8_err_no_data	Pipe was empty.
k_ra8_err_null_ptr	buf or got_len_bytes was NULL.
k_ra8_err_invalid_state	Driver not initialized, no device attached, or device has no iso-IN endpoint.
k_ra8_err_invalid_arg	max_len_bytes == 0.

Precondition: ra8_usb_haud_init succeeded.; Attach callback already fired with an iso-IN endpoint.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 864 of file ra8_usb_haud.c.

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

◆ ra8_usb_haud_send_samples()

ra8_err_t ra8_usb_haud_send_samples	(	const uint8_t *	buf,
		uint16_t	len_bytes )

nodiscard

Push isochronous-OUT samples to a speaker / headphones.

Streams buf[0..len_bytes-1] onto the iso-OUT pipe configured for the attached Audio-Streaming interface. PCM byte-order matches the Audio-Streaming format (little-endian per USB Audio Data Formats 1.0 sec 2.2). Non-blocking; bytes that don't fit in the current micro-frame return k_ra8_err_busy for the caller to retry.

Parameters

[in]	buf	Sample byte buffer.
[in]	len_bytes	Number of bytes in buf.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes queued for the next iso-OUT slot.
k_ra8_err_null_ptr	buf == NULL and len_bytes != 0.
k_ra8_err_invalid_state	Driver not initialized, no device attached, or device has no iso-OUT endpoint.
k_ra8_err_invalid_arg	len_bytes == 0.
k_ra8_err_busy	iso-OUT pipe busy.

Precondition: ra8_usb_haud_init succeeded.; Attach callback already fired with an iso-OUT endpoint.

Postcondition: On success bytes queued onto PIPE2.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 843 of file ra8_usb_haud.c.

References internal_class_preflight(), k_ra8_err_invalid_arg, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_haud_pipe_iso_out, k_ra8_ok, ra8_usb_queue_in(), and s_state.

◆ ra8_usb_haud_set_format()

ra8_err_t ra8_usb_haud_set_format	(	uint8_t	channel_count,
		uint8_t	bits_per_sample,
		uint32_t	sample_rate_hz )

nodiscard

Issue SET_CUR on the format-type-I descriptor (USB Audio 1.0 sec 5.2.3 "Class-Specific AS Interface Control Requests").

Builds an 8-byte SETUP packet with bmRequestType = 0x22 (Class | Endpoint | Host-to-Device), bRequest = 0x01 (SET_CUR), and wValue = (SAMPLING_FREQ_CONTROL << 8). The data stage payload is a 3-byte little-endian sample rate (USB Audio 1.0 sec 5.2.3.2.3.1). Channel count and bits-per-sample are validated and recorded into the cached device snapshot, but the wire transfer for those is already implicit in the chosen Audio-Streaming interface alt setting; this entry point just refreshes the iso-EP sampling-rate.

Parameters

[in]	channel_count	Channels (1..8).
[in]	bits_per_sample	8..32.
[in]	sample_rate_hz	8000..192000.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SETUP queued.
k_ra8_err_invalid_state	Driver not initialized, or no device attached.
k_ra8_err_invalid_arg	One of channel_count / bits_per_sample / sample_rate_hz is out of range.
k_ra8_err_busy	Controller busy with a prior SETUP.

Precondition: ra8_usb_haud_init succeeded.; Attach callback already fired.

Postcondition: On success the SETUP mirror registers hold the SET_CUR request envelope; the cached format snapshot is updated.

Note: Not thread-safe.

Since: 0.1.0

Definition at line 743 of file ra8_usb_haud.c.

References internal_class_preflight(), internal_format_ok(), k_ra8_err_invalid_arg, k_ra8_haud_bm_class_ep_out, k_ra8_haud_ep_control_sampling_freq, k_ra8_haud_req_set_cur, k_ra8_haud_sample_rate_payload, k_ra8_haud_shift_byte1, k_ra8_ok, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_haud_set_mute()

ra8_err_t ra8_usb_haud_set_mute	(	uint8_t	channel,
		bool	mute )

nodiscard

Issue SET_CUR on the Feature Unit Mute control (USB Audio 1.0 sec 5.2.2.4.3.1 "Mute Control").

Builds an 8-byte SETUP packet with bmRequestType = 0x21 (Class | Interface | Host-to-Device), bRequest = 0x01 (SET_CUR), and wValue = (MUTE_CONTROL << 8) | channel. wIndex packs the Feature Unit ID in the high byte and the AudioControl interface in the low byte. Mute is a one-byte boolean (0 = unmute, 1 = mute).

Parameters

[in]	channel	Logical channel (0 = main, 1..N per channel).
[in]	mute	true = mute, false = unmute.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SETUP 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_haud_init succeeded.; Attach callback already fired.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 815 of file ra8_usb_haud.c.

References internal_class_preflight(), k_ra8_haud_bm_class_iface_out, k_ra8_haud_fu_control_mute, k_ra8_haud_mute_payload, k_ra8_haud_req_set_cur, k_ra8_haud_shift_byte1, k_ra8_ok, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_haud_set_volume()

ra8_err_t ra8_usb_haud_set_volume	(	uint8_t	channel,
		int16_t	volume )

nodiscard

Issue SET_CUR on the Feature Unit Volume control (USB Audio 1.0 sec 5.2.2.4.3 "Volume Control").

Builds an 8-byte SETUP packet with bmRequestType = 0x21 (Class | Interface | Host-to-Device), bRequest = 0x01 (SET_CUR), and wValue = (VOLUME_CONTROL << 8) | channel. wIndex packs the Feature Unit ID in the high byte and the AudioControl interface in the low byte. Volume is a signed 16-bit value in 1/256 dB steps; 0x8000 is the silence sentinel.

Parameters

[in]	channel	Logical channel (0 = main, 1..N per channel).
[in]	volume	Signed dB in 1/256 step.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SETUP 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_haud_init succeeded.; Attach callback already fired.

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

Note: Not thread-safe.

Since: 0.1.0

Definition at line 780 of file ra8_usb_haud.c.

References internal_class_preflight(), k_ra8_haud_bm_class_iface_out, k_ra8_haud_fu_control_volume, k_ra8_haud_req_set_cur, k_ra8_haud_shift_byte1, k_ra8_haud_volume_payload, k_ra8_ok, ra8_usb_host_setup_request(), and s_state.

◆ ra8_usb_haud_step()

ra8_err_t ra8_usb_haud_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_haud_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 894 of file ra8_usb_haud.c.

References internal_step_advance(), k_ra8_err_invalid_state, and s_state.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ ra8_usb_haud_attach_fn_t

Enumeration Type Documentation

◆ ra8_usb_haud_ac_subtype_t

◆ ra8_usb_haud_as_subtype_t

◆ ra8_usb_haud_class_t

◆ ra8_usb_haud_cs_desc_t

◆ ra8_usb_haud_default_t

◆ ra8_usb_haud_ep_control_t

◆ ra8_usb_haud_format_limit_t

◆ ra8_usb_haud_format_type_t

◆ ra8_usb_haud_fu_control_t

◆ ra8_usb_haud_packet_t

◆ ra8_usb_haud_pipe_t

◆ ra8_usb_haud_request_t

◆ ra8_usb_haud_volume_t

Function Documentation

◆ ra8_usb_haud_attach_callback()

◆ ra8_usb_haud_close()

◆ ra8_usb_haud_init()

◆ ra8_usb_haud_recv_samples()

◆ ra8_usb_haud_send_samples()

◆ ra8_usb_haud_set_format()

◆ ra8_usb_haud_set_mute()

◆ ra8_usb_haud_set_volume()

◆ ra8_usb_haud_step()