Serial Sound Interface Enhanced (SSIE / I2S) driver implementation. More...

#include "ra8_ssie.h"
#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_hw_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
#include "ra8_mstp_regs.h"
#include "ra8_ssie_regs.h"

Include dependency graph for ra8_ssie.c:

Functions
volatile r_ssie_regs_t *	priv_ra8_ssie_internal_regs (uint8_t channel)
	Implementation of priv_ra8_ssie_internal_regs() – bounds-check + accessor.
static bool	internal_format_decode (ra8_ssie_format_t format, uint8_t out_omod, uint8_t out_frm, uint8_t out_pdta, uint8_t out_sdta)
	Translate a public format enum to OMOD + FRM register fields.
static uint8_t	internal_decode_event (uint32_t ssisr, uint32_t ssifsr)
	Decode SSISR/SSIFSR into a ra8_ssie_event_t bitmap.
static uint32_t	internal_build_ssicr (const ra8_ssie_cfg_t *cfg, uint8_t frm, uint8_t pdta, uint8_t sdta)
	Build the SSICR value from a config descriptor.
static ra8_err_t	internal_wait_ssirst_clear (volatile r_ssie_regs_t *reg)
	Bounded poll on SSIFCR until SSIRST clears.
static ra8_err_t	internal_wait_fifo_reset_clear (volatile r_ssie_regs_t *reg)
	Bounded poll on SSIFCR until both FIFO reset bits clear.
static uint32_t	internal_build_ssiofr (const ra8_ssie_cfg_t *cfg, uint8_t omod)
	Pack SSIOFR (audio format register) value from cfg + decoded OMOD.
static uint32_t	internal_build_ssifcr (const ra8_ssie_cfg_t *cfg)
	Pack SSIFCR (FIFO control register) value from cfg.
static uint32_t	internal_build_ssiscr (uint8_t tx_threshold, uint8_t rx_threshold)
	Pack SSISCR (status control register) value from TX/RX thresholds.
static ra8_err_t	internal_pulse_fifo_reset (volatile r_ssie_regs_t *reg, uint32_t ssifcr_base)
	Pulse RFRST/TFRST high then low and wait for both bits to clear.
static void	internal_apply_dir_irq_bits (uint32_t desired_ren_ten, uint32_t ssicr, uint32_t ssifcr)
	Apply per-direction IRQ-enable bits to in-progress SSICR/SSIFCR.
static ra8_err_t	internal_validate_init_cfg (const ra8_ssie_cfg_t cfg, uint8_t out_omod, uint8_t out_frm, uint8_t out_pdta, uint8_t *out_sdta)
	Format-decode wrapper that validates ranges before delegation.
static ra8_err_t	internal_pulse_ssi_reset (volatile r_ssie_regs_t *reg)
	Drive the soft-reset sequence required before SSICR writes.
static ra8_err_t	internal_ssie_power_up (uint8_t channel, volatile r_ssie_regs_t *reg)
	Power up the SSIE block: enable MSTP then drive SSIRST low.
static void	internal_apply_init_regs (volatile r_ssie_regs_t reg, const ra8_ssie_cfg_t cfg, uint8_t frm, uint8_t pdta, uint8_t sdta, uint8_t omod)
	Stamp SSICR/SSIOFR/SSISCR/SSIFCR for a freshly reset SSIE block.
ra8_err_t	ra8_ssie_init (uint8_t channel, const ra8_ssie_cfg_t *cfg)
	Initialise an SSIE channel for I2S / TDM / monaural transfer.
ra8_err_t	ra8_ssie_deinit (uint8_t channel)
	Tear down an SSIE channel and gate its clock.
ra8_err_t	ra8_ssie_start (uint8_t channel, ra8_ssie_dir_t dir)
	Enable transmission, reception, or full duplex.
ra8_err_t	ra8_ssie_stop (uint8_t channel)
	Disable transmission and reception.
ra8_err_t	ra8_ssie_start_recovery (uint8_t channel)
	Force the channel back into a known idle state.
ra8_err_t	ra8_ssie_mute (uint8_t channel, bool enable)
	Enable or disable mute on the next frame boundary.
ra8_err_t	ra8_ssie_set_thresholds (uint8_t channel, uint8_t tx_threshold, uint8_t rx_threshold)
	Update the FIFO trigger watermarks at runtime.
ra8_err_t	ra8_ssie_write_sample (uint8_t channel, uint32_t sample)
	Push one 32-bit sample into the transmit FIFO.
ra8_err_t	ra8_ssie_read_sample (uint8_t channel, uint32_t *out)
	Pop one 32-bit sample from the receive FIFO.
ra8_err_t	ra8_ssie_write_buffer (uint8_t channel, const uint32_t buffer, uint16_t samples, uint16_t out_written)
	Drain a host buffer into the TX FIFO until either runs out.
ra8_err_t	ra8_ssie_read_buffer (uint8_t channel, uint32_t buffer, uint16_t samples, uint16_t out_read)
	Empty the RX FIFO into a host buffer until either runs out.
ra8_err_t	ra8_ssie_get_status (uint8_t channel, ra8_ssie_status_t *out)
	Snapshot SSISR + SSIFSR into a status struct.
ra8_err_t	ra8_ssie_clear_status (uint8_t channel, uint32_t mask)
	Clear sticky error flags in SSISR.
ra8_err_t	ra8_ssie_set_irq_enable (uint8_t channel, uint32_t mask, bool enable)
	Update the IRQ enable mask without rewriting SSICR fully.
ra8_err_t	ra8_ssie_attach_handler (ra8_ssie_event_fn_t fn, void *ctx)
	Attach a shared event callback for both SSIE channels.
void	ra8_ssie_dispatch (uint8_t channel)
	ISR helper: fire the registered event handler.
ra8_err_t	ra8_ssie_set_fifo_threshold (uint8_t channel, uint8_t tx_threshold, uint8_t rx_threshold)
	Programme SSITDMR / SSIRDMR FIFO thresholds in one call.
