SCI_B DMA TX/RX descriptors + TXI/RXI/ERI ISR dispatch. More...

#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_dma.h"
#include "ra8_dmac.h"
#include "ra8_err.h"
#include "ra8_sci.h"
#include "ra8_sci_internal.h"
#include "ra8_sci_regs.h"

Include dependency graph for ra8_sci_dma_isr.c:

Functions
static ra8_err_t	internal_dma_args_ok (const volatile r_sci_regs_t *reg, uint16_t len)
	Report whether a DMA entry point's channel register and length are usable.
static ra8_dma_request_t	internal_make_dma_request (uintptr_t src, uintptr_t dst, uint16_t len, bool src_inc, bool dst_inc, ra8_dma_complete_fn_t on_complete, void *ctx)
ra8_err_t	ra8_sci_write_dma (uint8_t channel, const uint8_t data, uint16_t len, ra8_dma_complete_fn_t on_complete, void ctx, uint8_t *out_dma_channel)
	Kick off a DMA-backed TX transfer.
ra8_err_t	ra8_sci_read_dma (uint8_t channel, uint8_t out_buf, uint16_t len, ra8_dma_complete_fn_t on_complete, void ctx, uint8_t *out_dma_channel)
	Kick off a DMA-backed RX transfer.
void	ra8_sci_dispatch_txi (uint8_t channel)
	TXI dispatch – advance the TX callback.
void	ra8_sci_dispatch_rxi (uint8_t channel)
	RXI dispatch – hand a received byte to the RX callback.
void	ra8_sci_dispatch_eri (uint8_t channel)
	ERI dispatch – clear SSR error flags, invoke optional error callback (none in reserved for 3.1b).

Variables
static const char *	s_tag = "SCI"

Detailed Description

SCI_B DMA TX/RX descriptors + TXI/RXI/ERI ISR dispatch.

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

Companion translation unit to ra8_sci.c for the RA8D2 SCI_B driver (HUM Ch 38). Carries the DMA request-descriptor builders that wire a byte stream to/from TDR/RDR (ra8_sci_write_dma / ra8_sci_read_dma) and the interrupt dispatch entry points (ra8_sci_dispatch_txi / ra8_sci_dispatch_rxi / ra8_sci_dispatch_eri) that advance the per-channel async byte stream and fire the legacy attach callbacks.

The shared per-channel dispatch table (s_sci_state) is defined in ra8_sci.c and reached here through ra8_sci_internal.h. See ra8_sci.h for the public API contract and ra8_sci_regs.h for the register layout.

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

Since: 0.1.0

Definition in file ra8_sci_dma_isr.c.

Function Documentation

◆ internal_dma_args_ok()

ra8_err_t internal_dma_args_ok	(	const volatile r_sci_regs_t *	reg,
		uint16_t	len )

static

Report whether a DMA entry point's channel register and length are usable.

Both DMA entry points ask the same two questions of their arguments: did ra8_sci resolve the channel to a register block, and is the transfer length non-zero. Answering them here keeps each entry point to one early return and gives this check a single exit of its own.

Parameters

[in]	reg	Register block ra8_sci resolved for the caller's channel, or nullptr when the channel index is out of range.
[in]	len	Requested transfer length in bytes.

Returns: ra8_err_t Argument-validation verdict.

Return values

k_ra8_ok	Both the register block and the length are usable.
k_ra8_err_invalid_arg	The channel did not resolve, or `len` is zero.

Precondition: The caller has already null-checked its own pointer arguments.; reg is whatever ra8_sci returned for the caller's channel.

Postcondition: No hardware register is read or written.; The caller's arguments are unchanged.

Note: Thread-safe; the function is pure.

Since: Version 0.1.0

Definition at line 65 of file ra8_sci_dma_isr.c.

References k_ra8_err_invalid_arg, k_ra8_ok, and RA8_INTERNAL.

Referenced by ra8_sci_read_dma(), and ra8_sci_write_dma().

◆ internal_make_dma_request()

ra8_dma_request_t internal_make_dma_request	(	uintptr_t	src,
		uintptr_t	dst,
		uint16_t	len,
		bool	src_inc,
		bool	dst_inc,
		ra8_dma_complete_fn_t	on_complete,
		void *	ctx )

static

Definition at line 80 of file ra8_sci_dma_isr.c.

References ra8_dma_request_t::count, ra8_dma_request_t::ctx, ra8_dma_request_t::dst_addr, ra8_dma_request_t::dst_inc, k_ra8_dmac_width_byte, ra8_dma_request_t::on_complete, RA8_INTERNAL, ra8_dma_request_t::src_addr, ra8_dma_request_t::src_inc, ra8_dma_request_t::trigger, and ra8_dma_request_t::width.

Referenced by ra8_sci_read_dma(), and ra8_sci_write_dma().

◆ ra8_sci_dispatch_eri()

void ra8_sci_dispatch_eri ( uint8_t channel )

ERI dispatch – clear SSR error flags, invoke optional error callback (none in reserved for 3.1b).

Parameters

[in] channel SCI channel whose ERI fired.

Precondition: Called from ISR context.

Postcondition: SSR error bits are cleared.

Since: 0.1.0

See implementation for details.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 259 of file ra8_sci_dma_isr.c.

References k_ra8_sci_channel_max_index, and ra8_sci_clear_errors().

Referenced by uart_irq_tei_isr().

◆ ra8_sci_dispatch_rxi()

void ra8_sci_dispatch_rxi ( uint8_t channel )

RXI dispatch – hand a received byte to the RX callback.

Parameters

[in] channel SCI channel whose RXI fired.

Precondition: Called from ISR context.

Postcondition: If an RX callback is attached, it has been invoked with the byte read from RDR.

