RA Flexible Software Package Documentation  Release v5.3.0

 
Transfer (r_dtc)

Functions

fsp_err_t R_DTC_Open (transfer_ctrl_t *const p_api_ctrl, transfer_cfg_t const *const p_cfg)
 
fsp_err_t R_DTC_Reconfigure (transfer_ctrl_t *const p_api_ctrl, transfer_info_t *p_info)
 
fsp_err_t R_DTC_Reset (transfer_ctrl_t *const p_api_ctrl, void const *volatile p_src, void *volatile p_dest, uint16_t const num_transfers)
 
fsp_err_t R_DTC_SoftwareStart (transfer_ctrl_t *const p_api_ctrl, transfer_start_mode_t mode)
 
fsp_err_t R_DTC_SoftwareStop (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DTC_Enable (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DTC_Disable (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DTC_InfoGet (transfer_ctrl_t *const p_api_ctrl, transfer_properties_t *const p_properties)
 
fsp_err_t R_DTC_Reload (transfer_ctrl_t *const p_api_ctrl, void const *p_src, void *p_dest, uint32_t const num_transfers)
 
fsp_err_t R_DTC_CallbackSet (transfer_ctrl_t *const p_api_ctrl, void(*p_callback)(transfer_callback_args_t *), void const *const p_context, transfer_callback_args_t *const p_callback_memory)
 
fsp_err_t R_DTC_Close (transfer_ctrl_t *const p_api_ctrl)
 

Detailed Description

Driver for the DTC peripheral on RA MCUs. This module implements the Transfer Interface.

Overview

The Data Transfer Controller (DTC) transfers data from one memory location to another without using the CPU.

The DTC uses a RAM based vector table. Each entry in the vector table corresponds to an entry in the ISR vector table. When the DTC is triggered by an interrupt, it reads the DTC vector table, fetches the transfer information, and then executes the transfer. After the transfer is executed, the DTC writes the updated transfer info back to the location pointed to by the DTC vector table.

Features

Configuration

Build Time Configurations for r_dtc

The following build time configurations are defined in fsp_cfg/r_dtc_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.
Linker section to keep DTC vector tableManual Entry.fsp_dtc_vector_table Section to place the DTC vector table.

Configurations for Transfer > Transfer (r_dtc)

This module can be added to the Stacks tab via New Stack > Transfer > Transfer (r_dtc).

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_transfer0 Module name.
Mode
  • Normal
  • Repeat
  • Block
Normal Select the transfer mode. Select the transfer mode. Normal: One transfer per activation, transfer ends after Number of Transfers; Repeat: One transfer per activation, Repeat Area address reset after Number of Transfers, transfer repeats until stopped; Block: Number of Blocks per activation, Repeat Area address reset after Number of Transfers, transfer ends after Number of Blocks.
Transfer Size
  • 1 Byte
  • 2 Bytes
  • 4 Bytes
2 Bytes Select the transfer size.
Destination Address Mode
  • Fixed
  • Incremented
  • Decremented
Fixed Select the address mode for the destination.
Source Address Mode
  • Fixed
  • Incremented
  • Decremented
Fixed Select the address mode for the source.
Repeat Area (Unused in Normal Mode)
  • Destination
  • Source
Source Select the repeat area. Either the source or destination address resets to its initial value after completing Number of Transfers in Repeat or Block mode.
Interrupt Frequency
  • After all transfers have completed
  • After each transfer
After all transfers have completed Select to have interrupt after each transfer or after last transfer.
Number of TransfersValue must be a non-negative integer0 Specify the number of transfers.
Number of Blocks (Valid only in Block Mode)Must be a valid non-negative integer with a maximum configurable value of 65536. Applicable only in Block Mode.0 Specify the number of blocks to transfer in Block mode.
Number of Transfer DescriptorsValue must be a non-negative integer1 Specify the number of transfer descriptors. Users have to initialize descriptors if its value is greater than 1.
Activation SourceMCU Specific OptionsSelect the DTC transfer start event.

Clock Configuration

The DTC peripheral module uses ICLK as the clock source. The ICLK frequency is set by using the Clocks tab of the RA Configuration editor prior to a build or by using the CGC module at runtime.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Source and Destination Configuration

R_DTC_Reset() API function should be called to set the Source and Destination address before starting the transfer operation.

Transfer Modes

The DTC Module supports three modes of operation.

Note
1. The source and destination address of the transfer must be aligned to the configured data unit.
2. In normal mode the length can be set to [0,65535]. When the length is set to 0, than the transaction will execute 65536 transfers not 0.
3. In block mode, num_blocks can be set to [0,65535]. When the length is set to 0, than the transaction will execute 65536 transfers not 0.

Chaining Transfers

Multiple transfers can be configured for the same interrupt source by specifying an array of transfer_info_t structs instead of just passing a pointer to one. In this configuration, every transfer_info_t struct must be configured for a chain mode except for the last one. There are two types of chain mode; CHAIN_MODE_EACH and CHAIN_MODE_END. If a transfer is configured in CHAIN_MODE_EACH then it triggers the next transfer in the chain after it completes each transfer. If a transfer is configured in CHAIN_MODE_END then it triggers the next transfer in the chain after it completes its last transfer.

r_dtc_flowchart.svg
DTC Transfer Flowchart

Selecting the DTC or DMAC

The Transfer API is implemented by both DTC and the DMAC so that applications can switch between the DTC and the DMAC. When selecting between them, consider these factors:

DTC DMAC
Repeat Mode
  • Repeats forever
  • Max repeat size is 256 x 4 bytes
  • Configurable number of repeats
  • Max repeat size is 1024 x 4 bytes
Block Mode
  • Max block size is 256 x 4 bytes
  • Max block size is 1024 x 4 bytes
Channels
  • One instance per interrupt
  • MCU specific (8 channels or less)
Chained Transfers
  • Supported
  • Not Supported
Software Trigger
  • Must use the software ELC event
  • Has support for software trigger without using software ELC event
  • Supports TRANSFER_START_MODE_SINGLE and TRANSFER_START_MODE_REPEAT
Offset Address Mode
  • Not supported
  • Supported

Additional Considerations

Interrupts

The DTC and DMAC interrupts behave differently. The DTC uses the configured event IRQ as the interrupt source whereas each DMAC channel has its own IRQ.

The transfer_info_t::irq setting also behaves a little differently depending on which mode is selected.

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each transfer N/A
TRANSFER_IRQ_END Interrupt after last transfer Interrupt after last transfer
DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each transfer Interrupt after each repeat
TRANSFER_IRQ_END Interrupt after each repeat Interrupt after last transfer
DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each block Interrupt after each block
TRANSFER_IRQ_END Interrupt after last block Interrupt after last block
Note
DTC_VECTOR_TABLE_SIZE = (ICU_NVIC_IRQ_SOURCES x 4) Bytes

Peripheral Interrupts and DTC

When an interrupt is configured to trigger DTC transfers, the peripheral ISR will trigger on the following conditions:

For example, if SCI1_RXI is configured to trigger DTC transfers and a SCI1_RXI event occurs, the interrupt will not fire until the DTC transfer is completed. If the DTC transfer_info_t::irq is configured to only interrupt on the last transfer, then no RXI interrupts will occur until the last transfer is completed.

Note
1. The DTC activation source must be enabled in the NVIC in order to trigger DTC transfers (Modules that are designed to integrate the R_DTC module will automatically handle this).
2. The DTC prioritizes activation sources by granting the smaller interrupt vector numbers higher priority. The priority of interrupts to the CPU is determined by the NVIC priority.

Low Power Modes

DTCST must be set to 0 before transitioning to any of the following:

Note
1. R_LPM Module stops the DTC before entering deep software standby mode and software standby without snooze mode transition.
2. For more information see 18.9 and 18.10 in the RA6M3 manual R01UH0886EJ0100.

Limitations

Developers should be aware of the following limitations when using the DTC:

Examples

Basic Example

This is a basic example of minimal use of the DTC in an application.

void dtc_minimal_example (void)
{
/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DTC_Open(&g_transfer_ctrl, &g_transfer_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Enable the DTC to handle incoming transfer requests. */
err = R_DTC_Enable(&g_transfer_ctrl);
assert(FSP_SUCCESS == err);
}

Data Structures

struct  dtc_extended_cfg_t
 
struct  dtc_instance_ctrl_t
 

Macros

#define DTC_MAX_NORMAL_TRANSFER_LENGTH
 
#define DTC_MAX_REPEAT_TRANSFER_LENGTH
 
#define DTC_MAX_BLOCK_TRANSFER_LENGTH
 
#define DTC_MAX_BLOCK_COUNT
 

Data Structure Documentation

◆ dtc_extended_cfg_t

struct dtc_extended_cfg_t

DTC transfer configuration extension. This extension is required.

Data Fields
IRQn_Type activation_source

Select which IRQ will trigger the transfer.

◆ dtc_instance_ctrl_t

struct dtc_instance_ctrl_t

Control block used by driver. DO NOT INITIALIZE - this structure will be initialized in transfer_api_t::open.

Macro Definition Documentation

◆ DTC_MAX_NORMAL_TRANSFER_LENGTH

#define DTC_MAX_NORMAL_TRANSFER_LENGTH

Max configurable number of transfers in NORMAL MODE

◆ DTC_MAX_REPEAT_TRANSFER_LENGTH

#define DTC_MAX_REPEAT_TRANSFER_LENGTH

Max number of transfers per repeat for REPEAT MODE

◆ DTC_MAX_BLOCK_TRANSFER_LENGTH

#define DTC_MAX_BLOCK_TRANSFER_LENGTH

Max number of transfers per block in BLOCK MODE

◆ DTC_MAX_BLOCK_COUNT

#define DTC_MAX_BLOCK_COUNT

Max configurable number of blocks to transfer in BLOCK MODE

Function Documentation

◆ R_DTC_Open()

fsp_err_t R_DTC_Open ( transfer_ctrl_t *const  p_api_ctrl,
transfer_cfg_t const *const  p_cfg 
)

Configure the vector table if it hasn't been configured, enable the Module and copy the pointer to the transfer info into the DTC vector table. Implements transfer_api_t::open.

Example:

/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DTC_Open(&g_transfer_ctrl, &g_transfer_cfg);
Return values
FSP_SUCCESSSuccessful open. Transfer transfer info pointer copied to DTC Vector table. Module started. DTC vector table configured.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_UNSUPPORTEDAddress Mode Offset is selected.
FSP_ERR_ALREADY_OPENThe control structure is already opened.
FSP_ERR_IN_USEThe index for this IRQ in the DTC vector table is already configured.
FSP_ERR_IRQ_BSP_DISABLEDThe IRQ associated with the activation source is not enabled in the BSP.

◆ R_DTC_Reconfigure()

fsp_err_t R_DTC_Reconfigure ( transfer_ctrl_t *const  p_api_ctrl,
transfer_info_t p_info 
)

Copy pointer to transfer info into the DTC vector table and enable transfer in ICU. Implements transfer_api_t::reconfigure.

Return values
FSP_SUCCESSTransfer is configured and will start when trigger occurs.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DTC_Open to initialize the control block.
FSP_ERR_NOT_ENABLEDTransfer source address is NULL or is not aligned correctly. Transfer destination address is NULL or is not aligned correctly.
Note
p_info must persist until all transfers are completed.

◆ R_DTC_Reset()

fsp_err_t R_DTC_Reset ( transfer_ctrl_t *const  p_api_ctrl,
void const *volatile  p_src,
void *volatile  p_dest,
uint16_t const  num_transfers 
)

Reset transfer source, destination, and number of transfers. Implements transfer_api_t::reset.

Return values
FSP_SUCCESSTransfer reset successfully (transfers are enabled).
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DTC_Open to initialize the control block.
FSP_ERR_NOT_ENABLEDTransfer source address is NULL or is not aligned correctly. Transfer destination address is NULL or is not aligned correctly.

◆ R_DTC_SoftwareStart()

fsp_err_t R_DTC_SoftwareStart ( transfer_ctrl_t *const  p_api_ctrl,
transfer_start_mode_t  mode 
)

Placeholder for unsupported softwareStart function. Implements transfer_api_t::softwareStart.

Return values
FSP_ERR_UNSUPPORTEDDTC software start is not supported.

◆ R_DTC_SoftwareStop()

fsp_err_t R_DTC_SoftwareStop ( transfer_ctrl_t *const  p_api_ctrl)

Placeholder for unsupported softwareStop function. Implements transfer_api_t::softwareStop.

Return values
FSP_ERR_UNSUPPORTEDDTC software stop is not supported.

◆ R_DTC_Enable()

fsp_err_t R_DTC_Enable ( transfer_ctrl_t *const  p_api_ctrl)

Enable transfers on this activation source. Implements transfer_api_t::enable.

Example:

/* Enable the DTC to handle incoming transfer requests. */
err = R_DTC_Enable(&g_transfer_ctrl);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSTransfers will be triggered by the activation source
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_UNSUPPORTEDAddress Mode Offset is selected.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DTC_Open to initialize the control block.

◆ R_DTC_Disable()

fsp_err_t R_DTC_Disable ( transfer_ctrl_t *const  p_api_ctrl)

Disable transfer on this activation source. Implements transfer_api_t::disable.

Return values
FSP_SUCCESSTransfers will not occur on activation events.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DTC_Open to initialize the control block.
FSP_ERR_ASSERTIONAn input parameter is invalid.

◆ R_DTC_InfoGet()

fsp_err_t R_DTC_InfoGet ( transfer_ctrl_t *const  p_api_ctrl,
transfer_properties_t *const  p_properties 
)

Provides information about this transfer. Implements transfer_api_t::infoGet.

Return values
FSP_SUCCESSp_info updated with current instance information.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DTC_Open to initialize the control block.
FSP_ERR_ASSERTIONAn input parameter is invalid.

◆ R_DTC_Reload()

fsp_err_t R_DTC_Reload ( transfer_ctrl_t *const  p_api_ctrl,
void const *  p_src,
void *  p_dest,
uint32_t const  num_transfers 
)

To update next transfer information without interruption during transfer.

Return values
FSP_ERR_UNSUPPORTEDThis feature is not supported.

◆ R_DTC_CallbackSet()

fsp_err_t R_DTC_CallbackSet ( transfer_ctrl_t *const  p_api_ctrl,
void(*)(transfer_callback_args_t *)  p_callback,
void const *const  p_context,
transfer_callback_args_t *const  p_callback_memory 
)

Placeholder for unsupported callbackset function. Implements transfer_api_t::callbackSet.

Return values
FSP_ERR_UNSUPPORTEDDTC does not support direct callbacks.

◆ R_DTC_Close()

fsp_err_t R_DTC_Close ( transfer_ctrl_t *const  p_api_ctrl)

Disables DTC activation in the ICU, then clears transfer data from the DTC vector table. Implements transfer_api_t::close.

Return values
FSP_SUCCESSSuccessful close.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DTC_Open to initialize the control block.