ra8_err_t	ra8_ssie_enter_stop (uint8_t channel)
	Gate the channel's MSTP bit (preserve register state).
ra8_err_t	ra8_ssie_exit_stop (uint8_t channel)
	Re-ungate the channel's MSTP bit.

Variables
static const char *	s_tag = "SSIE"
	Logger tag for ra8_log_* messages produced by this driver.
static const ra8_mstp_t	s_ssie_mstp_table [k_ra8_ssie_channel_count]
	Channel-index -> MSTP id lookup.
ra8_ssie_runtime_t	g_ssie_runtime [k_ra8_ssie_channel_count]
	Per-channel SSIE runtime state, shared across the ra8_ssie split.
static ra8_ssie_event_fn_t	s_ssie_fn
	Globally registered SSIE event callback (one slot, shared).
static void *	s_ssie_ctx
	Opaque context delivered to s_ssie_fn on dispatch.

Detailed Description

Serial Sound Interface Enhanced (SSIE / I2S) driver implementation.

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

Full-coverage implementation of HUM Ch 46 "Serial Sound Interface Enhanced (SSIE)" pages 3051-3121. Every documented register field is reachable, every operating mode (I2S, left/right justified, monaural, TDM 4/6/8) is selectable through the ra8_ssie_format_t enum, every IRQ source (TXI/RXI/IDLE/error) is dispatched through a unified callback, and DMAC channels are pumped through a thin adapter over ra8_dmac.

Every register access carries a HUM Ch 46 citation against r01uh1065ej0130-ra8d2.pdf. FSP r_ssi.c was used as a reference for the start/stop sequence and SSIFCR poll loop only; no source code was copied from the FSP tree.

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

Definition in file ra8_ssie.c.

Function Documentation

◆ internal_apply_dir_irq_bits()

void internal_apply_dir_irq_bits	(	uint32_t	desired_ren_ten,
		uint32_t *	ssicr,
		uint32_t *	ssifcr )

static

Apply per-direction IRQ-enable bits to in-progress SSICR/SSIFCR.

Sets TUIEN+TIE for TX-enabled directions and ROIEN+RIE for RX-enabled directions per HUM Ch 46.2.1 p 3057 and HUM Ch 46.2.3 p 3077.

Parameters

[in]	desired_ren_ten	See implementation.
[in]	ssicr	See implementation.
[in]	ssifcr	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 472 of file ra8_ssie.c.

References k_ra8_ssie_mask_ren, k_ra8_ssie_mask_rie, k_ra8_ssie_mask_roien, k_ra8_ssie_mask_ten, k_ra8_ssie_mask_tie, and k_ra8_ssie_mask_tuien.

Referenced by ra8_ssie_start().

◆ internal_apply_init_regs()

void internal_apply_init_regs	(	volatile r_ssie_regs_t *	reg,
		const ra8_ssie_cfg_t *	cfg,
		uint8_t	frm,
		uint8_t	pdta,
		uint8_t	sdta,
		uint8_t	omod )

static

Stamp SSICR/SSIOFR/SSISCR/SSIFCR for a freshly reset SSIE block.

See implementation.

Parameters

[in]	reg	See implementation.
[in]	cfg	See implementation.
[in]	frm	See implementation.
[in]	pdta	See implementation.
[in]	sdta	See implementation.
[in]	omod	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 597 of file ra8_ssie.c.

References internal_build_ssicr(), internal_build_ssifcr(), internal_build_ssiofr(), internal_build_ssiscr(), ra8_ssie_cfg_t::rx_threshold, r_ssie_regs_t::SSICR, r_ssie_regs_t::SSIFCR, r_ssie_regs_t::SSIOFR, r_ssie_regs_t::SSISCR, and ra8_ssie_cfg_t::tx_threshold.

Referenced by ra8_ssie_init().

◆ internal_build_ssicr()

uint32_t internal_build_ssicr	(	const ra8_ssie_cfg_t *	cfg,
		uint8_t	frm,
		uint8_t	pdta,
		uint8_t	sdta )

static

Build the SSICR value from a config descriptor.

Packs role / divider / data + system word lengths into a 32-bit register image. TEN/REN are intentionally left clear so the caller can prime the TX FIFO before starting communication (HUM Ch 46.6.2 "Transmission" p 3098).

Parameters

[in]	cfg	See implementation.
[in]	frm	See implementation.
[in]	pdta	See implementation.
[in]	sdta	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 245 of file ra8_ssie.c.

References ra8_ssie_cfg_t::bckp_rising, ra8_ssie_cfg_t::bclk_div, ra8_ssie_cfg_t::data_word, k_ra8_ssie_bit_ckdv0, k_ra8_ssie_bit_dwl0, k_ra8_ssie_bit_frm0, k_ra8_ssie_bit_swl0, k_ra8_ssie_mask_bckp, k_ra8_ssie_mask_ckdv, k_ra8_ssie_mask_cks, k_ra8_ssie_mask_del, k_ra8_ssie_mask_dwl, k_ra8_ssie_mask_frm, k_ra8_ssie_mask_lrckp, k_ra8_ssie_mask_mst, k_ra8_ssie_mask_pdta, k_ra8_ssie_mask_sdta, k_ra8_ssie_mask_spdp, k_ra8_ssie_mask_swl, k_ra8_ssie_role_controller, ra8_ssie_cfg_t::long_frame, ra8_ssie_cfg_t::lrckp_low, ra8_ssie_cfg_t::role, ra8_ssie_cfg_t::spdp_high, ra8_ssie_cfg_t::system_word, and ra8_ssie_cfg_t::use_gpt_clk.

Referenced by internal_apply_init_regs().

◆ internal_build_ssifcr()

uint32_t internal_build_ssifcr ( const ra8_ssie_cfg_t * cfg )

static

Pack SSIFCR (FIFO control register) value from cfg.

