SSIE streaming data path: DMAC channel attach/detach + polled ISO bulk send/receive. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_dmac.h"
#include "ra8_err.h"
#include "ra8_hal_internal.h"
#include "ra8_ssie.h"
#include "ra8_ssie_regs.h"

Include dependency graph for ra8_ssie_stream.c:

Functions
static ra8_err_t	internal_validate_dma_cfg (const ra8_ssie_dma_cfg_t dma, bool want_tx, bool *want_rx)
	Validate the DMA-attach descriptor against TX/RX intent.
static ra8_err_t	internal_start_tx_dma (volatile r_ssie_regs_t reg, uint8_t channel, const ra8_ssie_dma_cfg_t dma)
	Kick off the TX DMAC for an SSIE channel.
static ra8_err_t	internal_start_rx_dma (volatile r_ssie_regs_t reg, uint8_t channel, const ra8_ssie_dma_cfg_t dma)
	Kick off the RX DMAC for an SSIE channel.
static void	internal_unwind_tx_dma (uint8_t channel, uint8_t tx_dma_channel)
	Roll back a TX DMAC start when the RX side fails.
static ra8_err_t	internal_attach_dma_dirs (volatile r_ssie_regs_t reg, uint8_t channel, const ra8_ssie_dma_cfg_t dma, bool want_tx, bool want_rx)
	Run the per-direction DMA setup (TX then RX) with rollback.
ra8_err_t	ra8_ssie_attach_dma (uint8_t channel, const ra8_ssie_dma_cfg_t *dma)
	Attach DMAC channels to the SSIE TX and/or RX FIFOs.
ra8_err_t	ra8_ssie_detach_dma (uint8_t channel)
	Tear down DMAC channels attached to the SSIE FIFOs.
ra8_err_t	ra8_ssie_attach_dma_pair (uint8_t channel, uint8_t tx_dma_channel, uint8_t rx_dma_channel)
	Pair an SSIE channel's TX + RX FIFOs to DMAC channels.
ra8_err_t	ra8_ssie_send_iso (uint8_t channel, const uint32_t *buffer, uint16_t samples)
	Block-mode isochronous send.
ra8_err_t	ra8_ssie_recv_iso (uint8_t channel, uint32_t buffer, uint16_t max_samples, uint16_t out_got)
	Block-mode isochronous receive.

Variables
static const char *	s_tag = "SSIE"
	Logger tag for ra8_log_* messages produced by this driver.

Detailed Description

SSIE streaming data path: DMAC channel attach/detach + polled ISO bulk send/receive.

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

Sibling translation unit of ra8_ssie.c carrying the bulk-transfer half of the Serial Sound Interface Enhanced (SSIE / I2S) driver: the DMAC adapter (ra8_ssie_attach_dma / ra8_ssie_detach_dma / ra8_ssie_attach_dma_pair and their private helpers) and the polled isochronous streaming primitives (ra8_ssie_send_iso / ra8_ssie_recv_iso). Split out of ra8_ssie.c purely to satisfy the per-file size cap; behaviour is unchanged.

Every register access carries a HUM Ch 46 citation against r01uh1065ej0130-ra8d2.pdf. The per-channel runtime bookkeeping array (g_ssie_runtime) and the channel-validating register accessor (priv_ra8_ssie_internal_regs) are shared with ra8_ssie.c through ra8_hal_internal.h.

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

Since: 0.1.0

Definition in file ra8_ssie_stream.c.

Function Documentation

◆ internal_attach_dma_dirs()

ra8_err_t internal_attach_dma_dirs	(	volatile r_ssie_regs_t *	reg,
		uint8_t	channel,
		const ra8_ssie_dma_cfg_t *	dma,
		bool	want_tx,
		bool	want_rx )

static

Run the per-direction DMA setup (TX then RX) with rollback.

Encapsulates the body of ra8_ssie_attach_dma once validation has already chosen want_tx / want_rx. On RX failure, the TX side (if started) is unwound through internal_unwind_tx_dma.

