Renesas DTC HAL Application Note
Application Note
Renesas Synergy™ Platform
DTC HAL Module Guide
Introduction
This module guide will enable you to effectively use a module in your own design. Upon completion of this
guide, you will be able to add this module to your own design, configure it correctly for the target applicati on
and write code, using the included application project code as a reference and efficient starting point .
References to more detailed API descriptions a nd suggestions of other application projects that illustrate
more advanced uses of the module are available in t he Renesas Synergy Knowledge Base (as desc ribed in
the References section at the end of this document) and should be valuable resources for creating more
complex designs.
The Data Transfer Controller (DTC) HAL module is a hi gh-l evel API for data-transfer appl i cations and is
implemented on r_dtc. The DTC HAL module use s t he DTC peripheral on the Synergy MCU. A user-defined
callback can be created to inform the CPU when tran sfer events occur.
Contents
1. DTC HAL Module Features ....................................................................................................... 2
2. DTC HAL Module APIs Overview .............................................................................................. 2
3. DTC HAL Module Operational Overview ................................................................................... 3
3.1 DTC HAL Module Operational Notes ...................................................................................................... 4
3.2 DTC HAL Module Limitations .................................................................................................................. 5
4. Including the DTC HAL Module in an Application ...................................................................... 5
5. Configuring the DTC HAL Module ............................................................................................. 5
6. Using the DTC HAL Module in an Application ........................................................................... 7
7. The DTC HAL Module Application Project ................................................................................ 7
8. Customizing the DTC HAL Module for a Target Application ..................................................... 9
9. Running the DTC HAL Module Application Project ................................................................... 9
10. DTC HAL Module Conclusion .................................................................................................. 10
11. DTC HAL Module Next Steps .................................................................................................. 10
12. DTC HAL Module Reference Information ................................................................................ 10
Revision History .............................................................................................................................. 12
R11AN0116EU0101 Rev.1.01 Page 1 of 12
Jan.07.19
Renesas Synergy™ Platform DTC HAL Module Guide
Function Name
Example API Call and Description
.open
g_transfer0.api->open(g_transfer0.p_ctrl, g_transfer0.p_cfg)
length are valid. Transfers can also be enabled using enable or reset.
.close
g_transfer0.api->close(g_transfer0.p_ctrl)
Close device channel. Turns off hardware if last channel open.
1. DTC HAL Module Features
The Data Transfer Controller (DTC) HAL module moves data from a user-specified source to a userspecified destination when an interrupt or event occurs.
The DTC HAL module has the following features:
• Supports the DTC module on a Synergy MCU
• Supports interrupts, if desired
• Supports multiple transfer modes
Single transfer
Repeat transfer
Block transfer
Address increment or fixed modes
Chain transfers
• Supports multiple channels (depending on sele ct ed i mplementation)
Number of channels is limited only by the size of t he RAM-based vector table.
Figure 1. DTC HAL Module Block Diagram
2. DTC HAL Module APIs Overview
The DTC HAL module defines APIs for opening, closi ng, reset, enabling, disabling, starting, and stopping.
The DTC and the DMAC use the same transfer inte rf ace t o m ake it easier to change between DTC and DMA
implementations. The API calls are the same, independent of the lower-level implementations. A complet e
list of the available APIs, an example API call, and a short description of each can be found in the table
below. A table of status return values follows the A PI summary table.
Table 1. DTC HAL Module API Summary
Initial configuration. Enables the transfer if aut o_enable is true and p_src, p_dest, and
R11AN0116EU0101 Rev.1.01 Page 2 of 12
Jan.07.19
Renesas Synergy™ Platform DTC HAL Module Guide
Function Name
Example API Call and Description
.reset
g_transfer0.api->reset(g_transfer0.p_ctrl, &source,
other settings the same. Enable the transfer if p_src, p_dest, and length are valid.
.start
g_transfer0.api->start(g_transfer0.p_ctrl, mode)
.stop
g_transfer0.api->stop(g_transfer0.p_ctrl)
Stop transfer in software. The transfer stops after completion of the current transfer.
.enable
g_transfer0.api->enable(g_transfer0.p_ctrl)
.disable
g_transfer0.api->disable(g_transfer0.p_ctrl)
transfer_info_t::activation_source).
.versionGet
g_transfer0.api->versionGet(&version)
.infoGet
g_transfer0.api->infoGet(g_transfer0.p_ctrl, &info)
Provides information about this transfer.
.blockReset
g_transfer0.api->blockReset(g_transfer0.p_ctrl, &source,
Name
Description
SSP_SUCCESS
API Call Successful.
SSP_ERR_ASSERTION
Parameter has invalid value.
SSP_ERR_NOT_OPEN
The channel is not opened.
SSP_ERR_UNSUPPORTED
Operation not configured correctly.
SSP_ERR_IN_USE
The channel specified has already been opened. No configurations
Control commands to reconfigure the channel .
SSP_ERR_HW_LOCKED
The DTC hardware resource is locked.
SSP_ERR_IRQ_BSP_DISABLED
IRQ not enabled in BSP.
SSP_ERR_NOT_ENABLED
Operation failed.
SSP_ERR_NOT_OPEN
The channel is not opened.
&destination, number_of_transfers)
Reset source address pointer, destination address pointer, and/or length, keeping all
Start transfer in software.
Enable transfer. Transfers occur after the activ at i on source event (or when start is
called if ELC_EVENT_ELC_SOFTWARE_EVENT_0 or
ELC_EVENT_ELC_SOFTWARE_EVENT_0 is ch osen as activation source).
Disable transfer. Transfers do not occur after the t ransfer_info_t::activation source
event (or when start is called if ELC_EVENT_ELC_SOFTWARE_EVENT_0 or
ELC_EVENT_ELC_SOFTWARE_EVENT_0 is chosen as
Gets version and stores it in provided pointer version.
&destination, length, size, number_of_transfers)
Reset source address pointer, destination address pointer, and/or length, for block
transfer keeping all other settings the same. E nabl e the transfer if p_src, p_dest, and
length are valid.
Note: For details on operation and definitions for the function data structures, typedefs, defines, API data,
API structures and function variables, review the SSP User’s Manual A PI References for the
associated module.
Table 2. Status Return Values
were changed. Call the associated Close function or use associated
Note: Lower-level drivers may return common error codes. Refer to the SSP User’s Manual API references
for the associated module for a definition of all relevant status return values.
3. DTC HAL Module Operational Overview
The Direct Memory Access Controller (DMAC) and the Data Transfer Controller (DTC) can be used t o m ove
data within the Synergy MCU. There are some consi derat ions when selecting between these
implementations. This section includes information on each to help you determine which implementation is
best for your application. The DTC module is recommended for most generic transfer applications, but either
module can be used for basic transfer functionalit y. The following use-cases for each transfer module are
given.
R11AN0116EU0101 Rev.1.01 Page 3 of 12
Jan.07.19
Renesas Synergy™ Platform DTC HAL Module Guide
Selecting the DTC HAL Module
The DTC HAL module uses a RAM-based vector table with slots for every interrupt in the system. When the
DTC transfer completes, the activation source interrupt is called. To use the DTC, the activation source
interrupt must be enabled. Generally, the activat i on source interrupt is muted by the DTC until the transfer
completes unless TRANSFER_IRQ_EACH i s specified in the configuration. For example, if a normal-mode
transfer with a length of 16 is triggered by a timer, the timer interrupt does not fire the first 15 times while the
th
transfer is in effect. After the 16
transfer, the timer interrupt fires. DTC can also allow chained transfers,
meaning more than one transfer can occur after a single act ivation-source interrupt. This feature is supported
by the driver but must be configured outside the ISDE.
Selecting the DMAC HAL Module
The DMAC HAL module moves data from a user-specified source to a user-specified destination when an
interrupt or event occurs. The DMAC HAL module us es the DMAC peripheral registers, so the number of
transfers in the system is limited to the number of DM AC channels on the device. The activation source do es
not have to be enabled to use the DMAC. When the DMAC transfer completes, a DMAC interrupt is called. If
the activation source interrupt is enabled, it fires at the same time the transfer is triggered. If the DMAC
interrupt is enabled, it fires after all transfers are complete. For example, if a normal-mode transfer with a
length of 16 is triggered by a timer, the timer interrupt fires at the same time each transfer occurs and the
th
DMAC interrupt fires after the 16
transfer completes. The DMAC HAL module does not support chained
transfers.
3.1 DTC HAL Module Operational Notes
Normal Mode
In normal mode, a single transfer is triggered each tim e an act ivation-source event occurs. A single transfer
is 1 byte, 2 bytes, or 4 bytes, depending on the setting selected in the size parameter. Each time a transf er
occurs, the transfer length is decremented by 1. When the transfer length reaches 0, the transfer is
complete.
Repeat Mode
In repeat mode, a single transfer is triggered each ti me an act i vation-source event occurs. A single transfe r is
1 byte, 2 bytes, or 4 bytes, depending on the setting s el ect ed in the size parameter. Each time a transfer
occurs, the transfer length is decremented by 1. When the transfer length reaches 0, the transfer length is
reloaded with its initial value and the transfer re st arts. If the repeat area is set to source, the source register
is also reloaded with its initial value when the transf er restarts. Alternatively, if the repeat area is set t o
destination, the destination register is reloaded with its initial value when the transfer restart s.
Block Mode
In the block mode, the entire transfer length is transferred each time an activation-source event occurs. For
example, if a transfer is configured in block mode with the timer as the activation source, a 2-byte size, and a
12-byte length, 24 bytes are transferred each time t he act ivation source event occurs. Each time a transfer
occurs, the transfer length is decremented by 1. When the transfer length reaches 0, the transfer length is
reloaded with its initial value and the transfer re st arts. If the repeat area is set to source, the source register
is also reloaded with its initial value when the transf er restarts. Alternatively, if the repeat area is set to
destination, the destination register is reloaded with its initial value when the transfer restart s.
Address Mode
After each transfer of size (1 byte, 2 bytes, or 4 bytes), the source pointer and destination pointer are
adjusted by src_addr_mode and dest_addr_mode, respectively. For example, if src_addr_mode i s se t
to TRANSFER_ADDR_MODE_INCREMENTED and size is set to TRANSFER_SIZE_4_BYTES, the
p_dest pointer is incremented by 4 (the transfer size) after each transfer. The pointer does not change if s et
to TRANSFER_ADDR_MODE_FIXED.
Chained Transfers
Chained transfers are only supported by the DTC. To use a chained transfer, create an array of
transfer_info_t structures. Set chain_mode to TRANSFER_CHAIN_MODE_ENABLED for all
transfers except the last transfer. Set p_info to t he base of the first structure in the array for
transfer_info_t structures.
R11AN0116EU0101 Rev.1.01 Page 4 of 12
Jan.07.19
Loading...