See HUM Ch 46.2.3 "SSIFCR : FIFO Control Register" p 3077.

Parameters

[in] cfg 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 390 of file ra8_ssie.c.

References ra8_ssie_cfg_t::byte_swap, ra8_ssie_cfg_t::enable_aucke, k_ra8_ssie_mask_aucke, k_ra8_ssie_mask_bsw, k_ra8_ssie_role_controller, and ra8_ssie_cfg_t::role.

Referenced by internal_apply_init_regs().

◆ internal_build_ssiofr()

uint32_t internal_build_ssiofr	(	const ra8_ssie_cfg_t *	cfg,
		uint8_t	omod )

static

Pack SSIOFR (audio format register) value from cfg + decoded OMOD.

Honours the HUM Ch 46.2.7 Note 2 p 3091 constraint that BCKASTP and LRCONT must not be set together: LRCONT wins, BCKASTP is silently dropped when both are requested.

Parameters

[in]	cfg	See implementation.
[in]	omod	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 362 of file ra8_ssie.c.

References ra8_ssie_cfg_t::bck_idle_stop, k_ra8_ssie_mask_bckastp, k_ra8_ssie_mask_lrcont, k_ra8_ssie_mask_omod, k_ra8_ssie_role_controller, ra8_ssie_cfg_t::lr_continue, and ra8_ssie_cfg_t::role.

Referenced by internal_apply_init_regs().

◆ internal_build_ssiscr()

uint32_t internal_build_ssiscr	(	uint8_t	tx_threshold,
		uint8_t	rx_threshold )

static

Pack SSISCR (status control register) value from TX/RX thresholds.

See HUM Ch 46.2.8 "SSISCR : Status Control Register" p 3094.

Parameters

[in]	tx_threshold	See implementation.
[in]	rx_threshold	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 419 of file ra8_ssie.c.

References k_ra8_ssie_mask_rdfs, k_ra8_ssie_mask_tdes, k_ra8_ssie_shift_rdfs, and k_ra8_ssie_shift_tdes.

Referenced by internal_apply_init_regs(), and ra8_ssie_set_thresholds().

◆ internal_decode_event()

uint8_t internal_decode_event	(	uint32_t	ssisr,
		uint32_t	ssifsr )

static

Decode SSISR/SSIFSR into a ra8_ssie_event_t bitmap.

Parameters

[in]	ssisr	Raw SSISR snapshot (HUM Ch 46.2.2 p 3066).
[in]	ssifsr	Raw SSIFSR snapshot (HUM Ch 46.2.4 p 3083).

Returns: Bitmap of ra8_ssie_event_t flags.

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 194 of file ra8_ssie.c.

References k_ra8_ssie_evt_idle, k_ra8_ssie_evt_none, k_ra8_ssie_evt_rx_full, k_ra8_ssie_evt_rx_over, k_ra8_ssie_evt_rx_under, k_ra8_ssie_evt_tx_empty, k_ra8_ssie_evt_tx_over, k_ra8_ssie_evt_tx_under, k_ra8_ssie_mask_iirq, k_ra8_ssie_mask_rdf, k_ra8_ssie_mask_roirq, k_ra8_ssie_mask_ruirq, k_ra8_ssie_mask_tde, k_ra8_ssie_mask_toirq, and k_ra8_ssie_mask_tuirq.

Referenced by ra8_ssie_dispatch(), and ra8_ssie_get_status().

◆ internal_format_decode()

bool internal_format_decode	(	ra8_ssie_format_t	format,
		uint8_t *	out_omod,
		uint8_t *	out_frm,
		uint8_t *	out_pdta,
		uint8_t *	out_sdta )

static

Translate a public format enum to OMOD + FRM register fields.

Parameters

[in]	format	Public format enum.
[out]	out_omod	Receives SSIOFR.OMOD encoding (0..2).
[out]	out_frm	Receives SSICR.FRM encoding (0..3).
[out]	out_pdta	Receives PDTA polarity (right justify uses 1).
[out]	out_sdta	Receives SDTA polarity (left justify uses 0).

Returns: true on a recognised enum value, false otherwise.

See HUM Ch 46.2.1 FRM table p 3057 and HUM Ch 46.2.7 OMOD table p 3091.

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 132 of file ra8_ssie.c.

References k_ra8_ssie_format_i2s, k_ra8_ssie_format_left_just, k_ra8_ssie_format_monaural, k_ra8_ssie_format_right_just, k_ra8_ssie_format_tdm_4, k_ra8_ssie_format_tdm_6, k_ra8_ssie_format_tdm_8, k_ra8_ssie_frm_alt1, k_ra8_ssie_frm_alt2, k_ra8_ssie_frm_alt3, k_ra8_ssie_frm_default, k_ra8_ssie_omod_i2s, k_ra8_ssie_omod_monaural, and k_ra8_ssie_omod_tdm.

Referenced by internal_validate_init_cfg().

◆ internal_pulse_fifo_reset()

ra8_err_t internal_pulse_fifo_reset	(	volatile r_ssie_regs_t *	reg,
		uint32_t	ssifcr_base )

static

Pulse RFRST/TFRST high then low and wait for both bits to clear.

HUM Ch 46.2.3 "SSIFCR : FIFO Control Register" p 3077. ssifcr_base is the desired post-reset SSIFCR image (RFRST/TFRST clear).

Parameters

[in]	reg	See implementation.
[in]	ssifcr_base	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 447 of file ra8_ssie.c.

References internal_wait_fifo_reset_clear(), k_ra8_ssie_mask_rfrst_tfrst, and r_ssie_regs_t::SSIFCR.

Referenced by ra8_ssie_start().

◆ internal_pulse_ssi_reset()

ra8_err_t internal_pulse_ssi_reset ( volatile r_ssie_regs_t * reg )

static

Drive the soft-reset sequence required before SSICR writes.

Pulses SSIRST high then low, then polls SSIFCR until SSIRST clears. HUM Ch 46.2.3 "SSIFCR : FIFO Control Register" p 3077.

Parameters

[in] reg 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 543 of file ra8_ssie.c.

References internal_wait_ssirst_clear(), k_ra8_ssie_mask_ssirst, and r_ssie_regs_t::SSIFCR.

Referenced by internal_ssie_power_up().

◆ internal_ssie_power_up()

ra8_err_t internal_ssie_power_up	(	uint8_t	channel,
		volatile r_ssie_regs_t *	reg )

static

Power up the SSIE block: enable MSTP then drive SSIRST low.

Combines the two HUM-required pre-config steps so ra8_ssie_init stays under the per-function statement budget. HUM Ch 11.2.8 p 446 for MSTPCRC, HUM Ch 46.2.3 p 3077 for the reset pulse.

Parameters

[in]	channel	See implementation.
[in]	reg	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 570 of file ra8_ssie.c.

References internal_pulse_ssi_reset(), k_ra8_ok, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_ssie_mstp_table, and s_tag.

Referenced by ra8_ssie_init().

◆ internal_validate_init_cfg()

ra8_err_t internal_validate_init_cfg	(	const ra8_ssie_cfg_t *	cfg,
		uint8_t *	out_omod,
		uint8_t *	out_frm,
		uint8_t *	out_pdta,
		uint8_t *	out_sdta )

static

Format-decode wrapper that validates ranges before delegation.

Parameters

[in]	cfg	Caller's SSIE config.
[out]	out_omod	SSIOFR.OMOD encoding (0..2).
[out]	out_frm	SSICR.FRM encoding (0..3).
[out]	out_pdta	Right-justify polarity bit.
[out]	out_sdta	Left-justify polarity bit.

Returns: k_ra8_ok on success, k_ra8_err_invalid_arg if thresholds are out of range or the format enum is unrecognised.

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 506 of file ra8_ssie.c.