Parameters

[in]	reg	See implementation.
[in]	channel	See implementation.
[in]	dma	See implementation.
[in]	want_tx	See implementation.
[in]	want_rx	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 200 of file ra8_ssie_stream.c.

References internal_start_rx_dma(), internal_start_tx_dma(), internal_unwind_tx_dma(), k_ra8_ok, RA8_RETURN_ON_ERROR, s_tag, and ra8_ssie_dma_cfg_t::tx_dma_channel.

Referenced by ra8_ssie_attach_dma().

◆ internal_start_rx_dma()

ra8_err_t internal_start_rx_dma	(	volatile r_ssie_regs_t *	reg,
		uint8_t	channel,
		const ra8_ssie_dma_cfg_t *	dma )

static

Kick off the RX DMAC for an SSIE channel.

See HUM Ch 46.4.1 "Operation in DMAC Transfer" p 3104.

Parameters

[in]	reg	See implementation.
[in]	channel	See implementation.
[in]	dma	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 140 of file ra8_ssie_stream.c.

References g_ssie_runtime, k_ra8_dmac_width_word, k_ra8_ok, ra8_dmac_start(), ra8_ssie_dma_cfg_t::rx_buffer, ra8_ssie_dma_cfg_t::rx_dma_channel, ra8_ssie_dma_cfg_t::rx_samples, and r_ssie_regs_t::SSIFRDR.

Referenced by internal_attach_dma_dirs().

◆ internal_start_tx_dma()

ra8_err_t internal_start_tx_dma	(	volatile r_ssie_regs_t *	reg,
		uint8_t	channel,
		const ra8_ssie_dma_cfg_t *	dma )

static

Kick off the TX DMAC for an SSIE channel.

See HUM Ch 46.4.1 "Operation in DMAC Transfer" p 3104.

Parameters

[in]	reg	See implementation.
[in]	channel	See implementation.
[in]	dma	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 104 of file ra8_ssie_stream.c.

References g_ssie_runtime, k_ra8_dmac_width_word, k_ra8_ok, ra8_dmac_start(), r_ssie_regs_t::SSIFTDR, ra8_ssie_dma_cfg_t::tx_buffer, ra8_ssie_dma_cfg_t::tx_dma_channel, and ra8_ssie_dma_cfg_t::tx_samples.

Referenced by internal_attach_dma_dirs().

◆ internal_unwind_tx_dma()

void internal_unwind_tx_dma	(	uint8_t	channel,
		uint8_t	tx_dma_channel )

static

Roll back a TX DMAC start when the RX side fails.

See implementation.

Parameters

[in]	channel	See implementation.
[in]	tx_dma_channel	See implementation.

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 171 of file ra8_ssie_stream.c.

References g_ssie_runtime, k_ra8_ssie_dma_ch_unused, and ra8_dmac_stop().

Referenced by internal_attach_dma_dirs().

◆ internal_validate_dma_cfg()

ra8_err_t internal_validate_dma_cfg	(	const ra8_ssie_dma_cfg_t *	dma,
		bool *	want_tx,
		bool *	want_rx )

static

Validate the DMA-attach descriptor against TX/RX intent.

Parameters

[in]	dma	Caller's DMA config.
[out]	want_tx	Set to true when caller requests a TX DMA channel.
[out]	want_rx	Set to true when caller requests an RX DMA channel.

Returns: k_ra8_ok if the descriptor is consistent, else k_ra8_err_invalid_arg.

See implementation.

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 69 of file ra8_ssie_stream.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_dma_max_ch, ra8_ssie_dma_cfg_t::rx_buffer, ra8_ssie_dma_cfg_t::rx_dma_channel, ra8_ssie_dma_cfg_t::rx_samples, ra8_ssie_dma_cfg_t::tx_buffer, ra8_ssie_dma_cfg_t::tx_dma_channel, and ra8_ssie_dma_cfg_t::tx_samples.

Referenced by ra8_ssie_attach_dma().

