ra8-firmware 0.1.0
Bare-metal firmware for the Renesas RA8 family (RA8D2 / RA8P1)
Loading...
Searching...
No Matches
ra8_dtc.c File Reference

Data Transfer Controller driver implementation. More...

#include "ra8_dtc.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_cache.h"
#include "ra8_check.h"
#include "ra8_dtc_regs.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_mstp.h"
Include dependency graph for ra8_dtc.c:

Go to the source code of this file.

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.

Variables

static const char * s_tag = "DTC"
static ra8_dtc_event_fn_t s_dtc_fn
static void * s_dtc_ctx
static void * s_dtc_vector_base

Detailed Description

Data Transfer Controller driver implementation.

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

Driver for the RA8D2 DTC block. Every register access carries a HUM Ch 18 citation. Shares MSTPA22 with DMAC0 via ra8_mstp's reference counter (HUM 11.2.6 Note 1).

FSP-mapping (r_dtc.c): FSP entry-point | This driver --------------------—+-----------------------— R_DTC_Open | ra8_dtc_init (programmes DTCVBR + MSTP) R_DTC_Close | ra8_dtc_deinit R_DTC_Enable | ra8_dtc_enable (DTCST = 1) R_DTC_Disable | ra8_dtc_disable (DTCST = 0) R_DTC_Reconfigure | ra8_dtc_reconfigure R_DTC_Reset | (call sites edit TI directly + RRS toggle) R_DTC_InfoGet | (call sites read TI fields directly) R_DTC_Reload | unsupported (FSP returns FSP_ERR_UNSUPPORTED) R_DTC_CallbackSet | ra8_dtc_attach_handler (status-bit fan-out) R_DTC_SoftwareStart | unsupported (DTC has no SW trigger) R_DTC_SoftwareStop | unsupported (DTC has no SW trigger)

RRS write-skip handling matches FSP literally: bit 3 of DTCCR is documented as "reserved -- write 1, read 1" (HUM 18.2.1 p 786), so the RRS-disable / RRS-enable values are 0x08 / 0x18 not 0x00 / 0x10.

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

Definition in file ra8_dtc.c.

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_basePointer 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_baseNew 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.

Variable Documentation

◆ s_dtc_ctx

void* s_dtc_ctx
static

Definition at line 52 of file ra8_dtc.c.

Referenced by ra8_dtc_attach_handler(), ra8_dtc_deinit(), and ra8_dtc_dispatch().

◆ s_dtc_fn

ra8_dtc_event_fn_t s_dtc_fn
static

Definition at line 51 of file ra8_dtc.c.

Referenced by ra8_dtc_attach_handler(), ra8_dtc_deinit(), and ra8_dtc_dispatch().

◆ s_dtc_vector_base

void* s_dtc_vector_base
static

Definition at line 58 of file ra8_dtc.c.

Referenced by ra8_dtc_deinit(), ra8_dtc_enable(), ra8_dtc_init(), and ra8_dtc_reconfigure().

◆ s_tag

const char* s_tag = "DTC"
static

Definition at line 49 of file ra8_dtc.c.