Transfer Driver on r_dtc

Table of Contents

• DTC HAL Module Introduction
  • DTC HAL Module Features
  • DTC Hardware support details
• DTC HAL Module APIs Overview
• DTC HAL Module Operational Overview
  • DTC HAL Module Important Operational Notes and Limitations
    • DTC HAL Module Operational Notes
    • DTC HAL Module Limitations
• Including the DTC HAL Module in an Application
• Configuring the DTC HAL Module
  • DTC HAL Module Clock Configuration
  • DTC HAL Module Pin Configuration
• Using the DTC HAL Module in an Application

DTC HAL Module Introduction

The Data Transfer Controller (DTC) HAL module provides a high-level API for data-transfer applications and uses the DTC peripheral on the Synergy MCU. A user-defined callback can be created to inform the CPU when transfer events occur.

DTC HAL Module Features

The Data Transfer Controller (DTC) HAL module moves data from a user-specified source to a user-specified destination when an interrupt or event occurs.

• 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 selected implementation)
  • Number of channels is limited only by the size of the RAM-based vector table

DTC HAL Module Block Diagram

DTC Hardware support details

The following hardware features are, or are not, supported by SSP for DTC.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Normal Transfer Mode	Repeat Transfer Mode	Block Transfer Mode	Selectable Data Transfer Units (8 bits, 16 bits, 32 bits)	API/Config for Event link function upon completion of DTC transfers
S124	✓	✓	✓	✓	⌧
S128	✓	✓	✓	✓	⌧
S1JA	✓	✓	✓	✓	⌧
S3A1	✓	✓	✓	✓	⌧
S3A3	✓	✓	✓	✓	⌧
S3A6	✓	✓	✓	✓	⌧
S3A7	✓	✓	✓	✓	⌧
S5D3	✓	✓	✓	✓	⌧
S5D5	✓	✓	✓	✓	⌧
S5D9	✓	✓	✓	✓	⌧
S7G2	✓	✓	✓	✓	⌧

DTC HAL Module APIs Overview

The DTC HAL module defines APIs for opening, closing, resetting, enabling, disabling, starting and stopping. Note that the DTC and the DMAC use the same transfer interface to make it easier to change between DTC and DMA implementations. The API calls are the same independent of the lower-level implementations. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

DTC HAL Module API Summary

Function Name	Example API Call and Description
open	g_transfer0.api->open(g_transfer0.p_ctrl, g_transfer0.p_cfg) Initial configuration. Enables the transfer if auto_enable is true and p_src, p_dest, and 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.
reset	g_transfer0.api->reset(g_transfer0.p_ctrl, &source, &destination, number_of_transfers) Reset source address pointer, destination address pointer, and/or length, keeping all 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)  Start transfer in software.
stop	g_transfer0.api->stop(g_transfer0.p_ctrl) Stop transfer in software. The transfer will stop after completion of the current transfer.
enable	g_transfer0.api->enable(g_transfer0.p_ctrl) Enable transfer. Transfers occur after the 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 activation source).
disable	g_transfer0.api->disable(g_transfer0.p_ctrl) Disable transfer. Transfers do not occur after the transfer_info_t::activation source event (or when start is called if ELC_EVENT_ELC_SOFTWARE_EVENT_0or ELC_EVENT_ELC_SOFTWARE_EVENT_0 is chosen as  transfer_info_t::activation_source).
versionGet	g_transfer0.api->versionGet(&version) Gets version and stores it in provided pointer 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, &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. Enable the transfer if p_src, p_dest, and length are valid.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

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 were changed. Call the associated Close function or use associated 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.

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.

DTC HAL Module Operational Overview

The Direct Memory Access Controller (DMAC) and the Data Transfer Controller (DTC) can be used to move data within the Synergy MCU. There are some considerations when selecting between these implementations; the following operational overview 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 functionality. The use-cases for each transfer module are:

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 uses DMAC peripheral registers, so the number of transfers in the system is limited to the number of DMAC channels on the device. The activation source does 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 DMAC interrupt fires after the 16th transfer completes. The DMAC HAL module does not support chained transfers.

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. The activation source interrupt must be enabled to use the DTC. The activation source interrupt is generally muted by the DTC until the transfer completes, unless TRANSFER_IRQ_EACH is 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 transfer is in effect. After the 16th transfer, the timer interrupt fires. The DTC also allows chained transfers, meaning that more than one transfer can occur after a single activation-source interrupt. This feature is supported by the driver but must be configured outside the ISDE.