References ra8_ssie_cfg_t::format, internal_format_decode(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_thresh_max, ra8_ssie_cfg_t::rx_threshold, and ra8_ssie_cfg_t::tx_threshold.

Referenced by ra8_ssie_init().

◆ internal_wait_fifo_reset_clear()

ra8_err_t internal_wait_fifo_reset_clear ( volatile r_ssie_regs_t * reg )

static

Bounded poll on SSIFCR until both FIFO reset bits clear.

See implementation.

Parameters

[in] reg 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 334 of file ra8_ssie.c.

References k_ra8_ssie_mask_rfrst_tfrst, k_ra8_ssie_reset_poll_max, ra8_hw_wait_flag_clear32(), and r_ssie_regs_t::SSIFCR.

Referenced by internal_pulse_fifo_reset().

◆ internal_wait_ssirst_clear()

ra8_err_t internal_wait_ssirst_clear ( volatile r_ssie_regs_t * reg )

static

Bounded poll on SSIFCR until SSIRST clears.

Returns: k_ra8_ok if SSIRST self-cleared, otherwise k_ra8_err_hw_timeout.

See HUM Ch 46.2.3 "SSIRST" description, p 3077-3078. In fake/host mode the bit clears immediately after we write 0; in production a few PCLK cycles are required.

Parameters

[in] reg 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 311 of file ra8_ssie.c.

References k_ra8_ssie_mask_ssirst, k_ra8_ssie_reset_poll_max, ra8_hw_wait_flag_clear32(), and r_ssie_regs_t::SSIFCR.

Referenced by internal_pulse_ssi_reset(), and ra8_ssie_start_recovery().

◆ priv_ra8_ssie_internal_regs()

volatile r_ssie_regs_t * priv_ra8_ssie_internal_regs ( uint8_t channel )

Implementation of priv_ra8_ssie_internal_regs() – bounds-check + accessor.

Validate an SSIE channel index and return its register block.

Definition at line 101 of file ra8_ssie.c.

References k_ra8_ssie_channel_count, and ra8_ssie().

Referenced by ra8_ssie_attach_dma(), ra8_ssie_clear_status(), ra8_ssie_deinit(), ra8_ssie_dispatch(), ra8_ssie_get_status(), ra8_ssie_init(), ra8_ssie_mute(), ra8_ssie_read_buffer(), ra8_ssie_read_sample(), ra8_ssie_recv_iso(), ra8_ssie_send_iso(), ra8_ssie_set_irq_enable(), ra8_ssie_set_thresholds(), ra8_ssie_start(), ra8_ssie_start_recovery(), ra8_ssie_stop(), ra8_ssie_write_buffer(), and ra8_ssie_write_sample().

◆ ra8_ssie_attach_handler()

ra8_err_t ra8_ssie_attach_handler	(	ra8_ssie_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a shared event callback for both SSIE channels.

Parameters

[in]	fn	Callback invoked from ra8_ssie_dispatch.
[in]	ctx	Opaque context forwarded to the callback.

Returns: ra8_err_t error code.

Return values

k_ra8_ok Always succeeds (handler may be nullptr to detach).

Precondition: None.; Storage for the function pointer pair is process-global.

Postcondition: Subsequent ra8_ssie_dispatch calls invoke fn.; Previous handler is replaced.

Note: Thread safety: not thread-safe (writes two static pointers).

Since: 0.1.0

Definition at line 915 of file ra8_ssie.c.

References k_ra8_ok, s_ssie_ctx, and s_ssie_fn.

◆ ra8_ssie_clear_status()

ra8_err_t ra8_ssie_clear_status	(	uint8_t	channel,
		uint32_t	mask )

nodiscard

Clear sticky error flags in SSISR.

Performs a write-1-to-clear on the bits in mask that overlap SSISR.{ROIRQ, RUIRQ, TOIRQ, TUIRQ}. Other bits are ignored. See HUM Ch 46.2.2, p 3066-3071 for the per-flag clear protocol.

Parameters

[in]	channel	Channel index.
[in]	mask	Bitmask of flags to clear (use k_ra8_ssie_mask_err_all to clear them all).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Mask written.
k_ra8_err_invalid_arg	channel out of range.

Precondition: Channel initialized.; Caller already read SSISR (W1C requires "read 1 then write 0").

Postcondition: Flags in mask are cleared.; Other SSISR bits unchanged.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 884 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_err_all, priv_ra8_ssie_internal_regs(), and r_ssie_regs_t::SSISR.

◆ ra8_ssie_deinit()

ra8_err_t ra8_ssie_deinit ( uint8_t channel )

nodiscard

Tear down an SSIE channel and gate its clock.

Parameters

[in] channel Channel index.

Returns: ra8_err_t error code.

Precondition: IRQs masked or single-threaded.; ra8_ssie_init previously succeeded for channel.

Postcondition: SSICR.TEN = 0 and SSICR.REN = 0.; MSTP bit set (peripheral gated).

Note: Thread safety: not thread-safe.

See also: ra8_ssie_init

Since: 0.1.0

Definition at line 638 of file ra8_ssie.c.

References g_ssie_runtime, k_ra8_err_invalid_arg, k_ra8_ssie_mask_aucke, k_ra8_ssie_mask_ren_ten, priv_ra8_ssie_internal_regs(), ra8_mstp_disable(), ra8_ssie_detach_dma(), s_ssie_mstp_table, r_ssie_regs_t::SSICR, and r_ssie_regs_t::SSIFCR.

Referenced by main().

◆ ra8_ssie_dispatch()

void ra8_ssie_dispatch ( uint8_t channel )

ISR helper: fire the registered event handler.

Snapshots SSISR for channel (HUM Ch 51 "Serial Sound Interface Enhanced (SSIE)", p 2731), then invokes the attached event handler. Out-of-range channel indices and unattached slots are silently dropped so spurious IRQs are harmless.

Parameters

[in] channel Channel that fired.

Precondition: Channel index in range (out-of-range silently dropped).; A handler was attached via ra8_ssie_attach_handler.

Postcondition: The registered handler ran with the SSISR snapshot.; No SSISR flags are auto-cleared (caller's responsibility).

Note: Thread safety: callable from IRQ context.

Since: 0.1.0

Definition at line 923 of file ra8_ssie.c.

References internal_decode_event(), priv_ra8_ssie_internal_regs(), s_ssie_ctx, s_ssie_fn, r_ssie_regs_t::SSIFSR, and r_ssie_regs_t::SSISR.

◆ ra8_ssie_enter_stop()

ra8_err_t ra8_ssie_enter_stop ( uint8_t channel )

nodiscard

Gate the channel's MSTP bit (preserve register state).

Parameters

[in] channel Channel index.

Returns: ra8_err_t error code.

Precondition: Channel was initialized.; IRQs masked.

Postcondition: MSTP bit set, peripheral clock removed.; SSICR / SSIOFR contents persist (registers retain values).

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 949 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ssie_channel_count, ra8_mstp_disable(), and s_ssie_mstp_table.

◆ ra8_ssie_exit_stop()

ra8_err_t ra8_ssie_exit_stop ( uint8_t channel )

nodiscard

Re-ungate the channel's MSTP bit.

Parameters

[in] channel Channel index.

Returns: ra8_err_t error code.

Precondition: Channel was previously gated via ra8_ssie_enter_stop.; IRQs masked.

Postcondition: MSTP bit cleared, peripheral clock restored.; No SSICR / SSIOFR fields reprogrammed by this call.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 957 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ssie_channel_count, ra8_mstp_enable(), and s_ssie_mstp_table.

◆ ra8_ssie_get_status()

ra8_err_t ra8_ssie_get_status	(	uint8_t	channel,
		ra8_ssie_status_t *	out )

nodiscard

Snapshot SSISR + SSIFSR into a status struct.

Parameters

[in]	channel	Channel index.
[out]	out	Non-NULL status struct.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Snapshot taken.
k_ra8_err_null_ptr	out was nullptr.
k_ra8_err_invalid_arg	channel out of range.

Precondition: Channel previously initialized, out non-NULL.; IRQs may be enabled (read-only).

Postcondition: *out reflects a coherent SSISR/SSIFSR snapshot.; No registers are modified.

Note: Thread safety: safe to call from IRQ context.

Since: 0.1.0

Definition at line 860 of file ra8_ssie.c.

References ra8_ssie_status_t::error, ra8_ssie_status_t::events, ra8_ssie_status_t::idle, internal_decode_event(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_err_all, k_ra8_ssie_mask_iirq, k_ra8_ssie_mask_rdc, k_ra8_ssie_mask_rdf, k_ra8_ssie_mask_tdc, k_ra8_ssie_mask_tde, k_ra8_ssie_shift_rdc, k_ra8_ssie_shift_tdc, priv_ra8_ssie_internal_regs(), RA8_CHECK_NULL_PTR, ra8_ssie_status_t::rx_count, ra8_ssie_status_t::rx_full, s_tag, r_ssie_regs_t::SSIFSR, ra8_ssie_status_t::ssifsr, r_ssie_regs_t::SSISR, ra8_ssie_status_t::ssisr, ra8_ssie_status_t::tx_count, and ra8_ssie_status_t::tx_empty.

◆ ra8_ssie_init()

ra8_err_t ra8_ssie_init	(	uint8_t	channel,
		const ra8_ssie_cfg_t *	cfg )

nodiscard

Initialise an SSIE channel for I2S / TDM / monaural transfer.

Algorithm (HUM Ch 46.6.1 "Initial Settings", p 3097):

Ungate MSTPC8 (SSIE0) or MSTPC7 (SSIE1) via ra8_mstp.
Software-reset the channel (SSIFCR.SSIRST = 1, then 0).
Programme SSICR with role / clock divider / word lengths + polarity (BCKP, LRCKP, SPDP) and DEL (short/long frame).
Programme SSIOFR with the audio format (OMOD), LRCONT and BCKASTP.
Programme SSISCR with the FIFO watermarks.
Programme SSIFCR with AUCKE + BSW.
Leave TEN / REN / interrupts cleared so the caller can prime the FIFOs and call ra8_ssie_start.

Parameters

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

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel initialized.
k_ra8_err_null_ptr	cfg was nullptr.
k_ra8_err_invalid_arg	channel out of range.
k_ra8_err_hw_timeout	SSIRST did not self-clear within k_ra8_ssie_reset_poll_max reads.

Precondition: IRQs masked or single-threaded init context.; ra8_mstp_init() has run.

Postcondition: SSICR holds the requested format with TEN/REN clear.; SSIE channel is ungated (MSTP bit cleared).

Note: Thread safety: not thread-safe.

See also: ra8_ssie_deinit; ra8_ssie_start

Since: 0.1.0

Definition at line 610 of file ra8_ssie.c.

References g_ssie_runtime, internal_apply_init_regs(), internal_ssie_power_up(), internal_validate_init_cfg(), k_ra8_err_invalid_arg, k_ra8_ok, priv_ra8_ssie_internal_regs(), RA8_CHECK_NULL_PTR, ra8_log_info_val, RA8_RETURN_ON_ERROR, and s_tag.

Referenced by internal_ssie_loop_run(), and ra8_board_audio_init().

◆ ra8_ssie_mute()

ra8_err_t ra8_ssie_mute	(	uint8_t	channel,
		bool	enable )

nodiscard

Enable or disable mute on the next frame boundary.

Toggles SSICR.MUEN per HUM Ch 46.2.1 (p 3056). Data is still written to the TX line but its bits are forced to zero.

Parameters

[in]	channel	Channel index.
[in]	enable	true to mute, false to un-mute.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	MUEN updated.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized.; IRQs masked.

Postcondition: SSICR.MUEN reflects enable.; No other SSICR field touched.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 740 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_muen, priv_ra8_ssie_internal_regs(), and r_ssie_regs_t::SSICR.

◆ ra8_ssie_read_buffer()

ra8_err_t ra8_ssie_read_buffer	(	uint8_t	channel,
		uint32_t *	buffer,
		uint16_t	samples,
		uint16_t *	out_read )

nodiscard

Empty the RX FIFO into a host buffer until either runs out.

Parameters

[in]	channel	Channel index.
[out]	buffer	Destination samples.
[in]	samples	Destination-buffer length in samples.
[out]	out_read	Receives the number of samples consumed.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	At least zero samples consumed.
k_ra8_err_null_ptr	buffer or out_read was NULL.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized.; buffer and out_read non-NULL.

Postcondition: *out_read <= samples.; SSIFSR.RDF cleared if any sample was read.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 829 of file ra8_ssie.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_read_sample()

ra8_err_t ra8_ssie_read_sample	(	uint8_t	channel,
		uint32_t *	out )

nodiscard

Pop one 32-bit sample from the receive FIFO.

Parameters

[in]	channel	Channel index.
[out]	out	Receives the sample bits.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Sample read.
k_ra8_err_null_ptr	out was nullptr.
k_ra8_err_invalid_arg	channel out of range.

Precondition: Channel previously initialized, out non-NULL.; Caller has confirmed RDF or non-zero RDC.

Postcondition: *out holds the dequeued sample.; SSIFRDR read pointer advanced by one stage.

Note: Thread safety: not thread-safe.

See also: ra8_ssie_write_sample

Since: 0.1.0

Definition at line 782 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ok, priv_ra8_ssie_internal_regs(), RA8_CHECK_NULL_PTR, s_tag, and r_ssie_regs_t::SSIFRDR.

◆ ra8_ssie_set_fifo_threshold()

ra8_err_t ra8_ssie_set_fifo_threshold	(	uint8_t	channel,
		uint8_t	tx_threshold,
		uint8_t	rx_threshold )

nodiscard

Programme SSITDMR / SSIRDMR FIFO thresholds in one call.

Convenience wrapper that drives ra8_ssie_set_thresholds with the exact pair of TX / RX FIFO watermarks the audio pipeline wants. The SSIE only carries SSISCR.TDES / SSISCR.RDFS (HUM Ch 46.2.8 p 3094) – the names SSITDMR / SSIRDMR are aliases the application layer uses for clarity.

Parameters

[in]	channel	Channel index (0 = SSIE0, 1 = SSIE1).
[in]	tx_threshold	TDES[4:0]: TX-empty IRQ when TDC <= value.
[in]	rx_threshold	RDFS[4:0]: RX-full IRQ when RDC > value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Thresholds programmed.
k_ra8_err_invalid_arg	Channel out of range or threshold > 0x1F.

Precondition: Channel previously initialized.; Channel currently idle.

Postcondition: SSISCR reflects the requested thresholds.; Other SSISCR fields are zero (reserved).

Note: Thread safety: not thread-safe.

See also: ra8_ssie_set_thresholds

Since: 0.1.0

Definition at line 941 of file ra8_ssie.c.

References ra8_ssie_set_thresholds().

◆ ra8_ssie_set_irq_enable()

ra8_err_t ra8_ssie_set_irq_enable	(	uint8_t	channel,
		uint32_t	mask,
		bool	enable )

nodiscard

Update the IRQ enable mask without rewriting SSICR fully.

Performs read-modify-write on SSICR.{IIEN, ROIEN, RUIEN, TOIEN, TUIEN}. Pass k_ra8_ssie_mask_irq_all in mask to enable every IRQ source.

Parameters

[in]	channel	Channel index.
[in]	mask	Mask of bits to set / clear.
[in]	enable	true to set bits, false to clear.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SSICR updated.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel initialized.; Caller has registered an event handler via ra8_ssie_attach_handler.

Postcondition: Requested bits set or cleared in SSICR.; Other SSICR fields untouched.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 897 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_irq_all, priv_ra8_ssie_internal_regs(), and r_ssie_regs_t::SSICR.

◆ ra8_ssie_set_thresholds()

ra8_err_t ra8_ssie_set_thresholds	(	uint8_t	channel,
		uint8_t	tx_threshold,
		uint8_t	rx_threshold )

nodiscard

Update the FIFO trigger watermarks at runtime.

Parameters

[in]	channel	Channel index.
[in]	tx_threshold	TDES[4:0]: TX-empty IRQ when TDC <= value.
[in]	rx_threshold	RDFS[4:0]: RX-full IRQ when RDC > value.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	SSISCR updated.
k_ra8_err_invalid_arg	Channel out of range or threshold > 0x1F.

Precondition: Channel previously initialized.; Channel currently idle (SSISR.IIRQ = 1).

Postcondition: SSISCR.TDES = tx_threshold, SSISCR.RDFS = rx_threshold.; Other SSISCR bits zero (reserved).

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 757 of file ra8_ssie.c.

References internal_build_ssiscr(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_thresh_max, priv_ra8_ssie_internal_regs(), and r_ssie_regs_t::SSISCR.

Referenced by ra8_ssie_set_fifo_threshold().

◆ ra8_ssie_start()

ra8_err_t ra8_ssie_start	(	uint8_t	channel,
		ra8_ssie_dir_t	dir )

nodiscard

Enable transmission, reception, or full duplex.

Implements HUM Ch 46.6.2 "Transmission" (p 3098) and 46.6.3 "Reception" (p 3099). Resets both FIFOs (TFRST/RFRST), enables the matching interrupt mask in SSIFCR (TIE/RIE), enables the matching error masks in SSICR (TUIEN/ROIEN), then sets TEN/REN.

Parameters

[in]	channel	Channel index.
[in]	dir	k_ra8_ssie_dir_tx, ..._rx or ..._tx_rx.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Direction enabled.
k_ra8_err_invalid_arg	Channel or direction out of range.
k_ra8_err_busy	SSIE is not idle and direction would change (must call ra8_ssie_stop first).

Precondition: Channel previously initialized.; IRQs masked while modifying SSICR.

Postcondition: Requested REN/TEN bits asserted.; Matching IRQ enable bits asserted.

Note: Thread safety: not thread-safe.

See also: ra8_ssie_stop

Since: 0.1.0

Definition at line 656 of file ra8_ssie.c.

References internal_apply_dir_irq_bits(), internal_pulse_fifo_reset(), k_ra8_err_busy, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_dir_rx, k_ra8_ssie_dir_tx, k_ra8_ssie_dir_tx_rx, k_ra8_ssie_mask_iirq, k_ra8_ssie_mask_ren_ten, priv_ra8_ssie_internal_regs(), RA8_RETURN_ON_ERROR, s_tag, r_ssie_regs_t::SSICR, r_ssie_regs_t::SSIFCR, and r_ssie_regs_t::SSISR.

Referenced by internal_ssie_loop_run().

◆ ra8_ssie_start_recovery()

ra8_err_t ra8_ssie_start_recovery ( uint8_t channel )

nodiscard

Force the channel back into a known idle state.

Issues a software reset (SSIFCR.SSIRST), waits for it to self-clear, then clears every error flag in SSISR. Used by the IRQ dispatcher when a TUIRQ/ROIRQ pair is observed.

Parameters

[in] channel Channel index.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Channel reset and flags cleared.
k_ra8_err_invalid_arg	Channel out of range.
k_ra8_err_hw_timeout	SSIRST did not self-clear in bound.

Precondition: Channel previously initialized.; Caller has consumed any pending RX data (FIFO is reset).

Postcondition: FIFOs are empty and all SSISR error flags cleared.; SSICR retains its mode bits (only TEN/REN are touched).

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 719 of file ra8_ssie.c.

References internal_wait_ssirst_clear(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_err_all, k_ra8_ssie_mask_ssirst, priv_ra8_ssie_internal_regs(), RA8_RETURN_ON_ERROR, s_tag, r_ssie_regs_t::SSIFCR, and r_ssie_regs_t::SSISR.

◆ ra8_ssie_stop()

ra8_err_t ra8_ssie_stop ( uint8_t channel )

nodiscard

Disable transmission and reception.

Implements HUM Ch 46.6.4 "Idle Operation" p 3100. Clears REN/TEN/error-IEN, leaves IIEN set so the caller is notified when SSIE finishes the in-flight frame.

Parameters

[in] channel Channel index.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Stop requested; IIEN now armed.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized.; IRQs masked while modifying SSICR.

Postcondition: REN/TEN/error-IEN bits cleared.; IIEN bit set so the next IIRQ fires the callback.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 697 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_ssie_mask_err_ien, k_ra8_ssie_mask_iien, k_ra8_ssie_mask_ren_ten, k_ra8_ssie_mask_rie_tie, priv_ra8_ssie_internal_regs(), r_ssie_regs_t::SSICR, and r_ssie_regs_t::SSIFCR.

Referenced by main().

◆ ra8_ssie_write_buffer()

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

nodiscard

Drain a host buffer into the TX FIFO until either runs out.

Loops while samples > 0 and SSIFSR.TDC < depth. Returns the number of samples actually written via out_written.

Parameters

[in]	channel	Channel index.
[in]	buffer	Source samples.
[in]	samples	Source-buffer length in samples.
[out]	out_written	Receives the number of samples written.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	At least zero samples written.
k_ra8_err_null_ptr	buffer or out_written was NULL.
k_ra8_err_invalid_arg	Channel out of range.

Precondition: Channel previously initialized.; buffer and out_written non-NULL.

Postcondition: *out_written <= samples.; SSIFSR.TDE cleared if any sample was written.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 794 of file ra8_ssie.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.

Referenced by ra8_board_audio_play_sample_block().

◆ ra8_ssie_write_sample()

ra8_err_t ra8_ssie_write_sample	(	uint8_t	channel,
		uint32_t	sample )

nodiscard

Push one 32-bit sample into the transmit FIFO.

Performs a single 32-bit write to SSIFTDR (HUM Ch 46.2.5 p 3088). Samples wider than the configured DWL are truncated by the FIFO shift logic. Data alignment within the 32-bit word is governed by SSICR.PDTA / SSICR.SDTA.

Parameters

[in]	channel	Channel index (0 = SSIE0, 1 = SSIE1).
[in]	sample	Sample bits.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Sample queued.
k_ra8_err_invalid_arg	channel out of range.

Precondition: Channel was previously initialized.; Caller has (or accepts) FIFO space (TDE = 1).

Postcondition: One write to SSIFTDR has been issued.; No other registers are modified.

Note: Thread safety: not thread-safe.

See also: ra8_ssie_read_sample

Since: 0.1.0

Definition at line 771 of file ra8_ssie.c.

References k_ra8_err_invalid_arg, k_ra8_ok, priv_ra8_ssie_internal_regs(), and r_ssie_regs_t::SSIFTDR.

Referenced by internal_ssie_loop_run().

Variable Documentation

◆ g_ssie_runtime

ra8_ssie_runtime_t g_ssie_runtime[k_ra8_ssie_channel_count]

Initial value:

                                  = {
  {.tx_dma_channel = k_ra8_ssie_dma_ch_unused,
   .rx_dma_channel = k_ra8_ssie_dma_ch_unused,
   .initialized    = false,
   .dma_attached   = false},
  {.tx_dma_channel = k_ra8_ssie_dma_ch_unused,
   .rx_dma_channel = k_ra8_ssie_dma_ch_unused,
   .initialized    = false,
   .dma_attached   = false},
}

Per-channel SSIE runtime state, shared across the ra8_ssie split.

Per-channel runtime state.

Single definition lives in ra8_ssie.c; ra8_ssie_stream.c reads and writes the same object through this extern declaration. The mutable DMA-channel bookkeeping must remain one object so that attach/detach in the stream TU and init/deinit in the lifecycle TU agree on per-channel state.

Note: Module-private to libs/ra8_hal/src; not part of the public surface.

Warning: Not thread-safe; callers must serialise concurrent access.

Since: 0.1.0

Initialized to zero / unused.

Single definition for the ra8_ssie split; ra8_ssie_stream.c shares this object via the extern declaration in ra8_hal_internal.h. External linkage (no static) is required so both translation units bind the same storage. The s_ssie_ prefix keeps it clang-tidy-clean and link-unique.

Definition at line 73 of file ra8_ssie.c.

Referenced by internal_start_rx_dma(), internal_start_tx_dma(), internal_unwind_tx_dma(), ra8_ssie_attach_dma(), ra8_ssie_attach_dma_pair(), ra8_ssie_deinit(), ra8_ssie_detach_dma(), and ra8_ssie_init().

◆ s_ssie_ctx

void* s_ssie_ctx

static

Opaque context delivered to s_ssie_fn on dispatch.

Note: Modified only via ra8_ssie_attach_handler.

Definition at line 98 of file ra8_ssie.c.

Referenced by ra8_ssie_attach_handler(), and ra8_ssie_dispatch().

◆ s_ssie_fn

ra8_ssie_event_fn_t s_ssie_fn

static

Globally registered SSIE event callback (one slot, shared).

Note: Modified only via ra8_ssie_attach_handler.

Definition at line 90 of file ra8_ssie.c.

Referenced by ra8_ssie_attach_handler(), and ra8_ssie_dispatch().

◆ s_ssie_mstp_table

const ra8_mstp_t s_ssie_mstp_table[k_ra8_ssie_channel_count]

static

Initial value:

                                          = {
  k_ra8_mstp_ssie0,
  k_ra8_mstp_ssie1,
}

Channel-index -> MSTP id lookup.

SSIE0 sits on MSTPC8 and SSIE1 on MSTPC7 per HUM Ch 11.2.8 "MSTPCRC : Module Stop Control Register C", p 446. The two enum values were already declared in ra8_mstp_regs.h.

Definition at line 58 of file ra8_ssie.c.

Referenced by internal_ssie_power_up(), ra8_ssie_deinit(), ra8_ssie_enter_stop(), and ra8_ssie_exit_stop().

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

Definition at line 47 of file ra8_ssie.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_apply_dir_irq_bits()

◆ internal_apply_init_regs()

◆ internal_build_ssicr()

◆ internal_build_ssifcr()

◆ internal_build_ssiofr()

◆ internal_build_ssiscr()

◆ internal_decode_event()

◆ internal_format_decode()

◆ internal_pulse_fifo_reset()

◆ internal_pulse_ssi_reset()

◆ internal_ssie_power_up()

◆ internal_validate_init_cfg()

◆ internal_wait_fifo_reset_clear()

◆ internal_wait_ssirst_clear()

◆ priv_ra8_ssie_internal_regs()

◆ ra8_ssie_attach_handler()

◆ ra8_ssie_clear_status()

◆ ra8_ssie_deinit()

◆ ra8_ssie_dispatch()

◆ ra8_ssie_enter_stop()

◆ ra8_ssie_exit_stop()

◆ ra8_ssie_get_status()

◆ ra8_ssie_init()

◆ ra8_ssie_mute()

◆ ra8_ssie_read_buffer()

◆ ra8_ssie_read_sample()

◆ ra8_ssie_set_fifo_threshold()

◆ ra8_ssie_set_irq_enable()

◆ ra8_ssie_set_thresholds()

◆ ra8_ssie_start()

◆ ra8_ssie_start_recovery()

◆ ra8_ssie_stop()

◆ ra8_ssie_write_buffer()

◆ ra8_ssie_write_sample()

Variable Documentation

◆ g_ssie_runtime

◆ s_ssie_ctx

◆ s_ssie_fn

◆ s_ssie_mstp_table

◆ s_tag