RAFW Flexible Software Package Documentation  Release v2.0.1

 
Transfer (r_dmac_w)

Functions

fsp_err_t R_DMAC_W_Open (transfer_ctrl_t *const p_api_ctrl, transfer_cfg_t const *const p_cfg)
 
fsp_err_t R_DMAC_W_Reconfigure (transfer_ctrl_t *const p_api_ctrl, transfer_info_t *p_info)
 
fsp_err_t R_DMAC_W_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_W_SoftwareStart (transfer_ctrl_t *const p_api_ctrl, transfer_start_mode_t mode)
 
fsp_err_t R_DMAC_W_SoftwareStop (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_W_Enable (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_W_Disable (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_W_InfoGet (transfer_ctrl_t *const p_api_ctrl, transfer_properties_t *const p_info)
 
fsp_err_t R_DMAC_W_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_W_CallbackSet (transfer_ctrl_t *const p_api_ctrl, void(*p_callback)(dmac_callback_args_t *), void *const p_context, dmac_callback_args_t *const p_callback_memory)
 
fsp_err_t R_DMAC_W_Close (transfer_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_DMAC_W_Freeze (bool freeze)
 

Detailed Description

Driver for the DMAC peripheral on RA6W1/RA6W2 MCUs. This module implements the Transfer Interface.

Overview

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

Features

Configuration

Build Time Configurations for r_dmac_w

The following build time configurations are defined in fsp_cfg/r_dmac_w_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_w)

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

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 Size
  • 1 Byte
  • 2 Bytes
  • 4 Bytes
2 Bytes Select the transfer size.
Destination Address Mode
  • Fixed
  • Incremented
Fixed Select the address mode for the destination.
Source Address Mode
  • Fixed
  • Incremented
Fixed Select the address mode for the source.
Number of Transfers'Number of Transfers' must be a valid non negative integer between 1 and 65535.1 Specify the number of transfers for repeat and normal mode.
Number of Transfers to interruptValue must be a non-negative integer0 Specify the number of transfers before DMA interrupt generation (0 to fire IRQ after transfer ends).
Activation SourceMCU Specific OptionsSelect the DMAC transfer start event.
CallbackName must be a valid C symbolNULL A user callback that is called at the end of the transfer.
Transfer End Interrupt PriorityMCU Specific OptionsSelect the transfer end interrupt priority.
Start mode
  • Start immediately
  • On peripheral request
Start immediately Select whether DMA starts immediately, or waits for a trigger from HW.
DMA idle mode
  • Blocking mode
  • Interrupting mode
Blocking mode Select whether DMA blocks the bus during the transfer or allow CPU/cache activities on the bus during the transfer (relevant only for 'Request mode'='Start immediately').
DMA init mode
  • A1 to B1, A2 to B2
  • A1 to B1, B2
A1 to B1, A2 to B2 Select how DMA performs memory initialization (relevant only for 'Request mode'='Start immediately').
DMA read/write bursts
  • Disabled
  • 4-beat
  • 8-beat
Disabled Set the DMA read/write bursts value for DMAC. The bursts are not used if 'Number of Transfers' are not multiple of 4 or 8 respectively.
DMA channel priority'DMA channel priority' must be integer from '0' (Lowest) up to '7' (Highest).0 Select the priority of DMA channel to determine which DMA channel will be activated in case more than one DMA channel requests DMA (0 - Lowest, 7 - Highest).

Clock Configuration

The DMAC peripheral module uses SYS_CLK as the clock source. The SYS_CLK frequency is set by using the Clocks tab of the RA6W1/RA6W2 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 two modes of operation.

DMAC Features

Init Mode

DMAC can perform efficient memory initialization in the case of transfer triggered by the software. It can populate destination buffer with the content of the source buffer using one of the two modes:

DMAC Idle Operation

DMAC can work in a two different operation modes:

DMAC Channel Prioritization

DMAC channel access to the bus can be prioritized. The priority level determines which DMA channel will be granted access for transferring data, in case more than one channels are active and request the bus at the same time. The greater the value, the higher the priority.

Bursts Transfers

DMAC can perform transfer operations with bursts of 4 or 8 data units simultaneously (the buffer length in those cases should be multiple of 4 or 8 data units respectively).

Freezing of DMAC operations

The DMA controller can be frozen. The API call to freeze suspends the activity on every DMA channel until DMAC is unfrozen by the corresponding API call to unfreeze it.

Selecting the DTC or DMAC

The Transfer API is implemented by both DTC (on some MCUs) 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
  • Repeats forever (applicable only for transactions involving peripherals)
  • Max repeat size is 65535 x 4 bytes
Block Mode
  • Max transfer size is 256 x 4 bytes
  • N/A
Normal Mode
  • Max transfer size is 65535 x 4 bytes
  • Max transfer size is 65535 x 4 bytes
Channels
  • One instance per interrupt
  • MCU specific (16 channels or less)
Chained Transfers
  • Supported
  • Not Supported
Software Trigger
  • Must use the software ELC event
  • Has support of software trigger without peripheral HW involvement
  • Supports only TRANSFER_START_MODE_SINGLE

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 (one IRQn is shared between channels on some MCUs).

The transfer_info_t::irq is not used on DMAC, as DMAC provides more flexible way of interrupt generation depending on the transfer operation counter.

Additional Considerations

Normal Mode

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each transfer N/A (has IRQ generation based on transfer counter)
TRANSFER_IRQ_END Interrupt after last transfer N/A (has IRQ generation based on transfer counter)

Repeat Mode

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each transfer N/A (has IRQ generation based on transfer counter)
TRANSFER_IRQ_END Interrupt after each repeat N/A (has IRQ generation based on transfer counter)

Block Mode

DTC DMAC
TRANSFER_IRQ_EACH Interrupt after each block N/A (has IRQ generation based on transfer counter)
TRANSFER_IRQ_END Interrupt after last block N/A (has IRQ generation based on transfer counter)
Note
DTC_VECTOR_TABLE_SIZE = (ICU_NVIC_IRQ_SOURCES x 4) Bytes

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.

#include "r_dmac_w.h"
#pragma GCC diagnostic ignored "-Wunused-variable"
#pragma GCC diagnostic ignored "-Wunused-but-set-variable"
/***********************************************************************************************************************
* Macro definitions
**********************************************************************************************************************/
#define TRANSFER_LENGTH (16U)
#define BSP_VECTOR_DMAC_0 ((IRQn_Type) 0)
/***********************************************************************************************************************
* Typedef definitions
**********************************************************************************************************************/
/***********************************************************************************************************************
* Private function prototypes
**********************************************************************************************************************/
int dmac_main(void);
void dmac_minimal_example(void);
void dmac_freeze_example(void);
void dmac_callback(dmac_callback_args_t * cb_data);
/***********************************************************************************************************************
* Private global variables
**********************************************************************************************************************/
dmac_instance_ctrl_t g_transfer_ctrl;
volatile bool g_transfer_complete = false;
/* Transfer info that tests can use when configuring a transfer instance. */
transfer_info_t transfer_info =
{
.transfer_settings_word_b.dest_addr_mode = TRANSFER_ADDR_MODE_INCREMENTED,
.transfer_settings_word_b.src_addr_mode = TRANSFER_ADDR_MODE_INCREMENTED,
.length = TRANSFER_LENGTH / 4,
.transfer_settings_word_b.size = TRANSFER_SIZE_4_BYTE,
.p_dest = NULL,
.p_src = NULL,
.transfer_settings_word_b.mode = TRANSFER_MODE_NORMAL,
};
{
.channel = 0,
.irq = BSP_VECTOR_DMAC_0,
.ipl = 0,
.p_callback = dmac_callback,
};
/* Transfer config that tests can use when configuring a transfer instance. */
transfer_cfg_t g_transfer_cfg =
{
.p_info = &transfer_info,
.p_extend = &dmac_cfg,
};
/***********************************************************************************************************************
* Functions
**********************************************************************************************************************/
void dmac_minimal_example (void)
{
/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DMAC_W_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 to start the trasnfer so that it responds to transfer requests. */
err = R_DMAC_W_Enable(&g_transfer_ctrl);
assert(FSP_SUCCESS == err);
while (!g_transfer_complete)
{
/* Wait for transfer complete interrupt */
}
}
void dmac_freeze_example (void)
{
/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DMAC_W_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 to start the trasnfer so that it responds to transfer requests. */
err = R_DMAC_W_Enable(&g_transfer_ctrl);
assert(FSP_SUCCESS == err);
/* Temporarily disable (freeze) all channels of the DMA controller. */
err = R_DMAC_W_Freeze(true);
assert(FSP_SUCCESS == err);
/* DMAC starts transferring after unfreeze. */
err = R_DMAC_W_Freeze(false);
assert(FSP_SUCCESS == err);
}
void dmac_callback (dmac_callback_args_t * cb_data)
{
g_transfer_complete = true;
}
int dmac_main (void)
{
dmac_minimal_example();
/* Close DMAC channel so can be reused. */
fsp_err_t err = R_DMAC_W_Close(&g_transfer_ctrl);
assert(FSP_SUCCESS == err);
dmac_freeze_example();
return 0;
}

Data Structures

struct  dmac_extended_cfg_t
 

Macros

#define DMAC_MAX_NORMAL_TRANSFER_LENGTH
 

Typedefs

typedef transfer_callback_args_t dmac_callback_args_t
 

Enumerations

enum  dmac_start_mode_t
 
enum  dmac_burst_mode_t
 
enum  dmac_idle_mode_t
 
enum  dmac_init_mode_t
 

Data Structure Documentation

◆ 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.
 
dmac_start_mode_t start_mode
 Start DMA immediately or have it triggered by peripheral.
 
dmac_idle_mode_t idle_mode
 Idle mode: blocking or interrupting.
 
dmac_init_mode_t init_mode
 Copy mode: block copy or mem init.
 
dmac_burst_mode_t burst_mode
 Enable/Disable burst mode.
 
uint8_t channel_prio
 DMAC channel priority.
 
bsp_dmac_trig_t periph_trigger
 Trigger source, if DMAC starts on a peripheral request.
 
uint16_t irq_num_of_trans
 
void(* p_callback )(dmac_callback_args_t *cb_data)
 
void * p_context
 

Field Documentation

◆ irq_num_of_trans

uint16_t dmac_extended_cfg_t::irq_num_of_trans

Number of transfers before IRQ generation. Set to 0 to fire IRQ after transfer ends.

◆ p_callback

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

Callback for transfer end interrupt.

◆ p_context

void* 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.

Typedef Documentation

◆ dmac_callback_args_t

Callback function parameter data.

Enumeration Type Documentation

◆ dmac_start_mode_t

DMAC channel start mode

Enumerator
DMAC_START_IMMEDIATELY 

DMAC channel starts immediately.

DMAC_START_ON_PERIPHERAL_REQUEST 

DMAC channel must be triggered by a peripheral DMA request.

◆ dmac_burst_mode_t

DMAC channel burst mode

Enumerator
DMAC_BURST_MODE_DISABLED 

DMAC burst mode is disabled

DMAC_BURST_MODE_4x 

DMAC burst mode enabled, burst size of 4 data units is used

DMAC_BURST_MODE_8x 

DMAC burst mode enabled, burst size of 8 data units is used

◆ dmac_idle_mode_t

DMA idle mode

In blocking mode the DMA performs a fast back-to-back copy, disabling bus access for any bus master with lower priority. In interrupting mode the DMAC inserts a wait cycle after each store allowing other bus masters to perform a burst read.

Enumerator
DMAC_IDLE_BLOCKING_MODE 

Blocking mode.

DMAC_IDLE_INTERRUPTING_MODE 

Interrupting mode.

◆ dmac_init_mode_t

Enumerator
DMAC_INIT_AX_BX_AY_BY 

DMA performs copy A1 to B1, A2 to B2

DMAC_INIT_AX_BX_BY 

DMA performs copy A1 to B1, B2

Function Documentation

◆ R_DMAC_W_Open()

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

Configure a DMAC channel.

Example:

/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_DMAC_W_Open(&g_transfer_ctrl, &g_transfer_cfg);
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.
FSP_ERR_UNSUPPORTEDA Selected setting is not supported by this API.

◆ R_DMAC_W_Reconfigure()

fsp_err_t R_DMAC_W_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 R_DMAC_W_Enable() is called.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_UNSUPPORTEDA Selected setting is not supported by this API.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_W_Open to initialize the control block.

◆ R_DMAC_W_Reset()

fsp_err_t R_DMAC_W_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 and destination.

Return values
FSP_ERR_UNSUPPORTEDThis feature is not supported.

◆ R_DMAC_W_SoftwareStart()

fsp_err_t R_DMAC_W_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_ERR_UNSUPPORTEDThis feature is not supported.

◆ R_DMAC_W_SoftwareStop()

fsp_err_t R_DMAC_W_SoftwareStop ( transfer_ctrl_t *const  p_api_ctrl)

Stop software transfers if they were started with TRANSFER_START_MODE_REPEAT.

Return values
FSP_ERR_UNSUPPORTEDThis feature is not supported.

◆ R_DMAC_W_Enable()

fsp_err_t R_DMAC_W_Enable ( transfer_ctrl_t *const  p_api_ctrl)

Enable a DMAC channel.

Example:

/* Enable the DMAC to start the trasnfer so that it responds to transfer requests. */
err = R_DMAC_W_Enable(&g_transfer_ctrl);
Return values
FSP_SUCCESSDMAC channel activated successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_W_Open to initialize the control block.

◆ R_DMAC_W_Disable()

fsp_err_t R_DMAC_W_Disable ( transfer_ctrl_t *const  p_api_ctrl)

Disable a Dmac channel.

Return values
FSP_SUCCESSDMAC channel disabled successfully.
FSP_ERR_ASSERTIONAn input parameter is invalid.
FSP_ERR_NOT_OPENHandle is not initialized. Call R_DMAC_W_Open to initialize the control block.

◆ R_DMAC_W_InfoGet()

fsp_err_t R_DMAC_W_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_W_Open to initialize the control block.
FSP_ERR_ASSERTIONAn input parameter is invalid.

◆ R_DMAC_W_Reload()

fsp_err_t R_DMAC_W_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_W_CallbackSet()

fsp_err_t R_DMAC_W_CallbackSet ( transfer_ctrl_t *const  p_api_ctrl,
void(*)(dmac_callback_args_t *)  p_callback,
void *const  p_context,
dmac_callback_args_t *const  p_callback_memory 
)

Updates the user callback with the option to provide memory for the callback argument structure.

Return values
FSP_SUCCESSCallback updated successfully.
FSP_ERR_ASSERTIONA required pointer is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_IRQ_BSP_DISABLEDThe IRQ associated with the activation source is not enabled in the BSP.

◆ R_DMAC_W_Close()

fsp_err_t R_DMAC_W_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_W_Open to initialize the control block.

◆ R_DMAC_W_Freeze()

fsp_err_t R_DMAC_W_Freeze ( bool  freeze)

Temporarily freeze/unfreeze all channels of the DMAC controller.

Example:

/* Temporarily disable (freeze) all channels of the DMA controller. */
err = R_DMAC_W_Freeze(true);
assert(FSP_SUCCESS == err);
Return values
FSP_SUCCESSSuccessful freeze.