◆ ra8_ssie_attach_dma()

ra8_err_t ra8_ssie_attach_dma	(	uint8_t	channel,
		const ra8_ssie_dma_cfg_t *	dma )

nodiscard

Attach DMAC channels to the SSIE TX and/or RX FIFOs.

Programmes a TX DMAC channel (source = caller buffer, dest = SSIFTDR, no dest increment) and an RX DMAC channel (source = SSIFRDR, dest = caller buffer, no source increment) per HUM Ch 46.4.1 "Operation in DMAC Transfer" p 3104. After this call the SSIE TIE/RIE bits are still required to advance the DMA (the FIFO watermark is the request signal).

Setting a channel ID >= 8 (the DMAC has only 8 channels) skips that direction.

Parameters

[in]	channel	Channel index (0 = SSIE0, 1 = SSIE1).
[in]	dma	Non-NULL DMA configuration.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	DMA channels programmed.
k_ra8_err_null_ptr	dma was NULL.
k_ra8_err_invalid_arg	Channel out of range or DMA samples = 0.

Precondition: Channel previously initialized.; DMA channels not currently in use.

Postcondition: DMAC sources/destinations and counts loaded.; SSIE FIFO watermarks unchanged.

Note: Thread safety: not thread-safe.

See also: ra8_ssie_detach_dma

Since: 0.1.0

Definition at line 224 of file ra8_ssie_stream.c.

References g_ssie_runtime, internal_attach_dma_dirs(), internal_validate_dma_cfg(), k_ra8_err_invalid_arg, k_ra8_ok, priv_ra8_ssie_internal_regs(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, and s_tag.

◆ ra8_ssie_attach_dma_pair()

ra8_err_t ra8_ssie_attach_dma_pair	(	uint8_t	channel,
		uint8_t	tx_dma_channel,
		uint8_t	rx_dma_channel )

nodiscard

Pair an SSIE channel's TX + RX FIFOs to DMAC channels.

Thin variant of ra8_ssie_attach_dma that takes only the DMAC channel ids (no buffers / counts). Useful for callers who programme the DMAC descriptors themselves and only need the SSIE side to record which DMAC channels to free during ra8_ssie_detach_dma. Pass >= 8 to skip a direction.

Parameters

[in]	channel	SSIE channel index 0..1.
[in]	tx_dma_channel	DMAC channel id pumping TX (or >= 8).
[in]	rx_dma_channel	DMAC channel id pumping RX (or >= 8).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel binding recorded.
k_ra8_err_invalid_arg	Channel out of range OR both DMA ids >= 8.

Precondition: Channel previously initialized.; At least one of tx_dma_channel / rx_dma_channel < 8.

Postcondition: Internal DMA bookkeeping records the TX / RX DMAC ids.; No DMAC start was issued (compare ra8_ssie_attach_dma).

Note: Thread safety: not thread-safe.

See also: ra8_ssie_attach_dma; ra8_ssie_detach_dma

Since: 0.1.0

Definition at line 264 of file ra8_ssie_stream.c.

References ra8_ssie_runtime_t::dma_attached, g_ssie_runtime, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_channel_count, k_ra8_ssie_dma_ch_unused, k_ra8_ssie_dma_max_ch, ra8_ssie_runtime_t::rx_dma_channel, and ra8_ssie_runtime_t::tx_dma_channel.

◆ ra8_ssie_detach_dma()

ra8_err_t ra8_ssie_detach_dma ( uint8_t channel )

nodiscard

Tear down DMAC channels attached to the SSIE FIFOs.

Parameters

[in] channel Channel index.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	All attached DMA channels stopped.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: ra8_ssie_attach_dma previously succeeded for channel.; TIE/RIE bits in SSIFCR cleared by caller before call.

Postcondition: Both DMAC channels stopped.; Internal DMA bookkeeping cleared.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 246 of file ra8_ssie_stream.c.

References ra8_ssie_runtime_t::dma_attached, g_ssie_runtime, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_channel_count, k_ra8_ssie_dma_ch_unused, k_ra8_ssie_dma_max_ch, ra8_dmac_stop(), ra8_ssie_runtime_t::rx_dma_channel, and ra8_ssie_runtime_t::tx_dma_channel.

Referenced by ra8_ssie_deinit().

◆ ra8_ssie_recv_iso()

ra8_err_t ra8_ssie_recv_iso	(	uint8_t	channel,
		uint32_t *	buffer,
		uint16_t	max_samples,
		uint16_t *	out_got )

nodiscard

Block-mode isochronous receive.

Drains up to max_samples.

Loops until either the destination buffer is full or the SSIE RX FIFO drains. Returns the actual sample count via out_got.

Parameters

[in]	channel	Channel index 0..1.
[out]	buffer	Destination buffer.
[in]	max_samples	Capacity of buffer in 32-bit samples.
[out]	out_got	Receives the number of samples consumed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Up to max_samples words consumed.
k_ra8_err_null_ptr	buffer or out_got was NULL.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized + started in RX mode.; buffer and out_got are non-NULL.

Postcondition: *out_got <= max_samples.; Receive FIFO drained to either empty or max_samples cap.

Note: Thread safety: not thread-safe.

See also: ra8_ssie_send_iso

Since: 0.1.0

Definition at line 313 of file ra8_ssie_stream.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_rdc, k_ra8_ssie_mask_tde_clear, k_ra8_ssie_shift_rdc, priv_ra8_ssie_internal_regs(), RA8_CHECK_NULL_PTR, s_tag, r_ssie_regs_t::SSIFRDR, and r_ssie_regs_t::SSIFSR.

◆ ra8_ssie_send_iso()

ra8_err_t ra8_ssie_send_iso	(	uint8_t	channel,
		const uint32_t *	buffer,
		uint16_t	samples )

nodiscard

Block-mode isochronous send.

Drains the buffer fully.

Loops until every requested sample has been pushed into SSIFTDR. Internally relies on the FIFO depth read-back to throttle, so the routine is bounded by samples * k_ra8_ssie_fifo_depth SSIFSR reads worst-case (HUM Ch 46.2.4 p 3083). The non-DMA path used by the iso pacing layer.

Parameters

[in]	channel	Channel index 0..1.
[in]	buffer	Source samples.
[in]	samples	Number of 32-bit samples to send.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	All samples queued.
k_ra8_err_null_ptr	buffer was NULL.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized + started in TX mode.; buffer is non-NULL and points to samples words.

Postcondition: All samples words have been pushed into SSIFTDR.; Remaining FIFO occupancy is implementation-defined.

Note: Thread safety: not thread-safe.

See also: ra8_ssie_recv_iso

Since: 0.1.0

Definition at line 285 of file ra8_ssie_stream.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_fifo_depth, k_ra8_ssie_mask_rdf_clear, k_ra8_ssie_mask_tdc, k_ra8_ssie_shift_tdc, priv_ra8_ssie_internal_regs(), RA8_CHECK_NULL_PTR, s_tag, r_ssie_regs_t::SSIFSR, and r_ssie_regs_t::SSIFTDR.

Variable Documentation

◆ s_tag

const char* s_tag = "SSIE"

static

Logger tag for ra8_log_* messages produced by this driver.

Note: Module-private; never modified at runtime. Independent copy of the identical literal in ra8_ssie.c so the split needs no promoted external symbol for a read-only constant.

Definition at line 46 of file ra8_ssie_stream.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_attach_dma_dirs()

◆ internal_start_rx_dma()

◆ internal_start_tx_dma()

◆ internal_unwind_tx_dma()

◆ internal_validate_dma_cfg()

◆ ra8_ssie_attach_dma()

◆ ra8_ssie_attach_dma_pair()

◆ ra8_ssie_detach_dma()

◆ ra8_ssie_recv_iso()

◆ ra8_ssie_send_iso()

Variable Documentation

◆ s_tag