 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The DMAC HAL module provides a high-level API for data-transfer applications and uses the DMAC peripheral on the Synergy MCU. A user-defined callback can be created to inform the CPU when transfer events occur.
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 supports the following:
The following hardware features are, or are not, supported by SSP for DMAC.
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 | Extended repeat area function | Event link function through ELC HAL driver |
|---|---|---|---|---|---|
| S124 | N/A | N/A | N/A | N/A | N/A |
| S128 | N/A | N/A | N/A | N/A | N/A |
| S1JA | N/A | N/A | N/A | N/A | N/A |
| S3A1 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S3A3 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S3A6 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S3A7 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S5D3 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S5D5 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S5D9 | ✓ | ✓ | ✓ | ✓ | ✓ |
| S7G2 | ✓ | ✓ | ✓ | ✓ | ✓ |
The DMAC HAL module defines APIs for opening, closing, starting and stopping timers. Note that the Data Transfer Controller (DTC) and the DMAC use the same transfer interface; sharing an interface makes 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 function can be found in the following table. A table of status return values follows the API summary table.
DMAC HAL Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| open | g_transfer0.api->open(g_transfer0.p_ctrl, g_transfer0.p_cfg)Open device channel. Initialize driver and hardware on first call. |
| 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 channel settings. |
| start | g_transfer0.api->start(g_transfer0.p_ctrl, mode)Start data transfer. |
| stop | g_transfer0.api->stop(g_transfer0.p_ctrl)Stop data transfer. |
| enable | g_transfer0.api->enable(g_transfer0.p_ctrl)Enable channel. |
| disable | g_transfer0.api->disable(g_transfer0.p_ctrl)Disable channel. |
| versionGet | g_transfer0.api->versionGet(&version)Retrieve the API version with the version pointer. |
| infoGet | g_transfer0.api->infoGet(g_transfer0.p_ctrl, &info)Get transfer channel info. |
| blockReset | g_transfer0.api->blockReset(g_transfer0.p_ctrl, &source, &destination, length, size, number_of_transfers)Reset Block Transfer parameters. |
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_IRQ_BSP_DISABLED | IRQ not enabled in BSP. |
| SSP_ERR_NOT_ENABLED | Operation failed. |
| SSP_ERR_NOT_OPEN | The channel is not opened. |
| SSP_ERR_INVALID_SIZE | Invalid Offset Value. |
The DMAC and the DTC can be used to move data within the Synergy MCU. There are a few considerations when selecting between these modules and you need to determine which implementation works best for your application. The DTC module is recommended for most generic transfer applications and is also available for data transfer operations. The following use cases describe operations within each transfer module.
Selecting the DTC Transfer 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.
Selecting the DMAC Transfer 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 does not support chained transfers.
Normal Mode
In normal mode, a single transfer triggers 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 decrements by 1. When the transfer length reaches 0, the transfer is complete.
Repeat Mode
In repeat mode, a single transfer triggers 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 decrements by 1. When transfer length reaches 0, the transfer length reloads with its initial value and the transfer restarts. If the repeat area is set to source, the source register also reloads with its initial value when the transfer restarts. Alternatively, if the repeat area is set to destination, the destination register reloads with its initial value when the transfer restarts.
Block Mode
In block mode, the entire transfer length transfers each time an activation source event occurs. For example, if a transfer is configured in the block mode with a timer as the activation source, a 2-byte size and 12-byte length, 24 bytes transfer each time the activation source event occurs. Each time a transfer occurs, the transfer length decrements by 1. When the length reaches 0, the transfer length reloads 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 reloads 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 adjust by transfer_info_t::src_addr_mode and transfer_info_t::dest_addr_mode, respectively.
For example, if transfer_info_t::src_addr_mode is set to TRANSFER_ADDR_MODE_INCREMENTED, and size is set to TRANSFER_SIZE_4_BYTE, the transfer_info_t::p_dest pointer is incremented by 4 (the transfer size) after each transfer.
For TRANSFER_ADDR_MODE_OFFSET, the pointer is incremented or decremented by the configured offset value.
The pointer does not change if set to TRANSFER_ADDR_MODE_FIXED.
Refer to the latest SSP Release Notes for any additional operational limitations for this module.
This section describes how to include the DMAC HAL Module in an application using the SSP configurator.
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_dmac0. This name can be changed in the associated Properties window.)
DMAC HAL Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_ transfer0 Transfer Driver on r_dmac | Threads | New Stack> Driver> Transfer> Transfer Driver on r_dmac |
When the Transfer Driver on r_dmac 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.
The DMAC 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.
Configuration Settings for the DMAC HAL Module on r_dmac
| ISDE Property | Value | Description |
|---|---|---|
| Parameter Checking | BSP, Enabled, Disabled Default: BSP | Selects if code for parameter checking is to be included in the build. |
| Name | g_transfer0 | Module name. |
| Channel | 0 | Channel selection. |
| Mode | Normal, Repeat, Block Default: Normal | Mode selection. |
| Transfer Size | 1 Byte, 2 Bytes, 4 Bytes Default: 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. |
| 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. |
| Offset Addition (Valid only in Offset Addition mode) | -16777216 to 16777215 Default: 0 | Offset value selection. |
| Activation Source | Software Activation, Peripheral Events Default: Software Activation | Activation source selection. |
| Auto Enable | True, False Default: True | Auto enable selection. |
| Callback | NULL | Callback selection. |
| Interrupt Priority | Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX) Default: Disabled | Interrupt priority selection. |
The DMAC peripheral module use ICLK as the clock source. The ICLK frequency is set by using the SSP configurator clock tab, prior to a build, or by using the CGC Interface at run-time.
The DMAC HAL Module is not associated with any pins.
The typical steps in using the DMAC HAL module in an application are:
These common steps are illustrated in a typical operational flow diagram in the following figure:
