Data Transfer Controller (DTC) driver. More...

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

Include dependency graph for ra8_dtc.h:

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

Typedefs
typedef void(*	ra8_dtc_event_fn_t) (void *ctx, uint16_t status)
	DTC activation-complete callback.

Functions
ra8_err_t	ra8_dtc_init (void *vector_base)
	Initialise the DTC and install its vector table base.
ra8_err_t	ra8_dtc_deinit (void)
	Tear down the DTC (clears run bit + drops MSTP ref).
ra8_err_t	ra8_dtc_enable (void)
	Start the DTC module.
ra8_err_t	ra8_dtc_disable (void)
	Stop the DTC module.
ra8_err_t	ra8_dtc_reconfigure (void *vector_base)
	Reconfigure the DTC vector base at runtime.
ra8_err_t	ra8_dtc_get_status (uint16_t *out_mask)
	Read the DTCSTS activation status register.
ra8_err_t	ra8_dtc_clear_status (uint16_t mask)
	Clear sticky bits in DTCSTS.
ra8_err_t	ra8_dtc_attach_handler (ra8_dtc_event_fn_t fn, void *ctx)
	Attach a shared activation-complete callback.
void	ra8_dtc_dispatch (void)
	Fire the attached activation callback with current DTCSTS.
ra8_err_t	ra8_dtc_enter_stop (void)
	Put the DTC into MSTP-gated stop.
ra8_err_t	ra8_dtc_exit_stop (void)
	Exit MSTP-gated stop and re-arm the engine.

Detailed Description

Data Transfer Controller (DTC) driver.

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

Driver for the RA8D2 DTC block. The DTC is a lighter-weight alternative to the DMAC for moving small amounts of data in response to peripheral interrupts. It shares the MSTPA22 gate with DMAC0 via ra8_mstp's reference counter. The driver owns the DTCCR / DTCVBR / DTCST / DTCSTS surface and exposes a shared activation-callback slot that the ICU dispatcher forwards DTC completion events into.

FSP transfer-API mapping (see r_dtc.c):

R_DTC_Open -> ra8_dtc_init (programme DTCVBR + MSTP)
R_DTC_Close -> ra8_dtc_deinit
R_DTC_Enable -> ra8_dtc_enable
R_DTC_Disable -> ra8_dtc_disable
R_DTC_Reconfigure -> ra8_dtc_reconfigure
R_DTC_CallbackSet -> ra8_dtc_attach_handler
R_DTC_Reset, _InfoGet: call sites edit the TI table directly.
R_DTC_Reload, _SoftwareStart, _SoftwareStop: not supported (matches FSP FSP_ERR_UNSUPPORTED).

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

Definition in file ra8_dtc.h.

Typedef Documentation

◆ ra8_dtc_event_fn_t

typedef void(* ra8_dtc_event_fn_t) (void *ctx, uint16_t status)

DTC activation-complete callback.

Definition at line 47 of file ra8_dtc.h.

Function Documentation

◆ ra8_dtc_attach_handler()

ra8_err_t ra8_dtc_attach_handler	(	ra8_dtc_event_fn_t	fn,
		void *	ctx )

nodiscard

Attach a shared activation-complete callback.

DTC activation events land on per-source IRQs via the ICU; the ICU dispatcher calls ra8_dtc_dispatch() which fans them out to the handler stored here.

Since: 0.1.0

Definition at line 172 of file ra8_dtc.c.

References k_ra8_ok, s_dtc_ctx, and s_dtc_fn.

Referenced by dtc_arm_bringup_or_halt(), dtc_coh_bringup_or_halt(), and dtc_demo_bringup_or_halt().

◆ ra8_dtc_clear_status()

ra8_err_t ra8_dtc_clear_status ( uint16_t mask )

nodiscard

Clear sticky bits in DTCSTS.

Since: 0.1.0

Definition at line 164 of file ra8_dtc.c.

References r_dtc_regs_t::DTCSTS, k_ra8_ok, and ra8_dtc().

◆ ra8_dtc_deinit()

ra8_err_t ra8_dtc_deinit ( void )

nodiscard

Tear down the DTC (clears run bit + drops MSTP ref).

Since: 0.1.0

Definition at line 89 of file ra8_dtc.c.

References r_dtc_regs_t::DTCCR, r_dtc_regs_t::DTCST, r_dtc_regs_t::DTCVBR, r_dtc_regs_t::DTCVBR_SEC, k_ra8_mstp_dmac0_dtc0, ra8_dtc(), ra8_mstp_disable(), s_dtc_ctx, s_dtc_fn, and s_dtc_vector_base.

◆ ra8_dtc_disable()

ra8_err_t ra8_dtc_disable ( void )

nodiscard

Stop the DTC module.

Since: 0.1.0

Definition at line 124 of file ra8_dtc.c.

References r_dtc_regs_t::DTCST, k_ra8_ok, and ra8_dtc().

◆ ra8_dtc_dispatch()

void ra8_dtc_dispatch ( void )

Fire the attached activation callback with current DTCSTS.