DTC HAL Module Important Operational Notes and Limitations

DTC HAL Module Operational Notes

Normal Mode

In normal mode, a single transfer is triggered each time an activation-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 transfer 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 time an activation-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 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 restarts. If the repeat area is set to source, the source register is also reloaded with its initial value when the transfer restarts. Alternatively, if the repeat area is set to destination, the destination register is reloaded with its initial value when the transfer restarts.

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 the activation 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 restarts. If the repeat area is set to source, the source register is also reloaded with its initial value when the transfer restarts. Alternatively, if the repeat area is set to destination, the destination register is reloaded with its initial value when the transfer restarts.

Address Mode

After each transfer of size (1 byte, 2 bytes, or 4 bytes), the source pointer and destination pointer are adjusted based on the configuration settings for Source Address Mode and Destination Address Mode, respectively. For example, if the Source Address Mode is set to TRANSFER_ADDR_MODE_INCREMENTED and the size is set to TRANSFER_SIZE_4_BYTES, the destination pointer is incremented by 4 (the transfer size) after each transfer. The pointer does not change if the configuration setting is 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. Configure transfer_chain_mode_t to TRANSFER_CHAIN_MODE_EACH or TRANSFER_CHAIN_MODE_END for all transfers except the last transfer. The last transfer must be TRANSFER_CHAIN_MODE_DISABLED.

Set transfer_cfg_t::p_info to the base of the first structure in the array for transfer_info_t structures.

DTC HAL Module Limitations

• Refer to the most SSP Release Notes for any additional operational limitations for this module.

Including the DTC HAL Module in an Application

This section describes how to include the DTC HAL Module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Transfer Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Transfer Driver is g_transfer0. This name can be changed in the associated Properties window.)

DTC HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_ transfer0 DTC Driver on r_dtc	Threads> HAL/Common	New Stack> Driver> Transfer> Transfer Driver on r_dtc

When the Transfer Driver on r_dtc is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

DTC HAL Module Stack

Configuring the DTC HAL Module

The DTC HAL Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the DTC HAL Module on r_dtc

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Selects if code for parameter checking is to be included in the build.
Software Start	Enabled, Disabled Default: Disabled	Software start selection.
Linker section to keep DTC vector table	.ssp_dtc_vector_table	Linker section to keep DTC vector table selection.
Name	g_transfer0	Module name.
Mode	Normal, Repeat, Block Default: Normal	Mode selection.
Transfer Size	2 Bytes	Transfer size selection.
Destination Address Mode	Fixed, Incremented, Destination Default: Fixed	Destination address mode selection.
Source Address Mode	Fixed, Incremented, Destination Default: Fixed	Source address mode selection.
Repeat Area (Unused in Normal Mode	Destination, Source Default: Source	Repeat area selection.
Interrupt Frequency	After all transfers have completed	Interrupt frequency selection.
Destination Pointer	NULL	Destination pointer selection.
Source Pointer	NULL	Source pointer selection.
Number of Transfers	0	Number of transfers selection.
Number of Blocks (Valid only in Block Mode)	0	Number of blocks selection.
Activation Source (Must enable IRQ)	Software Activation 1, Software Activation 2, Peripheral Events Default: Software Activation 1	Activation source selection.
Auto Enable	True, False Default: True	Auto enable selection.
Callback (Only valid with Software start)	NULL	Callback selection.
ELC Software Event Interrupt Priority	Priority 0 (highest), Priority 1:2, Priority 3 (lowest - not valid if using ThreadX) Default: Disabled	ELC Software Event interrupt priority selection.

Note

The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

DTC HAL Module Clock Configuration

The DTC peripheral module use ICLK as the clock source. The ICLK frequency is set by using the SSP configurator Clocks tab prior to a build, or by using the CGC Interface at run-time.

DTC HAL Module Pin Configuration

The DTC is not associated with any pins.

Using the DTC HAL Module in an Application

The typical steps in using the DTC HAL module in an application are:

1. Initialize the DTC using the transfer_api_t::open API.
2. Enable the DTC using the transfer_api_t::enable API (if not auto enabled).
3. Manage transfers using other APIs as needed.
4. Close the DTC with the transfer_api_t::close when needed.

These common steps are illustrated in a typical operational flow diagram in the following figure:

Flow Diagram of a Typical DTC HAL Module Application