4.9. CDD_DMA¶
4.9.1. About This Document¶
Document Title |
User Guide of MCAL CDD_DMA Driver |
Document Version |
Version 1.4 |
Company |
Texas Instruments |
Document Name |
CDD_DMA User Guide |
4.9.2. Document Revision History¶
Version |
Date |
Revision History |
Status |
|---|---|---|---|
Version 1.0 |
07 Feb 2023 |
Initial Version |
Approved |
Version 1.1 |
24 Jul 2023 |
Updated as per HTML format. |
Approved |
Version 1.2 |
25 Aug 2023 |
Document release version column removed |
Approved |
Version 1.3 |
25 Oct 2023 |
Updated the document with driver specific details |
Approved |
Version 1.4 |
16 Feb 2024 |
Updated the Information about Readback Function |
Approved |
4.9.3. Table of contents¶
4.9.4. Acronyms and Definitions¶
Acronyms and Definitions used are presented in below table.
Acronyms |
Descriptions |
|---|---|
BSW |
Basic Software |
DET |
Default Error Tracer |
CDD |
Complex Device Driver |
DMA |
Direct Memory Access |
MCU |
Micro Controller Unit |
OS |
Operating System |
API |
Application Programming Interface |
HW |
Hardware |
SW |
Software |
ISR |
Interrupt Service Routine |
INT |
Interrupt |
4.9.5. Functional Overview¶
4.9.5.1. Brief Overview¶
This document describes the functionality, its application interfaces and configuration details of the Cdd_Dma module.
Supported AUTOSAR Release |
4.3.1 |
Supported Configuration Variants |
Pre-Compile |
Vendor ID |
DMA_VENDOR_ID (44) |
Module ID |
DMA_MODULE_ID (255) |
Supported Platform |
AM263x |
The Cdd_Dma module initiates memory transfer without the intervension of the CPU and used in data transfer within peripheral, based on DMA channel configured.
4.9.5.1.1. CDD_DMA Driver¶
Cdd_Dma Driver using HW IP “EDMA”(Enhanced DMA).EDMA, performs high-performance data transfer between two target endpoints, memories and peripheral devices without microcontroller support during transfer. EDMA transfer is programmed through a logical EDMA channel which allows the transfer to be optimally tailored to the requirements of the application. The EDMA controller is based on two major principal blocks:
EDMA third-party channel controller (EDMA_TPCC)
EDMA third-party transfer controller (EDMA_TPTC)
Figure 1: Basic Working Principle
The TPCC is a high flexible channel controller that serves as both a user interface and an event interface for the EDMA controller. The EDMA_TPCC serves to prioritize incoming software requests or events from peripherals, and submits transfer requests (TRs) to the transfer controller. The TPTC performs read and write transfers by EDMA ports to the target peripherals, as programmed in the Active and Pending set of the registers. The transfer controllers are responsible for data movement, and issue read/write commands to the source and destination addresses programmed for a given transfer in the EDMA_TPCC. The Cdd_Dma module has 64 EDMA channels, which serves the purpose of driving transfering of data.
4.9.5.1.2. Initialization¶
Cdd_Dma_Init() has to be called to initialize the Cdd_Dma driver.
4.9.5.1.3. States¶
None
4.9.5.2. Features Supported and Not Supported¶
Cdd_Dma IP Features supported |
Not Supported |
|---|---|
EDMA channels are supported |
QDMA is not supported. |
Both memory transfer and transfer within peripheral is supported |
|
Both interrupt mode and polling mode are supported |
|
Linking of multiple params are supported |
|
Chaining of multiple channels are supported. |
4.9.5.3. Assumptions¶
None
4.9.5.4. Limitations¶
Note
Below are the IP’s that needed software workaround with EDMA because of the HW Limitations -
UART : A dummy PaRAM needs to be linked to the actual TX PaRAM. This is because UART generates TX empty event after the last character is transferred and it results in an event miss error being set in EDMA (since the TX PaRAM has already been used up for the transfer). A dummy PaRAM set is linked to the actual TX PaRAM to service the extra event generated.
McSpi : Above scenario also applies to McSPI. A dummy PaRAM set is linked to solve the issue.
NOTE: Both of these above limitations are taken care internally by UART and McSpi driver respectively.
4.9.5.5. Design overview¶
Please refer SITARA MCU MCAL Architecture Document and MCAL: CDD DMA Detailed Design Document provided as part of CSP.
4.9.5.6. File Structure¶
Description of static files is provided below:
Static source and header files |
Description |
|---|---|
Cdd_Dma.h |
Contains the API’s of the Cdd_Dma driver to be used by upper layers |
Cdd_Dma.c |
Contains the implementation of the API’s for Cdd_Dma driver |
Cdd_Dma_cslr_tpcc.h Cdd_Dma_cslr_tptc.h Cdd_Dma_edma.h Cdd_Dma_Priv.h and Cdd_Dma_Priv.c |
Contains Internal functions definition and initialization of Cdd_Dma driver |
Cdd_Dma_soc.c |
Contains device specific a function definition, data types and definitions |
Cdd_Dma_Irq.c and Cdd_Dma_Irq.h |
Contains ISR function definitions and declaration |
Cdd_Dma_dmaxbar.h Cdd_Dma_trig_xbar.h Cdd_Dma_xbar.h |
Contains DMA cross bar interrupt information |
Description of generated files is provided below:
Plugin Files |
Descriptions |
|---|---|
CDD_Dma_Cfg.h |
Contains the Precompile switches,Symbolic names of the handles and xbar, HW uints. |
CDD_Dma_Cfg.c |
contains the configuration parameters. |
4.9.6. Deviations to requirements(Requirement Traceability)¶
4.9.6.1. Module Requirements¶
Please refer Software Product Specification document provided as part of CSP.
4.9.6.2. Deviation of requirements against AUTOSAR specification requirements¶
Will be updated in future release
4.9.7. Integration Details¶
4.9.7.1. Dependency on Other Software Modules¶
4.9.7.1.1. MCU¶
The module MCU powers up the microcontroller’s peripherals at startup time and initializes the PLL as well as the internal clock domains which is connected to the Cdd_Dma unit.
The Cdd_Dma module will not take care of settings which configure the clock and PLL for channels in its init function. This must be done by the MCU module.
4.9.7.1.2. Port¶
The Port driver configures the port pins used for the Cdd_Dma driver as input or output. Hence, the Port driver has to be initialized prior to the use of Cdd_Dma functions. Otherwise, Cdd_Dma driver functions will exhibit undefined behavior.
4.9.7.1.3. OS¶
An operating system can be used for task scheduling, interrupt handling, global suspend and restore of interrupts and creating of the Interrupt Vector Table.The Cdd_Dma module may use AUTOSAR OS to suspend and restore global interrupts.
4.9.7.1.4. Error Handling module¶
4.9.7.1.4.1. DET¶
In development mode, the Cdd_Dma module reports development error through the Det_ReportError function of module DET.
Type of Error |
Relevance |
Related Error Code |
Value |
|---|---|---|---|
API service called without module initialization |
Development |
CDD_DMA_E_UNINIT |
0x01 |
API service for initialization is called when already initialized |
Development |
CDD_DMA_E_ALREADY_INITIALIZED |
0x02 |
API parameter checking: invalid value |
Development |
CDD_DMA_E_PARAM_VALUE |
0x03 |
API parameter checking: invalid pointer |
Development |
CDD_DMA_E_PARAM_POINTER |
0x04 |
API service for indicating callback is already registered |
Development |
CDD_DMA_E_ALREADY_REGISTERED |
0x05 |
API service for indicating DMA handle already in use |
Development |
CDD_DMA_E_ALREADY_IN_PROGRESS |
0x06 |
4.9.7.1.4.2. DEM¶
None
4.9.7.1.4.3. Callback Functions¶
None
4.9.7.1.4.4. Callback Notification¶
None
4.9.7.2. Hardware - Software - ISR API name mapping¶
Cdd_Dma driver provides ISR for transfer completion detection. The interrupt category must be configured in Cdd_Dma Driver and OS modules.
Respective ISR for each Cdd_Dma Instance in AM263x are as follows:
Cdd_Dma Instances |
ISR Routines |
|---|---|
CDD_DMA_MSS_A |
CDD_EDMA_lld_transferCompletionMasterIsrFxn() |
CDD_DMA_MSS_A instance of Cdd_Dma has interrupt number as “72” in AM263x.
4.9.7.3. Scheduling Strategy¶
4.9.7.3.1. SchM (Optional)¶
Beside the OS the BSW Scheduler provides functions that module Cdd_Dma calls at begin and end of critical sections.
4.9.7.3.2. Critical Sections¶
There is only one kind of critical sections in this driver. Within these sections all read /modify / write accesses to internal Cdd_Dma driver data structures must be protected. Therefore, switching to tasks that also access Cdd_Dma has to be avoided and all Cdd_Dma interrupts have to be suspended. This is handled internally by Cdd_Dma Driver.
4.9.8. API Description¶
4.9.8.1. Description of the API’s¶
API SERVICE |
DESCRIPTION |
|---|---|
Cdd_Dma_Init |
Service is used for initialization of the module. |
Cdd_Dma_DeInit |
Service to de-initialize the module. With this call all handlers registered are de-initialized. |
Cdd_Dma_GetInitStatus |
Service to provide the initialization status of the module. |
Cdd_Dma_CbkRegister |
Service to register callback function for a TCC. And this callback will be called once transfer completion happens for that particular TCC associated with the handle. |
Cdd_Dma_ParamSet |
Service to set the paramSet value with the param value associated with the channel of a particular handle.Here length of the transmission and how the data should be transferred is configured. |
Cdd_Dma_LinkChannel |
Service to link the params. Ofter used to link different params within the channel.With this functionality once the paramSet got empty after the transfer linked paramSet will be automatically loaded. |
Cdd_Dma_ChainChannel |
Service to chain multiple channels and used in transmission with one trigger.So when we chain multiple channels then with a single trigger it will transfer from both channels. |
Cdd_Dma_EnableTransferRegion |
Service to enable the trigger for transmission. Can be event based or manual. |
Cdd_Dma_GetStatus |
Service to Read the status of the transfer. Used in case of polling.In case of polling mode we need to continue poll this service in order to know the status of the transfer. |
Cdd_Dma_GetVersionInfo |
Service to get version information |
Cdd_Dma_GetParam |
Service to get the paramSet value with the param value associated with the channel of a particular handle.Here remaining data to be transferred is returned. |
Cdd_Dma_DisableTransferRegion |
Service to disable the trigger for transmission. Can be event based or manual. |
Cdd_Dma_RegisterReadback |
Service to read the data in the registers of DMA. |
4.9.8.2. API’s with Service ID¶
Service ID |
Service |
|---|---|
0x01 |
Cdd_Dma_Init |
0x02 |
Cdd_Dma_DeInit |
0x0A |
Cdd_Dma_GetInitStatus |
0x03 |
Cdd_Dma_CbkRegister |
0x04 |
Cdd_Dma_ParamSet |
0x05 |
Cdd_Dma_LinkChannel |
0x06 |
Cdd_Dma_ChainChannel |
0x07 |
Cdd_Dma_EnableTransferRegion |
0x08 |
Cdd_Dma_GetStatus |
0x09 |
Cdd_Dma_GetVersionInfo |
0x0B |
Cdd_Dma_GetParam |
0x0C |
Cdd_Dma_DisableTransferRegion |
0x0D |
Cdd_Dma_RegisterReadback |
4.9.8.3. Description on Non Standard API’s¶
Dma_RegisterReadback API
This function is non-autosar based and is used to read the data in the registers of DMA.
This functionality is enabled, if parameter Dma_RegisterReadback is TRUE (The Parameter sets DMA_REGISTER_READBACK_API Macro as STD_ON ).
Service Id is 0x0D.
4.9.9. Configuration Description¶
4.9.9.1. Configuration Variants¶
The Cdd_Dma can be configured as Pre-Compile variant, using EB tresos tool.
Variants |
Generated Files |
|---|---|
Pre-Compile |
Cdd_Dma_Cfg.c , Cdd_Dma_Cfg.h |
4.9.9.2. Parameter Description¶
Standard Parameters |
Description |
Default Value |
Range |
Unit/Datatype |
|---|---|---|---|---|
Config Variant |
Parameter used to configure the variant of the module. |
Pre-Compile |
Pre-Compile |
ENUMERATION |
CddDmaVersionInfoApi |
Macro to enable or disable the version info |
TRUE |
TRUE or FALSE |
BOOLEAN |
CddDmaDeinitApi |
Macro to enable or disable the DeInit Api |
TRUE |
TRUE or FALSE |
BOOLEAN |
CddDmaDevErrorDetect |
Macro to enable or disable the Development error detection |
TRUE |
TRUE or FALSE |
BOOLEAN |
CddDmaIrqType |
Parameter specifies the category of Interrupt Request. |
CDD_DMA_ISR_VOID |
CDD_DMA_ISR_VOID CDD_DMA_ISR_CAT1 CDD_DMA_ISR_CAT2 |
ENUMERATION |
CddDmaTransferType |
Parameter denote the type of transfer either this is memory transfer or peripheral based and even in peripheral based which peripheral is using Dma is decided by this field. |
CDD_DMA_TRANSFER_TYPE_MEMORY_TRANSFER |
CDD_DMA_TRANSFER_TYPE_MEMORY_TRANSFER CDD_DMA_TRANSFER_TYPE_UART_TX CDD_DMA_TRANSFER_TYPE_UART_RX CDD_DMA_TRANSFER_TYPE_ADC CDD_DMA_TRANSFER_TYPE_MC_SPI |
ENUMERATION |
CddDmaInstance |
Parameter to select the Dma instance which we want to use. |
CDD_DMA_MSS_A |
CDD_DMA_MSS_A |
ENUMERATION |
CddDmaRegionID |
There are several dma regions and according to the region selected DMA resources(DMA channels and interrupts) that are assigned to the region can be used by EDMA programmer. |
0 |
0 to 7 |
INTEGER |
CddDmaTccNumber |
Tcc field is linked to the logical channel and whenever that channel is involved in the transmission we can see the completion status for that channel based on the Tcc number. |
0 |
0 to 63 |
INTEGER |
CddDmaQueueNumber |
Queue number correspond to the priority of the transfer.Lower the number higher the priority. |
0 |
0 to 1 |
INTEGER |
CddDmaEnableInterrupt |
Parameter to enable or disable the interrupt mode |
TRUE |
TRUE or FALSE |
BOOLEAN |
CddDmaTransferModeSelect |
In Cdd_Dma we are supporting multiple transfer mode like linking (used in case linking params) chaining(used in chaining channels)and nomal mode. |
CDD_DMA_TRANSFER_MODE_NORMAL |
CDD_DMA_TRANSFER_MODE_NORMAL CDD_DMA_TRANSFER_MODE_LINKING CDD_DMA_TRANSFER_MODE_CHAINING |
ENUMERATION |
CddDmaChannel |
In a particular handle we have channel group and within this we have channel number(logical channel) we can assign channel number which will be linked to the handle.In case of chaining multiple channels can be configured. |
0 |
0 to 63 |
INTEGER |
CddDmaParamNumber |
For a particular channel group we can have multiple params so param number is assigned at channel level and each param has dedicated paramSet which contains transfer parameters. |
0 |
0 to 255 |
INTEGER |
Below parameters are applicable for AM263x device only
Parameter “CddDmaDmaChannelModule” represents the Cdd_Dma channel of EDMA module i.e., from 0 to 63.
Parameter “CddDmaChannelTriggerSource” represents the Cdd_Dma trigger source from external module (such as UART, SPI , Cross Bar etc)
Parameter “CddDmaDmaChannelXbar” represents the cross bar triggers that are represented in Parameter “CddDmaChannelTriggerSource” ( from “DMA_TRIG_XBAR_DMA_XBAR_OUT_0” to “DMA_TRIG_XBAR_DMA_XBAR_OUT_15”).
Parameter “CddDmaDmaChannelXbarMap” represents the trigger source, where cross bar triggers are mapped to particular interrupt trigger source from external modules (such as ADC, EPWM, FSI etc.., )
4.9.9.3. Symbolic Names deviations¶
None.
4.9.9.4. Configuration rules and constraints to enable plausibility checks¶
None.
4.9.10. Memory Mapping¶
Memory Mapping Sections |
CDD_DMA_CODE |
CDD_DMA_CODE_ISR |
CDD_DMA_VAR_NO_INIT |
CDD_DMA_VAR |
CDD_DMA_CFG |
|---|---|---|---|---|---|
CDD_DMA_START_SEC_VAR_INIT_8(.bss) |
x |
||||
CDD_DMA_STOP_SEC_VAR_INIT_8 |
x |
||||
CDD_DMA_START_SEC_CONFIG_DATA (.const) |
x |
||||
CDD_DMA_STOP_SEC_CONFIG_DATA |
x |
||||
CDD_DMA_START_SEC_CODE(.text) |
x |
||||
CDD_DMA_STOP_SEC_CODE |
x |
||||
CDD_DMA_START_SEC_VAR_INIT_32(.bss) |
x |
||||
CDD_DMA_STOP_SEC_VAR_INIT_32 |
x |
||||
CDD_DMA_START_SEC_VAR_NO_INIT_UNSPECIFIED(.data) |
x |
||||
CDD_DMA_STOP_SEC_VAR_NO_INIT_UNSPECIFIED |
x |
||||
CDD_DMA_START_SEC_ISR_CODE |
x |
||||
CDD_DMA_STOP_SEC_ISR_CODE |
x |
4.9.11. Memory footprint¶
Please refer Memory Footprint for more details.
4.9.12. Performance¶
Not Applicable
4.9.12.1. ISR latency / ISR processing time¶
Not Applicable
4.9.12.2. API level profiling¶
Not Applicable
4.9.13. Example Usage¶
4.9.13.1. Steps to build and run example¶
Cdd_Dma example applications demonstrates the MCAL CDD_DMA driver features, which is referred from folder <MCAL_ROOT>/examples/Dma.
There are 4 example applications provided to verify all the features of the module.
These applications can be built from the build folder by giving :
“gmake –s dma_pollingmode_app PLATFORM=am263” for polling mode example
“gmake –s dma_interruptmode_app PLATFORM=am263” for interrupt mode example
“gmake –s dma_linkingmode_app PLATFORM=am263” for linking mode example
“gmake –s dma_chainingmode_app PLATFORM=am263” for chaining mode example
In case of linking mode example multiple params are configured within the channel and once the execution gets completed with first paramSet then automatically second paramSet data will be loaded.
In case of chaining mode example multiple channels are chained together so in this case once the trigger for first channel happen for transmission it will internally trigger for second channel as well.So in this way with less number of trigger transmission happens.
Once the build is completed we get a binary file,which is loaded in our controller and executed.
4.9.13.2. Document external set up Information¶
None
4.9.14. FAQ’s¶
None
4.9.15. Test Report¶
Please refer AM26x CDD DMA Driver Test Case Report provided as part of CSP.
4.9.16. References¶
4.9.17. TI Disclaimer¶
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgment, including those pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements.
Customers are responsible for their applications using TI components. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, license, warranty or endorsement thereof.
Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations and notices. Representation or reproduction o f this information with alteration voids all warranties provided for an associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Resale of TI’s products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service, is an unfair and deceptive business practice, and TI is not responsible nor liable for any such use.
Also see: Standard Terms and Conditions of Sale for Semiconductor Products https://www.ti.com/sc/docs/stdterms.htm
Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265