RA Flexible Software Package Documentation  Release v5.1.0

 
Transfer (r_dmac)

Functions

fsp_err_t R_DMAC_Open (transfer_ctrl_t *const p_api_ctrl, transfer_cfg_t const *const p_cfg)
 
fsp_err_t R_DMAC_Reconfigure (transfer_ctrl_t *const p_api_ctrl, transfer_info_t *p_info)
 
fsp_err_t R_DMAC_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_DMAC_SoftwareStart (transfer_ctrl_t *const p_api_ctrl, transfer_start_mode_t mode)
 
fsp_err_t R_DMAC_SoftwareStop (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_Enable (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_Disable (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_InfoGet (transfer_ctrl_t *const p_api_ctrl, transfer_properties_t *const p_info)
 
fsp_err_t R_DMAC_Reload (transfer_ctrl_t *const p_api_ctrl, void const *p_src, void *p_dest, uint32_t const num_transfers)
 
fsp_err_t R_DMAC_Close (transfer_ctrl_t *const p_api_ctrl)
 

Detailed Description

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

Overview

The Direct Memory Access Controller (DMAC) transfers data from one memory location to another without using the CPU.

Features

Configuration

Build Time Configurations for r_dmac

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

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.

Configurations for Transfer > Transfer (r_dmac)

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

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_transfer0 Module name.
ChannelValue must be a non-negative integer0 Specify the hardware channel.
ModeMCU Specific OptionsSelect 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 ends after Number of Blocks; 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
  • Offset addition
  • Incremented
  • Decremented
Fixed Select the address mode for the destination.
Source Address Mode
  • Fixed
  • Offset addition
  • 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.
Destination PointerManual EntryNULL Specify the transfer destination pointer.
Source PointerManual EntryNULL Specify the transfer source pointer.
Number of TransfersValue must be a non-negative integer1 Specify the number of transfers for repeat and normal mode or block size for repeat-block transfer mode.
Number of Blocks (Valid only in Repeat,Block or Repeat-Block Mode)Value must be a non-negative integer0 Specify the number of blocks to transfer in Repeat,Block or Repeat-Block mode.
Activation SourceMCU Specific OptionsSelect the DMAC transfer start event. If no ELC event is chosen then software start can be used.
CallbackName must be a valid C symbolNULL A user callback that is called at the end of the transfer.
ContextManual EntryNULL Pointer to the context structure passed through the callback argument.
Transfer End Interrupt PriorityMCU Specific OptionsSelect the transfer end interrupt priority.
Interrupt Frequency
  • Interrupt after all transfers have completed
  • Interrupt after each block, or repeat size is transfered
Interrupt after all transfers have completed Select to have interrupt after each transfer or after last transfer.
Offset value (Valid only when address mode is \'Offset\')Value must be a 24 bit signed integer.1 Offset value is added to the address after each transfer.
Source Buffer SizeValue must be a non-negative integer with a maximum configurable value of 65535.1 Specify the size of whole source buffer (valid only for Repeat-Block transfer mode with source address update mode other than offset addition).

Clock Configuration

The DMAC 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 run-time.

Pin Configuration

This module does not use I/O pins.

Usage Notes

Transfer Modes

The DMAC Module supports three modes of operation.

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

Interrupts

The DTC and DMAC interrupts behave differently. The DTC uses the configured IELSR 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.

Normal Mode

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each transfer N/A
TRANSFER_IRQ_END Interrupt after last transfer Interrupt after last transfer

Repeat Mode

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each transfer Interrupt after each repeat
TRANSFER_IRQ_END Interrupt after each repeat Interrupt after last transfer

Block Mode

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each block Interrupt after each block
TRANSFER_IRQ_END Interrupt after last block Interrupt after last block

Repeat-block Mode

DTC DMAC
TRANSFER_IRQ_EACH N/A N/A
TRANSFER_IRQ_END N/A Interrupt after last block

Additional Considerations

Offset Address Mode

When the source or destination mode is configured to offset mode, a configurable offset is added to the source or destination pointer after each transfer. The offset is a signed 24 bit number.

Examples

Basic Example

This is a basic example of minimal use of the DMAC in an application. In this case, one or more events have been routed to the DMAC for handling so it only needs to be enabled to start accepting transfers.

void dmac_minimal_example (void)
{
/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DMAC_Open(&g_transfer_ctrl, &g_transfer_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Enable the DMAC so that it responds to transfer requests. */
err = R_DMAC_Enable(&g_transfer_ctrl);
assert(FSP_SUCCESS == err);
}

CRC32 Example

In this example the DMAC is used to feed the CRC peripheral to perform a CRC32 operation.

volatile bool g_transfer_complete = false;
void dmac_callback (dmac_callback_args_t * cb_data)
{
g_transfer_complete = true;
}
void dmac_crc_example (void)
{
uint8_t p_src[TRANSFER_LENGTH];
/* Initialize p_src to [ABC..OP] */
for (uint32_t i = 0; i < TRANSFER_LENGTH; i++)
{
p_src[i] = (uint8_t) ('A' + (i % 26));
}
/* Set transfer source address to p_src */
g_transfer_cfg.p_info->p_src = (void *) p_src;
/* Set transfer destination address to the CRC data input register */
g_transfer_cfg.p_info->p_dest = (void *) &R_CRC->CRCDIR;
/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DMAC_Open(&g_transfer_ctrl, &g_transfer_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Enable DMAC transfers. */
(void) R_DMAC_Enable(&g_transfer_ctrl);
/* Open the CRC module. */
err = R_CRC_Open(&g_crc_ctrl, &g_crc_cfg);
assert(FSP_SUCCESS == err);
/* Clear the transfer complete flag. */
g_transfer_complete = false;
/* Trigger the transfer using software. */
assert(FSP_SUCCESS == err);
while (!g_transfer_complete)
{
/* Wait for transfer complete interrupt */
}
/* Get CRC result and perform final XOR. */
uint32_t crc32;
(void) R_CRC_CalculatedValueGet(&g_crc_ctrl, &crc32);
crc32 ^= CRC32_FINAL_XOR_VALUE;
/* Verify that the CRC32 is calculated correctly. */
/* CRC32("ABCD...NOP") = 0xE0E8FF4D. */
const uint32_t expected_crc32 = 0xE0E8FF4D;
if (expected_crc32 != crc32)
{
/* Handle any CRC errors. This function should be defined by the user. */
handle_crc_error();
}
}

Data Structures

struct  dmac_instance_ctrl_t
 
struct  dmac_callback_args_t
 
struct  dmac_extended_cfg_t
 

Macros

#define DMAC_MAX_NORMAL_TRANSFER_LENGTH
 
#define DMAC_MAX_REPEAT_TRANSFER_LENGTH
 
#define DMAC_MAX_BLOCK_TRANSFER_LENGTH
 
#define DMAC_MAX_REPEAT_COUNT
 
#define DMAC_MAX_BLOCK_COUNT
 

Data Structure Documentation

◆ dmac_instance_ctrl_t

struct dmac_instance_ctrl_t

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

◆ dmac_callback_args_t

struct dmac_callback_args_t

Callback function parameter data.

Data Fields
void const * p_context Placeholder for user data. Set in r_transfer_t::open function in transfer_cfg_t.

◆ dmac_extended_cfg_t

struct dmac_extended_cfg_t

DMAC transfer configuration extension. This extension is required.

Data Fields

uint8_t channel
 Channel number, does not apply to all HAL drivers.
 
IRQn_Type irq
 DMAC interrupt number.
 
uint8_t ipl
 DMAC interrupt priority.
 
int32_t offset
 Offset value used with transfer_addr_mode_t::TRANSFER_ADDR_MODE_OFFSET.
 
uint16_t src_buffer_size
 
elc_event_t activation_source
 
void(* p_callback )(dmac_callback_args_t *cb_data)
 
void const * p_context
 

Field Documentation

◆ src_buffer_size

uint16_t dmac_extended_cfg_t::src_buffer_size

Source ring buffer size for TRANSFER_MODE_REPEAT_BLOCK.

◆ activation_source

elc_event_t dmac_extended_cfg_t::activation_source

Select which event will trigger the transfer.

Note
Select ELC_EVENT_NONE for software activation in order to use softwareStart and softwareStart to trigger transfers.

◆ p_callback

void(* dmac_extended_cfg_t::p_callback) (dmac_callback_args_t *cb_data)

Callback for transfer end interrupt.

◆ p_context

void const* dmac_extended_cfg_t::p_context

Placeholder for user data. Passed to the user p_callback in dmac_callback_args_t.

Macro Definition Documentation

◆ DMAC_MAX_NORMAL_TRANSFER_LENGTH

#define DMAC_MAX_NORMAL_TRANSFER_LENGTH

Max configurable number of transfers in TRANSFER_MODE_NORMAL.

◆ DMAC_MAX_REPEAT_TRANSFER_LENGTH

#define DMAC_MAX_REPEAT_TRANSFER_LENGTH

Max number of transfers per repeat for TRANSFER_MODE_REPEAT.

◆ DMAC_MAX_BLOCK_TRANSFER_LENGTH

#define DMAC_MAX_BLOCK_TRANSFER_LENGTH

Max number of transfers per block in TRANSFER_MODE_BLOCK

◆ DMAC_MAX_REPEAT_COUNT

#define DMAC_MAX_REPEAT_COUNT

Max configurable number of repeats to trasnfer in TRANSFER_MODE_REPEAT

◆ DMAC_MAX_BLOCK_COUNT

#define DMAC_MAX_BLOCK_COUNT

Max configurable number of blocks to transfer in TRANSFER_MODE_BLOCK

Function Documentation

◆ R_DMAC_Open()

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

Configure a DMAC channel.

Return values
FSP_SUCCESSSuccessful open.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_IP_CHANNEL_NOT_PRESENTThe configured channel is invalid.
FSP_ERR_IRQ_BSP_DISABLEDThe IRQ associated with the activation source is not enabled in the BSP.
FSP_ERR_ALREADY_OPENThe control structure is already opened.

◆ R_DMAC_Reconfigure()

fsp_err_t R_DMAC_Reconfigure ( transfer_ctrl_t *const  p_api_ctrl,
transfer_info_t p_info 
)

Reconfigure the transfer with new transfer info.

Return values
FSP_SUCCESSTransfer is configured and will start when trigger occurs.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_ENABLEDDMAC is not enabled. The current configuration must not be valid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.

◆ R_DMAC_Reset()

fsp_err_t R_DMAC_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.

Return values
FSP_SUCCESSTransfer reset successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_ENABLEDDMAC is not enabled. The current configuration must not be valid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.

◆ R_DMAC_SoftwareStart()

fsp_err_t R_DMAC_SoftwareStart ( transfer_ctrl_t *const  p_api_ctrl,
transfer_start_mode_t  mode 
)

If the mode is TRANSFER_START_MODE_SINGLE initiate a single transfer with software. If the mode is TRANSFER_START_MODE_REPEAT continue triggering transfers until all of the transfers are completed.

Return values
FSP_SUCCESSTransfer started written successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.
FSP_ERR_UNSUPPORTEDHandle was not configured for software activation.

◆ R_DMAC_SoftwareStop()

fsp_err_t R_DMAC_SoftwareStop ( transfer_ctrl_t *const  p_api_ctrl)

Stop software transfers if they were started with TRANSFER_START_MODE_REPEAT.

Return values
FSP_SUCCESSTransfer stopped written successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.

◆ R_DMAC_Enable()

fsp_err_t R_DMAC_Enable ( transfer_ctrl_t *const  p_api_ctrl)

Enable transfers for the configured activation source.

Return values
FSP_SUCCESSCounter value written successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.

◆ R_DMAC_Disable()

fsp_err_t R_DMAC_Disable ( transfer_ctrl_t *const  p_api_ctrl)

Disable transfers so that they are no longer triggered by the activation source.

Return values
FSP_SUCCESSCounter value written successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.

◆ R_DMAC_InfoGet()

fsp_err_t R_DMAC_InfoGet ( transfer_ctrl_t *const  p_api_ctrl,
transfer_properties_t *const  p_info 
)

Set driver specific information in provided pointer.

Return values
FSP_SUCCESSInformation has been written to p_info.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_Open to initialize the control block.
FSP_ERR_ASSERTIONAn input parameter is invalid.

◆ R_DMAC_Reload()

fsp_err_t R_DMAC_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_DMAC_Close()

fsp_err_t R_DMAC_Close ( transfer_ctrl_t *const  p_api_ctrl)

Disable transfer and clean up internal data. 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_DMAC_Open to initialize the control block.