Texas Instruments EDMA3 User Manual
  1. Manuals
  2. Brands
  3. Texas Instruments Manuals
  4. Controller
  5. EDMA3
  6. User manual
Texas Instruments EDMA3 User Manual

Texas Instruments EDMA3 User Manual

Drivers
Hide thumbs Also See for EDMA3:
Table of Contents

Advertisement

Quick Links

EDMA3 Driver
U
s e
r ' s
G
u
i d
e
User Guide
November 2009
Anuj Aggarwal
Document Version 01.11.00.XX

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the EDMA3 and is the answer not in the manual?

Questions and answers

Subscribe to Our Youtube Channel

Related Manuals for Texas Instruments EDMA3

Summary of Contents for Texas Instruments EDMA3

  • Page 1 EDMA3 Driver r ' s User Guide November 2009 Anuj Aggarwal Document Version 01.11.00.XX...
  • Page 2 Read This First IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete.

  • Page 3: Read This First

    EDMA3 Driver in user systems and applications. This manual provides details regarding how the EDMA3 Driver is Architected, its composition, its functionality, the requirements it places on the hardware and software environment where it can be deployed, how to customize/configure it to specific requirements, how to leverage the supported run-time interfaces in user’s own application etc.,...

  • Page 4: Terms And Abbreviations

    Add any abbreviations and short explanations to the table. Term/Abbreviation Description EDMA Enhanced Direct Memory Access EDMA3 Controller Consists of the EDMA3 channel controller (EDMA3CC) and EDMA3 transfer memory access controller(s) (EDMA3TC). Is referred to as EDMA3 in this document. Direct Memory Access QDMA Quick DMA...

  • Page 5: Notations

    Read This First Notations Explain any special notations or typefaces used (such as for API guides, special typefaces for functions, variables, etc.) Information about Cautions and Warnings This book may contain cautions and warnings. This is an example of a caution statement. CAUTION A caution statement describes a situation that could potentially damage your software or equipment.

  • Page 6: Related Documentation

    Related Documentation  EDMA3 Channel Controller (TPCC), version 3.0.2  EDMA3 Transfer Controller (TPTC), version 3.0.1 Trademarks The TI logo design is a trademark of Texas Instruments Incorporated. All other brand and product names may be trademarks of their respective companies.

  • Page 7: Revision History

    Anuj a) ECN# TIDSP00012004 (Migration to new 01.10.00.01 Aggarwal license) TIDSP00011985 (Addition EDMA3_DRV_disableLogicalChannel in EDMA3 Driver) implemented. b) IRs# SDOCM00058021, SDOCM00058057, SDOCM00058147 and SDOCM00058401 fixed. See release notes for more information. May 11, 2009 Anuj a) Add support for new platforms: C6748, 01.07.00.01...
  • Page 8 Made EDMA3 package RTSC 1.00.00.02 Aggarwal compliant. May 14, 2007 Anuj a) MR# DPSP00007858 (Issue in EDMA3 1.0.0.1 Aggarwal DRV causes false missed events) Fixed. May 9, 2007 Anuj a) MR# DPSP00007800 (Result of resource 1.0.0 Aggarwal allocation is over-written by the semaphore release result in EDMA3 Resource Manager) Fixed.

  • Page 9: Table Of Contents

    This manual also provides supplementary information regarding steps to be followed for proper installation/ un-installation of the EDMA3 Driver. Also included are appendix sections on related Glossary, Web sites and Pointers for gathering further information on the EDMA3 Driver. Terms and Abbreviations .iii Terms and Abbreviations ..................... iv Notations Information about Cautions and Warnings ..............

  • Page 10: Contents

    API Flow Diagram ................. 2-A-72 3.5.1 EDMA3 Driver Creation ................ 2-A-73 3.5.2 EDMA3 Open..................2-A-73 3.5.3 EDMA3 Request Channel (DMA / QDMA Channel) ......2-A-74 3.5.4 EDMA3 Request Channel (LINK Channel) ......... 2-A-75 3.5.5 EDMA3 Close ..................2-A-76 3.5.6 EDMA3 Delete..................2-A-77 API Usage Example ..............

  • Page 11: Tables

    Tables Table 1: Development Tools/components...........1-2-4 Table 2: Build Options..................1-2-8 Table 3: Symbolic Constants and Enumerated Data types Table for common header file edma3_common.h..........2-A-2 Table 4: Symbolic Constants and Enumerated Data types Table for EDMA3 Driver header file edma3_drv.h..........2-A-4...

  • Page 13: Edma3 Driver Introduction

    Chapter 1 EDMA3 Driver Introduction This chapter introduces the EDMA3 Driver to the user by providing a brief overview of the purpose and construction of the EDMA3 Driver along with hardware and software environment specifics in the context of EDMA3...

  • Page 14: Overview

    EDMA3 Driver Introduction Overview This section describes the functional scope of the EDMA3 Driver and its feature set. A brief definition of the component is provided at this point – its main characteristics and purpose. 1.1.1 System Partitioning EDMA3 peripheral supports data transfers between two memory mapped devices.
  • Page 15 EDMA3 Driver Introduction Applications Framework Components PSP Drivers CSL/DAT DMAN ACPY EDMA3 Resource Manager Internally calls DMA/QDMA EDMA3 EDMA3 Driver TCCs PaRAMs Channels ISRs EDMA3 Product Dependency Figure 1: EDMA3 Related Software Product and Packages Structure I-1-3...
  • Page 16 The EDMA3 resources should be carefully allocated among all those instances to avoid any possible conflict. All software entities intending to use the services of the EDMA3 peripheral on the given processor shall use the services of the EDMA3 Product (Resource manager...
  • Page 17 EDMA3 Driver Introduction I-1-5...

  • Page 18: Supported Services

    Following are the services provided by the EDMA3 Driver: 1.1.2.1 Request and Free DMA channel: It provides an interface that applications or device drivers can use to request and free DMA channels. Channels in EDMA3 module are categorized as: DMA Channel (mapped to a hardware sync event), ...
  • Page 19 (and hence different shadow regions). These different instances will run on the same processor but manage same/different set of EDMA3 resources and are tied to different shadow regions. Please note that EDMA3 Driver doesn’t allow multiple instances for a single master on the respective shadow region.

  • Page 21: Installation Guide

    Chapter 2 Installation Guide This chapter discusses the EDMA3 Driver installation, how and what software and hardware components to be availed in order to complete a successful installation of EDMA3 Driver.

  • Page 22: Component Folder

    Top level installation directory. Contains the source code, examples and the documents. docs Contains release notes for EDMA3 Driver and Resource Manager. examples Contains the stand-alone applications for EDMA3 Driver (for all the supported platforms) and the DAT example.
  • Page 23 -> User guide, datasheet etc. d) drv\lib -> EDMA3 Driver libraries for all the supported platforms. e) drv\sample -> Sample code for how to use the EDMA3 Driver, along-with the pre-built libraries for the same. drv\sample\build: Build files for CCSv3/CCSv4/eBinder...

  • Page 24: Development Tools Environment(S)

    Installation Guide Development Tools Environment(s) This section describes the development tools environment(s) for software development with EDMA3 Driver. It describes the tools used and their setup, for each supported environment. 2.2.1 Development Tools Describe here the tools that need to be installed, the installation order and specific configuration.

  • Page 25: Installation Guide

    5) Download the image (.out) onto the platform using CCS. 6) Run the program. 2.3.2 Un-installation 1) Uninstall the EDMA3 package by using the uninstall.exe in the install directory. 2) Un-install the products mentioned in the development tools requirements section as per the instructions provided with the product. I-2-5...

  • Page 26: Integration Guide

    EDMA3 Driver Sample Initialization libraries. 2) For CCSv4: Projects located in drv\build\ccs4\<<target_name>>\ folder needs to be imported via CCSv4 into a workspace to build the EDMA3 Driver libraries for desired target – C64P C674X.

  • Page 27: Building The Dat Example

    Building the DAT Example The EDMA3 package contains CSL 2.0 DAT Adapter Reference Implementation using EDMA3 Low Level Driver. The same can be built using the steps shown in the previous section. The application can be located at “edma3_lld_<<version_number>>\examples\CSL2_DAT_DEMO\demo\” in the platform specific folder.

  • Page 28: Build Options

    Table 2: Build Options Note 1: All EDMA3 public APIs provide a mechanism to disable input parameter checking. This is intended to reduce the number of CPU cycles spent in the parameter checking and hence provide more efficient libraries. To do that, user has to modify the build environment (for e.g.

  • Page 29: Run-Time Interfaces/Integration Guide

    Chapter 3 Run-Time Interfaces/Integration Guide This chapter discusses the EDMA3 Driver run-time interfaces that comprise the API specification & usage scenarios, in association with its data types and structure definitions.

  • Page 30: Symbolic Constants And Enumerated Data Types

    EDMA3 Driver and EDMA3_MAX_PARAM_SETS Maximum PaRAM Sets supported Resource Manager. by the EDMA3 Controller EDMA3_MAX_LOGICAL_CH Maximum Logical channels supported by the EDMA3 Package EDMA3_MAX_TCC Maximum TCCs (Interrupt Channels) supported EDMA3 Controller EDMA3_MAX_EVT_QUE Maximum Event Queues supported by the EDMA3 Controller...
  • Page 31 Defines for the level of OS protection EDMA3_OS_PROTECT_INTERRUPT_XFER_ Protection from EDMA3 Transfer needed when calling COMPLETION Completion Interrupt required edma3OsProtectXXX() EDMA3_OS_PROTECT_INTERRUPT_CC_E Protection from EDMA3 CC Error RROR Interrupt required EDMA3_OS_PROTECT_INTERRUPT_TC_E Protection from EDMA3 TC Error RROR Interrupt required I-A-3...
  • Page 32 Run-Time Interfaces/Integration Guide Table 4: Symbolic Constants and Enumerated Data types Table for EDMA3 Driver header file edma3_drv.h Group or Symbolic Constant Name Description or Evaluation Enumeration Class Driver Error Codes EDMA3_DRV_E_OBJ_NOT_DELETED Before a Driver Object could be created, it must be in the ‘Deleted’...
  • Page 33 Run-Time Interfaces/Integration Guide Driver Global EDMA3_DRV_CH_NO_PARAM_MAP This define is used to say that the Defines DMA channel is not tied to any PaRAM hence available PaRAM Set could be used for that DMA channel. It could be used dmaChannelPaRAMMap [EDMA3_MAX_DMA_CH], in global configuration structure EDMA3_DRV_GblConfigParams.
  • Page 34 Run-Time Interfaces/Integration Guide set for linking. It is used in the API EDMA3_DRV_requestChannel (). PaRAM from pool (owned && non_reserved && available_right_now) PaRAM Sets will be chosen and returned. EDMA3_DRV_QDMA_CHANNEL_0 QDMA Channel 0 define. It used while requesting the specific QDMA channel.
  • Page 35 Run-Time Interfaces/Integration Guide EDMA3_DRV_OPT_FIELD_STATIC Static/non-static PaRAM set EDMA3_DRV_OPT_FIELD_FWID FIFO Width. Applies if either SAM or DAM is set to FIFO mode. EDMA3_DRV_OPT_FIELD_TCCMODE Transfer complete code mode. Indicates the point at which a transfer is considered completed chaining interrupt generation. EDMA3_DRV_OPT_FIELD_TCC Transfer complete code.
  • Page 36 Run-Time Interfaces/Integration Guide used for DMA channels and for non-final transfers in a linked list of QDMA transfers. EDMA3_DRV_STATIC_EN PaRAM set is Static. PaRAM set is not updated or linked after TR is submitted. A value of 1 should be used for isolated QDMA transfers or for the final transfer in a linked list of QDMA transfers.
  • Page 37 (ESR/ESRH). EDMA3_DRV_TRIG_MODE_QDMA EDMA Trigger Mode Selection: Set the Trigger mode to QDMA. A QDMA transfer is triggered when a other EDMA3 programmer) writes to the trigger word QDMA channel parameter set (auto-triggered) or when the EDMA3CC performs a...
  • Page 38 Run-Time Interfaces/Integration Guide EDMA3_DRV_PARAM_ENTRY_SRC PaRAM Set Entry type: The SRC field (Offset Address 4h Bytes) EDMA3_DRV_PARAM_ENTRY_ACNT_BCNT PaRAM Entry type: (ACNT+BCNT) field (Offset Address 8h Bytes) EDMA3_DRV_PARAM_ENTRY_DST PaRAM Set Entry type: The DST field (Offset Address Ch Bytes) EDMA3_DRV_PARAM_ENTRY_SRC_DST_B PaRAM Entry type: (SRCBIDX+DSTBIDX) field (Offset Address 10h Bytes)
  • Page 39 Dest Block (DSTCIDX). EDMA3_DRV_PARAM_FIELD_CCNT PaRAM Set Field type: Number of Frames in a block (CCNT). Enum EDMA3_DRV_IOCTL_MIN_IOCTL EDMA3 Driver IOCTL commands. EDMA3_DRV_IoctlCm Min IOCTL. EDMA3_DRV_IOCTL_SET_PARAM_CLEAR PaRAM Sets will be cleared OR will _OPTION not be cleared during allocation, depending upon this option.
  • Page 40 Run-Time Interfaces/Integration Guide EDMA3_DRV_IOCTL_MAX_IOCTL Max IOCTL. A-12...

  • Page 41: Data Structures

    This configuration information is SoC specific and could be provided by the user at run-time while creating the EDMA3 Driver Object. In case user doesn’t provide it, this information could be taken from the SoC specific configuration file edma3_<SOC_NAME>_cfg.c, in...
  • Page 42 Base address of EDMA3 TCs memory mapped registers. xferCompleteInt EDMA3 transfer completion interrupt line (could be different for ARM and DSP) ccError EDMA3 CC error interrupt line (could be different for ARM and DSP) tcError[EDMA3_MAX_TC] EDMA3 TCs error interrupt line (could be different for ARM and DSP)
  • Page 43 Run-Time Interfaces/Integration Guide DMA channels which are tied to some peripheral are RESERVED for that peripheral only. They are not allocated when user asks for ‘ANY’ DMA channel. All channels need not be mapped, some can be free also. I-A-15...

  • Page 44: Edma3_Drv_Instanceinitconfig

    ARM, b) DSP, c) IMCOP (Imaging Co-processor) etc. User can assign each EDMA3 resource to a shadow region using this structure. In this way, user specifies which resources are owned by the specific EDMA3 Driver Instance. This assignment should also ensure that the same resource is not assigned to more than one shadow regions (unless desired in that way).
  • Page 45 For PaRAM Set, there is one difference. If the DMA channels are one-to-one tied to their respective PaRAM Sets (i.e. user cannot ‘choose’ the PaRAM Set for a particular DMA channel), EDMA3 Driver automatically reserves all those PaRAM Sets which are tied to the DMA channels. Then those PaRAM Sets would not be returned when user requests for ANY PaRAM Set (specifically for linking purpose).

  • Page 46: Edma3_Drv_Initconfig

    Shadow region identifier. Note that only one EDMA3 driver instance can be opened for each shadow region. isMaster It tells whether the EDMA3 driver instance is Master or not. Only the shadow region associated with this master instance will receive the EDMA3 interrupts (if enabled).

  • Page 47: Edma3_Drv_Miscparam

    In a multi-master system (for e.g. ARM + DSP), this option is used to distinguish between Master and Slave. Only the Master is allowed to program the global EDMA3 registers (like Queue priority, Queue water-mark level, error registers etc). param...

  • Page 48: Edma3_Drv_Chainoptions

    Run-Time Interfaces/Integration Guide 3.2.5 EDMA3_DRV_ChainOptions This configuration structure is used to configure the interrupt (final and intermediate) generation and chaining (final and intermediate) options. Member Description tcchEn Transfer complete chaining enable. When enabled, the chained event register (CER/CERH) bit is set on final chained transfer completion (upon completion of the final/last TR in the PaRAM set).

  • Page 49: Edma3_Drv_Paramregs

    EDMA3 PaRAM in user configurable format. This is a mapping of the EDMA3 PaRAM set provided to the user for ease of modification of the individual fields. Member Description OPT field of PaRAM Set. It consists of various transfer related configuration options.
  • Page 50 Run-Time Interfaces/Integration Guide decremented to 0) with a new PaRAM set. The 16-bit parameter LINK specifies the byte address offset in the PaRAM from which the EDMA3CC loads/reloads the next PaRAM set during linking. User should make sure to program the LINK field correctly, so that link update is requested from a PaRAM address that falls in the range of the available PaRAM addresses on the device.

  • Page 51: Edma3_Drv_Evtquepriority

    Run-Time Interfaces/Integration Guide 3.2.7 EDMA3_DRV_EvtQuePriority This configuration structure is used to set the event queues’ priorities. It allows to change the priority of the individual queues and the priority of the transfer request (TR) associated with the events queued in the queue. I-A-23...

  • Page 52: Api Specification

    Run-Time Interfaces/Integration Guide API Specification This section introduces the application programming interface (API) for the EDMA3 Driver. A-24...

  • Page 53: Creation

    Run-Time Interfaces/Integration Guide 3.3.1 Creation This section lists the EDMA3 Driver API that is intended for use in Driver Object creation. 3.3.1.1 EDMA3_DRV_create () Prototype EDMA3_DRV_Result EDMA3_DRV_create (unsigned int phyCtrllerInstId, const EDMA3_DRV_GblConfigParams *gblCfgParams, const void *param); Description This API is used to create the EDMA3 Driver Object.
  • Page 54 SoC. For e.g. number of DMA/QDMA channels, number of PaRAM sets, TCCs, event queues, transfer controllers, base addresses of CC global registers and TC registers, interrupt number for EDMA3 transfer completion, CC error, event queues’ priority,...

  • Page 55: Configuration

    Run-Time Interfaces/Integration Guide 3.3.2 Configuration This section lists the EDMA3 Driver API that allows user to specify the desired configuration parameters of EDMA3 Driver Instance, at run time. It assigns startup/default values to various system parameters of the deployed EDMA3 Driver Instance.
  • Page 56 Comments a) Init configuration structure initCfg consists  regionId - Region Identification Number.  isMaster - Whether EDMA3 Driver Instance is Master or not. Shadow Region tied to this Master Instance will only receive interrupts from the EDMA3 controller, if they are enabled.

  • Page 57: Control

    Run-Time Interfaces/Integration Guide 3.3.3 Control This section lists all the EDMA3 Driver APIs that are intended for use in controlling the functioning of EDMA3 Driver during run- time. 3.3.3.1 EDMA3_DRV_requestChannel () Prototype EDMA3_DRV_Result EDMA3_DRV_requestChannel (EDMA3_DRV_Handle hEdma, unsigned int *pLCh, unsigned int *pTcc, EDMA3_RM_EventQueue...
  • Page 58 This API will not enable the interrupts (IER/IERH register) if the callback function specified by the user is NULL. This is done to provide support for users who want to use EDMA3 in POLL mode. See Also Errors EDMA3_DRV_E_INVALID_PARAM,...
  • Page 59 Description Free the specified channel (DMA/QDMA/Link) and its associated resources (PaRAM Set, TCC etc) and removes various mappings. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> channelId [IN] Logical Channel number to be freed. Return value EDMA3_DRV_SOK or EDMA3_DRV Error Code in case of error.
  • Page 60 3.3.3.3 EDMA3_DRV_clearErrorBits () Prototype EDMA3_DRV_Result EDMA3_DRV_clearErrorBits (EDMA3_DRV_Handle hEdma, unsigned int channelId); Description It clears Event Registers and Error Registers for a specific channel and brings back EDMA3 to its initial state. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance.
  • Page 61 After linking the channels, user should not update any PaRAM Set of the channel. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> lCh1 [IN] Logical Channel to which particular channel will be linked.
  • Page 62 This function breaks the link between the specified channel and the earlier linked logical channel by clearing the Link Address field. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Channel for which linking has to be removed.
  • Page 63 (A/AB Sync), setting the FIFO width etc. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel, bound to which PaRAM set OPT field needs to be set.
  • Page 64 Like enable/disable completion interrupts, enable/disable chaining, setting the transfer mode (A/AB Sync), setting the FIFO width etc. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel bound to which PaRAM Set OPT field is required. <arg3>...
  • Page 65 FIFO. In FIFO Addressing mode, memory location must be 32 bytes aligned. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> lCh [IN] Logical Channel for which the source parameters need to be configured. <arg3> srcAddr [IN] Source address.
  • Page 66 FIFO. In FIFO Addressing mode, memory location must be 32 bytes aligned. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> lCh [IN] Logical Channel for which the destination parameters are to be configured <arg3> destAddr [IN] Destination address.
  • Page 67 AB- synchronized transfer is the first array in the frame. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> lCh [IN] Logical Channel for which source indices are to be configured <arg3>...
  • Page 68 AB-synchronized transfer is the first array in the frame. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> lCh [IN] Logical Channel for which destination indices are to be configured.
  • Page 69 65535 bytes (64K – 1 bytes). ACNT must be greater than or equal to 1 for a TR to be submitted to EDMA3 Transfer Controller. An ACNT equal to 0 is considered either a null or dummy transfer. A dummy or null transfer generates a completion code depending on the settings of the completion bit fields in OPT.
  • Page 70 Run-Time Interfaces/Integration Guide <arg6> bCntReload [IN] Reload value for bCnt. BCNTRLD is a 16-bit unsigned value used to reload the BCNT field once the last array in the 2nd dimension is transferred. This field is only used for A-synchronized transfers. In this case, the EDMA3CC decrements the BCNT value by 1 on each TR submission.
  • Page 71 Chain the two specified channels. This API is used to chain two previously allocated logical (DMA/QDMA) channels. Chaining is different from Linking. The EDMA3 link feature reloads the current channel parameter set with the linked parameter set. The EDMA3 chaining feature does not modify or update any channel parameter set;...
  • Page 72 Run-Time Interfaces/Integration Guide values. It is non-re-entrant for same lCh1 & lCh2 values. See Also Errors EDMA3_DRV_E_INVALID_PARAM A-44...
  • Page 73 Prototype EDMA3_DRV_Result EDMA3_DRV_unchainChannel (EDMA3_DRV_Handle hEdma, unsigned int lCh); Description Unchain the specified channel. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Channel whose chaining with the other channel has to be removed. Return value EDMA3_DRV_SOK or EDMA3_DRV Error Code in case of error.
  • Page 74 (EDMA3_DRV_Handle hEdma, unsigned int lCh, EDMA3_DRV_TrigMode trigMode); Description Start EDMA transfer on the specified channel. There are multiple ways to trigger an EDMA3 transfer. The triggering mode option allows choosing from the available triggering modes: Event, Manual or QDMA. In event triggered, a peripheral or an externally generated event triggers the transfer.
  • Page 75 Run-Time Interfaces/Integration Guide Errors EDMA3_DRV_E_INVALID_PARAM I-A-47...
  • Page 76 (EDMA3_DRV_Handle hEdma, unsigned int lCh, EDMA3_DRV_TrigMode trigMode); Description Disable EDMA transfer on the specified channel. There are multiple ways by which an EDMA3 transfer could be triggered. The triggering mode option allows choosing from the available triggering modes: Event, Manual or QDMA.
  • Page 77 In case of that, this API returns error. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] DMA/QDMA Channel which needs to be disabled.
  • Page 78 This API sets the Trigger word for the specific QDMA channel in the QCHMAP Register. Default QDMA trigger word is CCNT. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> channelId [IN] QDMA Channel which needs to be assigned the Trigger Word.
  • Page 79 QDMA channels whose trigger words are not CCNT field. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel for which new PaRAM set is specified. <arg3> newPaRAM [IN] Parameter RAM set to be copied onto existing PaRAM.
  • Page 80 EDMA3_DRV_PaRAMRegs *currPaRAM); Description Retrieve existing PaRAM associated with specified logical channel (DMA/QDMA/Link). <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel for which new PaRAM set is specified. <arg3> currPaRAM [IN] User gets the existing PaRAM here.
  • Page 81 Description Set a particular PaRAM set entry of the specified PaRAM set <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel bound to the Parameter RAM set whose specified field needs to be set. <arg3>...
  • Page 82 *paRAMEntryVal); Description Get a particular PaRAM set entry of the specified PaRAM set <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel bound to the Parameter RAM set whose specified field needs to be get. <arg3>...
  • Page 83 Description Set a particular PaRAM set field of the specified PaRAM set <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel bound to the Parameter RAM set whose specified field needs to be set. <arg3>...
  • Page 84 *currPaRAMFieldVal); Description Get a particular PaRAM set field of the specified PaRAM set <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel bound to the Parameter RAM set whose specified field needs to be get. <arg3>...
  • Page 85 IO initiated by either of the TCs (Transfer Controllers) relative to IO initiated by the other bus masters on the device (ARM, DSP, USB, etc) <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> evtQPriObj [IN] Priority of the Event Queues Return value EDMA3_DRV_SOK or EDMA3_DRV Error Code in case of error.
  • Page 86 EDMA3_DRV_Result EDMA3_DRV_mapChToEvtQ (EDMA3_DRV_Handle hEdma, unsigned int channelId, EDMA3_RM_EventQueue eventQ); Description Associate Channel to Event Queue <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> channelId [IN] Logical Channel to which the Event Queue is to be mapped. <arg3> eventQ...
  • Page 87 ( EDMA3_DRV_Handle hEdma, unsigned int channelId, unsigned int *mappedEvtQ); Description Get the Event Queue mapped to the specified DMA/QDMA channel <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> channelId [IN] Logical Channel whose associated Event Queue is needed <arg3>...
  • Page 88 EDMA3_DRV_Handle hEdma, unsigned int regOffset, unsigned int newRegValue); Description Sets a particular EDMA3 Channel Controller (CC) register, by specifying the offset and value. Since all the CC registers are 4 bytes in length, the offset specified should be 4-bytes aligned in nature.
  • Page 89 EDMA3_DRV_Handle hEdma, unsigned int regOffset, unsigned int *regValue); Description Gets a particular EDMA3 Channel Controller (CC) register, by specifying the offset. Since all the CC registers are 4 bytes in length, the offset specified should be 4-bytes aligned in nature.
  • Page 90 This is a blocking function that returns when the IPR/IPRH bit corresponding to the tccNo specified, is SET. It clears the corresponding bit while returning also. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> tccNo [IN] TCC, specific to which the function waits on a IPR/IPRH bit.
  • Page 91 It clears the corresponding bit, if SET, while returning also. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> tccNo [IN] TCC, specific to which the function checks the status of the IPR/IPRH bit.
  • Page 92 EDMA3_DRV_SOK or EDMA3_DRV Error Code in case of error. Calling constraints Example result = EDMA3_DRV_Ioctl (hEdma, EDMA3_DRV_IOCTL_SET_PARAM_CLEAR_OPTION, (void *)1,NULL); Comments 'EDMA3_DRV_IOCTL_GET_PARAM_CLEAR_OPTION', this function is re-entrant. 'EDMA3_DRV_IOCTL_SET_PARAM_CLEAR_OPTION', this function is re-entrant for different EDMA3 Driver Instances (handles). See Also Errors EDMA3_DRV_E_INVALID_PARAM A-64...
  • Page 93 LINK field directly SHOULD use this API to get the associated PaRAM Set address with the LINK channel. <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance. <arg2> [IN] Logical Channel for which the PaRAM set offset is required.
  • Page 94 This API is used to return the previously opened EDMA3 Driver's Instance Handle (region specific), which could be used to call other EDMA3 Driver APIs. Since EDMA3 Driver does not allow multiple instances, for a single shadow region, this API is provided.
  • Page 95 Run-Time Interfaces/Integration Guide b) This function is re-entrant. See Also Errors EDMA3_DRV_E_INVALID_PARAM EDMA3_DRV_E_INST_NOT_OPENED I-A-67...

  • Page 96: Termination

    Run-Time Interfaces/Integration Guide 3.3.4 Termination This section should list all the EDMA3 Driver APIs that help in gracefully terminating the deployed EDMA3 Driver run-time entities. A-68...
  • Page 97 3.3.4.1 EDMA3_DRV_close () Prototype EDMA3_DRV_Result EDMA3_DRV_close(EDMA3_DRV_Handle hEdma, void *param) Description It is used to close an already opened EDMA3 Driver Instance. It should be called when the EDMA3 driver functionality is no more required <arg1> hEdma [IN] Handle to the EDMA3 Driver Instance.
  • Page 98 Run-Time Interfaces/Integration Guide 3.3.4.2 EDMA3_DRV_delete () Prototype EDMA3_DRV_Result EDMA3_DRV_delete (unsigned int phyCtrllerInstId, void param); Description EDMA3 Driver instance deletion. Use this API to delete the EDMA3 Driver Object. It should be called ONCE each EDMA3 hardware instance. Note: It should be called ONLY after closing all the EDMA3 Driver Instances.

  • Page 99: Edma3 Driver Initialization

    Run-Time Interfaces/Integration Guide EDMA3 Driver Initialization EDMA3 Driver should be initialized first before it can be used by the peripheral drivers or application. During initialization, EDMA3 driver object is created first and then a region specific EDMA3 driver instance is opened. Following are the APIs which are used for the...

  • Page 100: Api Flow Diagram

    Run-Time Interfaces/Integration Guide API Flow Diagram Below are the flow diagrams for some EDMA3 Driver APIs which interact with the EDMA3 Resource Manager for their functioning. A-72...

  • Page 101: Edma3 Open

    Run-Time Interfaces/Integration Guide 3.5.1 EDMA3 Driver Creation App/Driver EDMA3 Resource EDMA3 Driver Manager EDMA3_DRV_create () EDMA3_RM_create () Reset all global info for this EDMA3 instance For each EDMA3 instance edma3GloablRegionInit () Program H/W Registers 3.5.2 EDMA3 Open App/Driver EDMA3 Resource...

  • Page 102: Edma3 Request Channel (Dma / Qdma Channel)

    Run-Time Interfaces/Integration Guide 3.5.3 EDMA3 Request Channel (DMA / QDMA Channel) EDMA3 Resource EDMA3 Driver Manager EDMA3_RM_allocResource () EDMA3_DRV_requestChannel () Allocate a DMA/QDMA channel. EDMA3_RM_allocResource () Allocate a PaRAM Set. EDMA3_RM_allocResource () Allocate a TCC. Registers the TCC EDMA3_RM_registerTccCb ()

  • Page 103: Edma3 Request Channel (Link Channel)

    Run-Time Interfaces/Integration Guide 3.5.4 EDMA3 Request Channel (LINK Channel) EDMA3 Resource EDMA3 Driver Manager EDMA3_DRV_requestChannel () EDMA3_RM_allocResource () Allocate a PaRAM Set. /* Make the LINK field of Program Registers PaRAM Set NULL */ I-A-75...

  • Page 104: Edma3 Close

    Run-Time Interfaces/Integration Guide 3.5.5 EDMA3 Close EDMA3 Resource App/Driver EDMA3 Driver Manager EDMA3_DRV_close () EDMA3_RM_close () Set the RM Instance specific configuration as NULL. For each EDMA3 instance Set Driver’s state as EDMA3_DRV_CLOSED, If no other Driver Instance is there.

  • Page 105: Edma3 Delete

    Run-Time Interfaces/Integration Guide 3.5.6 EDMA3 Delete EDMA3 Resource App/Driver EDMA3 Driver Manager EDMA3_DRV_delete () EDMA3_RM_delete () Set Resource Manager’s state as EDMA3_RM_DELETED, if no other RM Instance is there. For each EDMA3 instance Set Driver’s state as EDMA3_DRV_DELETED, If no other Driver Instance is there.

  • Page 106: Api Usage Example

    Driver Instance. Afterwards, if required, the application has to register the various interrupt handlers with the underlying OS. After the successful opening, the Driver instance can be used to call other EDMA3 Driver APIs. A-78...
  • Page 107 Run-Time Interfaces/Integration Guide I-A-79...
  • Page 108 Driver Instance. Afterwards, if required, the application has to register the various interrupt handlers with the underlying OS. */ /** EDMA3 Driver Handle, used to call all the Driver APIs */ EDMA3_DRV_Handle hEdma = NULL; /** EDMA3 Driver Instance specific Semaphore handle */ static EDMA3_OS_Sem_Handle semHandle = NULL;...
  • Page 109 Run-Time Interfaces/Integration Guide else * Register Interrupt Handlers for various interrupts * like transfer completion interrupt, CC error * interrupt, TC error interrupts etc, if required. else /* EDMA3 Driver Already Initialized… */ return edma3Result; I-A-81...
  • Page 110 Run-Time Interfaces/Integration Guide Below is the flow diagram for an application requesting a DMA channel to transfer data. After the transfer completion, EDMA3 Resource Manager calls the application specific call-back function, along with the status code. EDMA3 Resource EDMA3 Driver...
  • Page 111 Run-Time Interfaces/Integration Guide Below is the sample code describing the steps required to close the already opened EDMA3 Driver Instance and then delete the EDMA3 Driver Object. It should be done when EDMA3 driver functionality is no more required. EDMA3_DRV_Result edma3deinit(void) unsigned int edmaInstanceId = 0;...

  • Page 112: Edma3 Driver Porting

    EDMA3 Driver Porting Chapter 4 EDMA3 Driver Porting This chapter discusses how to port EDMA3 Driver (and EDMA3 Resource Manager) to other supported target platforms and operating systems. A-84...

  • Page 113: Getting Started

    EDMA3 Driver Porting Getting Started The EDMA3 Driver is based upon PSP Framework architecture making portability and re-usability as prime requirements. Based upon the architecture, the EDMA3 Driver is made like it can be ported to another platform very easily.
  • Page 114 (EDMA3_OS_Sem_Handle hSem); c) Interrupts registration and un-registration: It is not done by the EDMA3 Driver or the Resource Manager. The application which is using the EDMA3 Driver should register the various Interrupt Handlers (ISRs in Resource Manager) with the underlying OS on which it is running.

  • Page 115: Step-By-Step Procedure For Porting

    SoC specific and could be provided by the user at run-time also while creating the EDMA3 Driver object. In case user doesn’t provide it, this information will be taken from the configuration file, in case it is available for the specific SoC.

  • Page 116: Edma3_Rm_Bios__Lib.pjt

    EDMA3 Driver Porting 3.8.2 edma3_rm_bios_<PLATFORM_NAME>_lib.pjt Platform specific EDMA3 configuration file will be included as a source file in the platform specific CCS PJT file. This CCS PJT file will then generate the platform specific Resource Manager library. User can find the various CCS PJT files for different platforms at: “edma3_lld_<VERSION_NUMBER>\packages\ti\sdo\edma3\rm\buil...

  • Page 117: Os-Dependent (Sample) Implementation

    DSP/BIOS version 5.32.02 is the reference OS chosen here for the DM643X platform. /* Below is the sample configuration file which specifies EDMA3 hardware related information like number of transfer controllers, various interrupt ids etc. It is used while interrupts enabling / disabling, in the sample application.
  • Page 118 = EDMA3_HWI_INT; /* Driver Object Initialization Configuration */ EDMA3_DRV_GblConfigParams sampleEdma3GblCfgParams = /** Total number of DMA Channels supported by the EDMA3 Controller */ 64u, /** Total number of QDMA Channels supported by the EDMA3 Controller */ /** Total number of TCCs supported by the EDMA3 Controller */...
  • Page 119 EDMA3 Driver Porting /** Total number of Transfer Controllers (TCs) in the EDMA3 Controller */ /** Number of Regions on this EDMA3 controller */ * \brief Channel mapping existence * A value of 0 (No channel mapping) implies that there is fixed association * for a channel number to a parameter entry number or, in other words, * PaRAM entry n corresponds to channel n.
  • Page 120 EDMA3 Driver Porting 16u, 16u, 16u, * \brief To Configure the Default Burst Size (DBS) of TCs. * An optimally-sized command is defined by the transfer controller * default burst size (DBS). Different TCs can have different * DBS values. It is defined in Bytes.
  • Page 121 EDMA3 Driver Porting * \brief Mapping of DMA channels to Hardware Events from * various peripherals, which use EDMA for data transfer. * All channels need not be mapped, some can be free also. EDMA3_DMA_CHANNEL_TO_EVENT_MAPPING_0, EDMA3_DMA_CHANNEL_TO_EVENT_MAPPING_1 /* Driver Instance Initialization Configuration */...
  • Page 122 Header file for the sample application of the EDMA3 Driver. #include <stdio.h> /* Include EDMA3 Driver */ #include <ti/sdo/edma3/drv/edma3_drv.h> /* To enable debug traces in the EDMA3 sample app */ #define EDMA3_DEBUG_PRINT #define EDMA3_DEBUG_PRINTF printf /* To include linking or chaining test case. */...
  • Page 123 * \brief EDMA3 Initialization * This function initializes the EDMA3 Driver and registers the interrupt handlers. * \return EDMA3_DRV_SOK if success, else error code EDMA3_DRV_Result edma3init (void); * \brief EDMA3 De-initialization * This function removes the EDMA3 RM Instance and unregisters the * interrupt handlers.
  • Page 124 It should be used to create a semaphore with initial value as '1'. The semaphore is then passed by the user to the EDMA3 driver/RM for proper sharing of resources. * \param initVal [IN] is initial value for semaphore...
  • Page 125 EDMA3 Driver Porting /* Below is the sample code which show how to define the OS dependent critical section handling routines. These functions should be mandatorily defined by the user. */ #include <ecm.h> #include <bcache.h> #include <hwi.h> #include <tsk.h> #include <clk.h>...
  • Page 126 EDMA3 Driver Porting /** Exit from critical section */ void edma3OsProtectExit (int level, unsigned int intState) switch (level) case EDMA3_OS_PROTECT_INTERRUPT : HWI_restore (intState); break; case EDMA3_OS_PROTECT_SCHEDULER : TSK_enable(); break; case EDMA3_OS_PROTECT_INTERRUPT_XFER_COMPLETION : ECM_enableEvent (ccXferCompInt); break; case EDMA3_OS_PROTECT_INTERRUPT_CC_ERROR : ECM_enableEvent (ccErrorInt);...
  • Page 127 EDMA3 Driver Porting * \brief EDMA3 Cache Invalidate * This function invalidates the D cache. * \param mem_start_ptr [IN] Starting adress of memory. Please note that this should be aligned according * to the cache line size. * \param num_bytes [IN] length of buffer * \return EDMA3_DRV_SOK if success, else error code in case of error or non-alignment of buffers.
  • Page 128 EDMA3 Driver Porting /* Below is the sample code demonstrating how to create and delete a semaphore with a specific initial value. It also shows how to acquire and later release a semaphore. */ #include <sem.h> /* Function to create OS Semaphore */...
  • Page 129 EDMA3 Driver Porting /* Function to take OS Semaphore */ EDMA3_DRV_Result edma3OsSemTake(EDMA3_OS_Sem_Handle hSem, int mSecTimeout) EDMA3_DRV_Result semTakeResult = EDMA3_DRV_SOK; unsigned short semPendResult; if(NULL == hSem) semTakeResult = EDMA3_DRV_E_INVALID_PARAM; else if (TSK_self() != (TSK_Handle)&KNL_dummy) semPendResult = SEM_pend(hSem, mSecTimeout); if (semPendResult == FALSE) semTakeResult = EDMA3_DRV_E_SEMAPHORE;...
  • Page 130 /** @brief EDMA3 Driver Instance specific Semaphore handle */ static EDMA3_OS_Sem_Handle semHandle = NULL; * EDMA3 TC ISRs which need to be registered with the underlying OS by the user * (Not all TC error ISRs need to be registered, register only for the * available Transfer Controllers).
  • Page 131 * Enabling the HWI_ID. * EDMA3 interrupts (transfer completion, CC error etc.) correspond to different ECM events (SoC specific). * These ECM events come under ECM block XXX (handling those specific ECM events). Normally, block 0 * handles events 4-31 (events 0-3 are reserved), block 1 handles events 32-63 and so on. This ECM block * XXX (or interrupt selection number XXX) is mapped to a specific HWI_INT YYY in the tcf file.

Table of Contents