Reads DTC.DTCSTS (HUM Ch 17.2.10 "DTCSTS : DTC Status Register", p 654) which captures the most recent DTC activation source and ACT flag, and invokes the handler registered through ra8_dtc_attach_handler() with that status word and the stored context pointer. Silently returns when no handler is installed.

Precondition: ra8_dtc_init() previously succeeded.; Called from ISR context or unit-test driver.

Postcondition: Registered handler invoked at most once with current DTCSTS.; No DTC register state mutated by the dispatch itself.

Note: Thread safety: ISR context only; not re-entrant.

Since: 0.1.0

Definition at line 180 of file ra8_dtc.c.

References r_dtc_regs_t::DTCSTS, ra8_dtc(), s_dtc_ctx, and s_dtc_fn.

Referenced by dtc_arm_swevt_isr(), dtc_coh_swevt_isr(), and dtc_demo_swevt_isr().

◆ ra8_dtc_enable()

ra8_err_t ra8_dtc_enable ( void )

nodiscard

Start the DTC module.

Since: 0.1.0

Definition at line 104 of file ra8_dtc.c.

References r_dtc_regs_t::DTCST, k_ra8_dtc_vector_table_align, k_ra8_dtcst_dtcst_msk, k_ra8_ok, ra8_cache_dcache_clean_by_addr(), ra8_dtc(), and s_dtc_vector_base.

Referenced by dtc_arm_bringup_or_halt(), dtc_coh_run_once(), and dtc_demo_bringup_or_halt().

◆ ra8_dtc_enter_stop()

ra8_err_t ra8_dtc_enter_stop ( void )

nodiscard

Put the DTC into MSTP-gated stop.

Since: 0.1.0

Definition at line 193 of file ra8_dtc.c.

References r_dtc_regs_t::DTCST, k_ra8_mstp_dmac0_dtc0, ra8_dtc(), and ra8_mstp_disable().

◆ ra8_dtc_exit_stop()

ra8_err_t ra8_dtc_exit_stop ( void )

nodiscard

Exit MSTP-gated stop and re-arm the engine.

Since: 0.1.0

Definition at line 200 of file ra8_dtc.c.

References k_ra8_mstp_dmac0_dtc0, and ra8_mstp_enable().

◆ ra8_dtc_get_status()

ra8_err_t ra8_dtc_get_status ( uint16_t * out_mask )

nodiscard

Read the DTCSTS activation status register.

Since: 0.1.0

Definition at line 156 of file ra8_dtc.c.

References r_dtc_regs_t::DTCSTS, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dtc(), and s_tag.

◆ ra8_dtc_init()

ra8_err_t ra8_dtc_init ( void * vector_base )

nodiscard

Initialise the DTC and install its vector table base.

Parameters

[in] vector_base Pointer to a caller-supplied DTC vector table (16-byte-aligned SRAM region).

Since: 0.1.0

Definition at line 60 of file ra8_dtc.c.

References r_dtc_regs_t::DTCCR, r_dtc_regs_t::DTCST, r_dtc_regs_t::DTCVBR, r_dtc_regs_t::DTCVBR_SEC, k_ra8_mstp_dmac0_dtc0, k_ra8_ok, RA8_CHECK_NULL_PTR, ra8_dtc(), ra8_log_info, ra8_mstp_enable(), RA8_RETURN_ON_ERROR, s_dtc_vector_base, and s_tag.

Referenced by dtc_arm_bringup_or_halt(), dtc_coh_bringup_or_halt(), and dtc_demo_bringup_or_halt().

◆ ra8_dtc_reconfigure()

ra8_err_t ra8_dtc_reconfigure ( void * vector_base )

nodiscard

Reconfigure the DTC vector base at runtime.

Safe only while the DTC is disabled. Rewrites DTCVBR + toggles DTCCR.RRS so that a stale read-skip entry does not outlive the reprogramming.

Parameters

[in] vector_base New vector table base (16-byte-aligned).

Since: 0.1.0

Definition at line 131 of file ra8_dtc.c.

References r_dtc_regs_t::DTCCR, r_dtc_regs_t::DTCST, r_dtc_regs_t::DTCVBR, r_dtc_regs_t::DTCVBR_SEC, k_ra8_dtc_vector_table_align, k_ra8_dtccr_rrs_disable, k_ra8_dtccr_rrs_enable, k_ra8_ok, ra8_cache_dcache_clean_by_addr(), RA8_CHECK_NULL_PTR, ra8_dtc(), s_dtc_vector_base, and s_tag.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ ra8_dtc_event_fn_t

Function Documentation

◆ ra8_dtc_attach_handler()

◆ ra8_dtc_clear_status()

◆ ra8_dtc_deinit()

◆ ra8_dtc_disable()

◆ ra8_dtc_dispatch()

◆ ra8_dtc_enable()

◆ ra8_dtc_enter_stop()

◆ ra8_dtc_exit_stop()

◆ ra8_dtc_get_status()

◆ ra8_dtc_init()

◆ ra8_dtc_reconfigure()