Since: 0.1.0

See implementation for details.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 219 of file ra8_sci_dma_isr.c.

References r_sci_regs_t::CCR0, k_ra8_sci_ccr0_bit_rie, k_ra8_sci_channel_max_index, k_ra8_sci_rdr_mask_data8, ra8_sci(), r_sci_regs_t::RDR, and s_sci_state.

Referenced by uart_irq_rxi_isr().

◆ ra8_sci_dispatch_txi()

void ra8_sci_dispatch_txi ( uint8_t channel )

TXI dispatch – advance the TX callback.

Parameters

[in] channel SCI channel whose TXI fired.

Precondition: Called from ISR context (or from test helper).

Postcondition: If the attached TX callback returns true, the next byte has been written to TDR. Otherwise TIE is cleared.

Since: 0.1.0

See implementation for details.

Precondition: Module has been initialized.

Postcondition: Side effects bounded to documented state.

Note: Not thread-safe unless documented otherwise.

Definition at line 163 of file ra8_sci_dma_isr.c.

References r_sci_regs_t::CCR0, k_ra8_sci_ccr0_bit_tie, k_ra8_sci_channel_max_index, ra8_sci(), s_sci_state, and r_sci_regs_t::TDR.

Referenced by uart_irq_txi_isr().

◆ ra8_sci_read_dma()

ra8_err_t ra8_sci_read_dma	(	uint8_t	channel,
		uint8_t *	out_buf,
		uint16_t	len,
		ra8_dma_complete_fn_t	on_complete,
		void *	ctx,
		uint8_t *	out_dma_channel )

nodiscard

Kick off a DMA-backed RX transfer.

Programmes the ra8_dma substrate to copy len bytes from the channel's RDR register into out_buf[] as byte elements (src_inc=false, dst_inc=true). Completion callback fires from DMAC ISR context on transfer-end.

Parameters

[in]	channel	SCI channel 0..9.
[out]	out_buf	Destination byte buffer. Must stay live until on_complete fires.
[in]	len	Number of bytes; must be non-zero.
[in]	on_complete	Completion callback. May be NULL.
[in]	ctx	Context passed to on_complete.
[out]	out_dma_channel	Allocated DMAC channel on success.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer armed.
k_ra8_err_null_ptr	out_buf or out_dma_channel NULL.
k_ra8_err_invalid_arg	channel > 9 or len zero.
k_ra8_err_no_mem	All DMAC channels in use.
k_ra8_err_hw_error	Underlying ra8_dma_request failed.

Precondition: Channel previously initialized via ra8_sci_init.; ra8_dma_init has been called.; out_buf and out_dma_channel are non-NULL.

Postcondition: On success, the DMAC channel is programmed and armed.; *out_dma_channel holds a valid DMAC channel index.

Note: Thread safety: not thread-safe.

See also: ra8_sci_write_dma; ra8_dma_release

Since: 0.1.0

Definition at line 134 of file ra8_sci_dma_isr.c.

References internal_dma_args_ok(), internal_make_dma_request(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dma_request(), ra8_sci(), r_sci_regs_t::RDR, and s_tag.

◆ ra8_sci_write_dma()

ra8_err_t ra8_sci_write_dma	(	uint8_t	channel,
		const uint8_t *	data,
		uint16_t	len,
		ra8_dma_complete_fn_t	on_complete,
		void *	ctx,
		uint8_t *	out_dma_channel )

nodiscard

Kick off a DMA-backed TX transfer.

Programmes the ra8_dma substrate to copy len bytes from data[] into the channel's TDR register as byte elements (src_inc=true, dst_inc=false). The caller-supplied completion callback fires from DMAC ISR context on transfer-end. The allocated DMAC channel is returned in *out_dma_channel so the caller can release it via ra8_dma_release once the transfer is done.

Uses k_ra8_elc_event_none (software-start). Real hardware one-element-per-TXI routing is a task alongside the TrustZone retrofit.

Parameters

[in]	channel	SCI channel 0..9.
[in]	data	Source byte buffer. Must stay live until on_complete fires.
[in]	len	Number of bytes to transfer; must be non-zero.
[in]	on_complete	Completion callback. May be NULL.
[in]	ctx	Context passed to on_complete.
[out]	out_dma_channel	Allocated DMAC channel on success.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Transfer armed.
k_ra8_err_null_ptr	data or out_dma_channel NULL.
k_ra8_err_invalid_arg	channel > 9 or len zero.
k_ra8_err_no_mem	All DMAC channels in use.
k_ra8_err_hw_error	Underlying ra8_dma_request failed.

Precondition: Channel previously initialized via ra8_sci_init.; ra8_dma_init has been called.; out_dma_channel is non-NULL.

Postcondition: On success, the DMAC channel is programmed and armed.; *out_dma_channel holds a valid DMAC channel index.

Note: Thread safety: not thread-safe.

See also: ra8_sci_read_dma; ra8_dma_release

Since: 0.1.0

Definition at line 104 of file ra8_sci_dma_isr.c.

References internal_dma_args_ok(), internal_make_dma_request(), k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dma_request(), ra8_sci(), s_tag, and r_sci_regs_t::TDR.

Variable Documentation

◆ s_tag

const char* s_tag = "SCI"

static

Definition at line 38 of file ra8_sci_dma_isr.c.

Functions

Variables

Detailed Description

Function Documentation

◆ internal_dma_args_ok()

◆ internal_make_dma_request()

◆ ra8_sci_dispatch_eri()

◆ ra8_sci_dispatch_rxi()

◆ ra8_sci_dispatch_txi()

◆ ra8_sci_read_dma()

◆ ra8_sci_write_dma()

Variable Documentation

◆ s_tag