Texas Instruments EDMA3 User Manual

November 2009 Anuj Aggarwal

Document Version 01.11.00.XX

EDMA3 Driver

User Guide

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.

TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards.

TI does not warrant or represent that any licen se, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information published by TI regarding third-party products or servi ces does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third par ty under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI

Mailing Address:

Texas Instruments

Post Office Box 655303, Dallas, Texas 75265

LICENSE

This work is licensed under the Creative Commons Attribution-Share Alike 3.0 United States License. To view a copy of this license, visit

http://creativecommons.org/licenses/by-sa/3.0/us/

or send a letter to Creative Commons,

171 Second Street, Suite 300, San Francisco, California, 94105, USA.

iii

Preface

Read This First

About This Manual

This User’s Manual serves as a software programmer’s handbook for working with the EDMA3 Driver Version 01.11.00.XX. This manual provides necessary information regarding how to effectively install, build and use

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.,

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.

Read This First

Terms and Abbreviations

Add any longer explanations for terms before the table.

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.

DMA Direct Memory Access

QDMA Quick DMA

TCC Transfer Completion Code (basically Interrupt Channel)

ISR Interrupt Service Routine

CC Channel Controller

TC Transfer Controller

RM Resource Manager

TR Transfer Request.

A command for data movement that is issued from the EDMA3CC to the EDMA3TC. A TR includes source and destination addresses, counts, indexes, options, etc.

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.

CAUTION

WARNING

The information in a caution or a warning is provided for your protection. Please read each caution and warning carefully.

This is an example of a caution statement.

A caution statement describes a situation that could potentially damage your software or equipment.

This is an example of a warning statement.

A warning statement describes a situation that could potentially cause harm to you

Read This First

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.

Read This First

vii

Revision History

Date Author Revision History Version

November 2, 2009

Anuj Aggarwal

a) Added CCSv4 / BIOS5 support and linux

installer in LLD.

b) IRs SDOCM00061179 (Device 6748 isn't

listed in package.xs file of ti.sdo.fc.edma3.rm) & SDOCM00061809 (Exception occurs when edma3deinit() API called) fixed.

See release notes for more information.

01.11.00.XX

July 9, 2009 Anuj

Aggarwal

a) ECN# TIDSP00012004 (Migration to new

BSD license) and TIDSP00011985 (Addition of new API EDMA3_DRV_disableLogicalChannel API in EDMA3 Driver) implemented.

b) IRs# SDOCM00058021,

SDOCM00058057, SDOCM00058147 and SDOCM00058401 fixed.

See release notes for more information.

01.10.00.01

May 11, 2009 Anuj

Aggarwal

a) Add support for new platforms: C6748,

OMAPL138, DRA44x and DRX45x.

01.07.00.01

November 4, 2008

Anuj Aggarwal

a) Added support for new platforms. b) IR SDOCM00049778 is fixed. See release notes for more information.

01.06.00.01

March 20, 2008

Anuj Aggarwal

a) Added support for new platforms. b) MRs DPSP00010071, DPSP00010187,

DPSP00010479 and DPSP00010480 are fixed.

See release notes for more information.

1.05.00.01

January 28, 2008

Anuj Aggarwal

a) Header files modified to have extern "C"

declarations.

b) Implemented ECNs DPSP00009815 &

DPSP00010035.

1.04.00.01

January 9, 2008

Anuj Aggarwal

a) MR# DPSP00009788 has been fixed in

this release. See Release Notes for more information.

1.03.01.01

October 21, 2007

Anuj Aggarwal

a) C6452 support has been added in this

release. Now C6452 applications can also be built in the RTSC environment.

b) All the CCS PJT files now come under two

flavors: one for the RTSC environment and the other for the non-RTSC environment.

c) IOCTL interface has been added in the

EDMA3 Driver.

d) MRs DPSP00009099, DPSP00009190 and

DPSP00009213 Fixed. See Release Notes for more information.

1.03.00.01

Read This First

viii

September 28, 2007

Anuj Aggarwal

a) Added support for DM6467 platform. b) MRs DPSP00009060, DPSP00009063,

DPSP00009093 and DPSP00009100 Fixed. See Release Notes for more information.

1.02.00.01

September 14, 2007

Anuj Aggarwal

a) Moved the platform specific configuration

to the Resource Manager. b) Modified the chaining API. c) Divided the sample app into sample

initialization library and the standalone

sample application.

1.01.00.01

July 11, 2007 Anuj

Aggarwal

a) Modified the DSP/BIOS version number. b) Modified the Driver directory structure as per RTSC standard.

1.00.00.03

June 18, 2007 Anuj

Aggarwal

a) Made the EDMA3 package RTSC

compliant.

1.00.00.02

May 14, 2007 Anuj

Aggarwal

a) MR# DPSP00007858 (Issue in EDMA3

DRV causes false missed events) Fixed.

1.0.0.1

May 9, 2007 Anuj

Aggarwal

a) MR# DPSP00007800 (Result of resource allocation is over-written by the semaphore release result in EDMA3 Resource Manager) Fixed. b) MR# DPSP00007803 (Exit from EDMA3_RM_allocContiguousResource () in case of error is incorrect) Fixed.

1.0.0

Apr 23, 2007 Anuj

Aggarwal

a) New APIs to support POLL mode provided. b) API to set CC Register provided. c) Sample application made generic and more test cases added.

0.3.2

Mar 23, 2007 Anuj

Aggarwal

a) DMA/QDMA channel event missed issue fixed.

0.3.1

Mar 6, 2007 Anuj

Aggarwal

a) Renamed EDMA3_DVR to EDMA3_DRV. b) IPR bit clearing in RM ISR issue fixed. c) Sample application made generic.

0.3.0

Jan 16, 2007 Anuj

Aggarwal

Critical section handling code modification. Uses semaphore and interrupts disabling mechanism for resources sharing.

0.2.2

Nov 14, 2006 Anuj

Aggarwal

Made EDMA3 Driver OS Independent. Also, more run time configuration is possible now.

0.2.1

Contents

Read This First............................................................................................................ iii

About This Manual..........................................................................................................iii

.iii

Terms and Abbreviations ............................................................................................. iv

Notations v

Information about Cautions and Warnings ................................................................ v

Related Documentation................................................................................................ vi

Trademarks vi

Revision History.............................................................................................................vii

Contents........................................................................................................................ ix

Tables............................................................................................................................. xi

EDMA3 Driver Introduction...............................................................................0-1-1

1.1 Overview ...........................................................................................0-1-2

1.1.1 System Partitioning .................................................................................0-1-2

1.1.2 Supported Services .................................................................................0-1-6

Installation Guide.................................................................................................1-2-1

2.1 Component Folder ...........................................................................1-2-2

2.2 Development Tools Environment(s) .............................................1-2-4

2.2.1 Development Tools..................................................................................1-2-4

2.3 Installation guide .............................................................................1-2-5

2.3.1 Installation and Usage Procedure..........................................................1-2-5

2.3.2 Un-installation ..........................................................................................1-2-5

2.4 Integration Guide.............................................................................1-2-6

2.4.1 Building EDMA3 Libraries........................................................................1-2-6

2.4.2 Building the EDMA3 Driver Stand-alone Applications.........................1-2-6

2.4.3 Building the DAT Example......................................................................1-2-7

2.4.4 Build Options ............................................................................................1-2-8

Run-Time Interfaces/Integration Guide..................................................... 2-A-1

3.1 Symbolic Constants and Enumerated Data types ..................... 2-A-2

3.2 Data Structures............................................................................. 2-A-13

3.2.1 EDMA3_DRV_GblConfigParams .......................................................... 2-A-13

3.2.2 EDMA3_DRV_InstanceInitConfig ........................................................ 2-A-16

3.2.3 EDMA3_DRV_InitConfig....................................................................... 2-A-18

3.2.4 EDMA3_DRV_MiscParam...................................................................... 2-A-19

3.2.5 EDMA3_DRV_ChainOptions................................................................. 2-A-20

3.2.6 EDMA3_DRV_PaRAMRegs.................................................................... 2-A-21

3.2.7 EDMA3_DRV_EvtQuePriority............................................................... 2-A-23

3.3 API Specification ........................................................................... 2-A-24

3.3.1 Creation.................................................................................................. 2-A-25

3.3.2 Configuration......................................................................................... 2-A-27

3.3.3 Control.................................................................................................... 2-A-29

3.3.4 Termination ........................................................................................... 2-A-68

3.4 EDMA3 Driver Initialization ......................................................... 2-A-71

Contents

3.5 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

3.6 API Usage Example ...................................................................... 2-A-78

EDMA3 Driver Porting ...................................................................................... 3-A-84

3.7 Getting Started.............................................................................. 3-A-85

3.8 Step-by-Step procedure for porting .......................................... 3-A-87

3.8.1 edma3_<PLATFORM_NAME>_cfg.c:.................................................. 3-A-87

3.8.2 edma3_rm_bios_<PLATFORM_NAME>_lib.pjt................................. 3-A-88

3.8.3 OS-dependent (sample) Implementation ......................................... 3-A-89

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

1-1

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

Driver

Deployment.

EDMA3 Driver Introduction

1-2

1.1 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. It supports EDMA as well as QDMA channels for data transfer. This peripheral IP is being re-used in different SoCs with only a few configuration changes like number of DMA and QDMA channels supported, number of PARAM sets available, number of event queues and transfer controllers etc.

The EDMA3 peripheral is used by other peripherals for their DMA needs thus the EDMA3 Driver needs to cater to the requirements of device drivers of these peripherals as well as other application software that may need to use the 3

party DMA services.

The

EDMA3 Driver provides functionality that allows device drivers and applications for submitting and synchronizing with EDMA3 based DMA transfers. In order to simplify the usage, this component internally uses the services of the

EDMA3 Resource Manager and provides one

consistent interface for applications or device drivers.

The

EDMA3 Resource Manager comprises of the following two parts:

 Physical Driver: This component is responsible for the management

of several resources within the EDMA3 peripheral like DMA and QDMA channels, TCC codes, PARAM entry, all global EDMA3 registers, queues etc.

 Interrupt Manager: This module provides the different interrupt

handlers (ISRs) for various EDMA3 interrupts like transfer completion interrupt, CC error interrupt and TC error interrupt. Since interrupts could be associated with TCC codes in EDMA3, this module also provides the functionality of accepting application registration callbacks for TCC codes and calls the callback functions upon receipt of the given interrupt (TCC).

Moreover, these ISRs are NOT registered with the underlying OS, since Resource Manager is an OS-agnostic module. The user application has to do the registration / un-registration of ISRs by itself.

EDMA3 Driver Introduction

I-1-3

Figure 1: EDMA3 Related Software Product and Packages Structure

Dependency

EDMA3 Resource Manager

PaRAMs

DMA/QDMA

Channels

TCCs

EDMA3

ISRs

EDMA3 Driver

Internally calls

EDMA3 Product

PSP Drivers

CSL/DAT

Framework Components

DMAN

ACPY

Applications

EDMA3 Driver Introduction

1-4

Typically, each master (ARM, DSP etc.) within the SoC shall open an instance of EDMA3 Driver, which internally will open a Resource Manager Instance. Resources could be allocated statically or dynamically to the EDMA3 Driver Instance. This

Figure 2: EDMA3 Related Software Product and Packages Structure

EDMA3 Driver Instance should be used by the users (device drivers or applications) to call all other EDMA3 Driver APIs. This instance will use the appropriate shadow region registers (specific to its master) to program EDMA3 hardware. Please note that the shadow region registers are master specific and there is only and only one set of shadow region registers for each master. If a master tries to program EDMA3 using other sets of shadow region registers (tied to other masters in the system), it could result in unexpected behavior with the possible loss of EDMA3 interrupts and EDMA3 resources’ conflict. So it should be avoided in normal circumstances.

EDMA3 Driver doesn’t allow multiple instances for a single master on the respective shadow region. It permits only one instance for each master which will be tied to its specific shadow region. This is done to prevent any potential problem which could arise due to EDMA3 resources’ conflict among these different instances.

However, it is possible to have multiple EDMA3 Driver Instances, running on the same processor. These different EDMA3 Driver instances would be tied to different masters (and hence different shadow regions) to cater their specific requests. 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 OR EDMA3 Driver) as desired.

Callback Notification Service Call Link between EDMA3 instances

SoC

Processor 1 (e.g

ARM)

Driver 1... NApp NApp 1

EDMA3

Driver

EDMA3 Product

EDMA3 Res Mgr

Phy Res

Mgr

Int

Mgr

Processor

(e.g.DSP

)

Driver 1.. NApp NApp 1

EDMA3

Driver

EDMA3 Product

EDMA3 Res Mgr

Phy Res

Mgr

Int

Mgr

EDMA3 Driver Introduction

I-1-5

EDMA3 Driver Introduction

1-6

1.1.2 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),

 DMA Channel (NOT mapped to a hardware sync event),

 QDMA Channel, and

 Link Channel (a PARAM Set in EDMA3).

1.1.2.2 Programs DMA channel: It provides an interface that applications or device drivers can use to program a DMA transaction. This typically involves setting the DMA source and destination parameters.

Following types of transactions are supported:

• Event triggered (peripheral driven transfers),

• Chain triggered (issuing a chain of transfers initiated by single

event),

• Manual triggered (CPU generated sync-event), and

• QDMA transfer (triggered on a write to the QDMA Trigger word).

EDMA3 Driver Introduction

I-1-7

1.1.2.3 Start and Synchronize with DMA transfers: It provides an interface that applications or device drivers can use to start and synchronize with a DMA transaction.

1.1.2.4 Provides DMA transaction completion callback to applications: It provides an interface that applications or device drivers can use to register a transaction completion (final or intermediate) callback or error interrupt callback. EDMA3 driver calls this application or device driver specifc callback routine, with the appropriate status message.

1.1.2.5 Supports Linking and chaining feature: EDMA3 peripheral provides linking and chaining capabilities. EDMA driver provides an interface that applications or device drivers can use to use this functionality.

1.1.2.6 Supports multiple instances of EDMA driver on a single processor: It supports multiple instances of itself, running on the same processor, but tied to different masters (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.

1.1.2.7 Read/Write a specific CC register: It also provides an interface which enables users to read/write any EDMA3 Channel Controller register. These APIs are for advanced users and could be used for debugging purposes.

1.1.2.8 Support for Polled Mode DMA Transfers: It provides an interface which enables the application or device driver to use it in an interrupt-less (and further in an OS-less) environment. In this scenario, the application does not register the callback function with the resource manager and itself polls the EDMA3 hardware for the completion interrupt, using the specific APIs.

1.1.2.9 Non-RTSC Environment Support: EDMA3 Driver module should gets built in non-RTSC environment also. All the CCS PJT files should come for non-RTSC environment too.

1.1.2.10 IOCTL interface support: EDMA3 Driver shall provide an IOCTL interface for toggling the option whether PaRAM Sets should be cleared during allocation or not. This interface could also be extended in future for other misc requirements.

2-1

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.

Installation Guide

2-2

2.1 Component Folder

Upon installing the EDMA3 Driver, the following directory structure is found in the main directory.

Figure 3: EDMA3 Driver Directory Structure

The sections below describe the folder contents:

edma3_lld_<<version_number>>

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.

Installation Guide

I-2-3

packages

All components (Driver, Resource Manager, sample OS-abstraction layers etc) fall under packages/ti/sdo/edma3 directory, under their individual directories. For e.g., EDMA3 Driver lies under packages/ti/sdo/edma3/drv folder, sample initialization library for EDMA3 Driver lies under packages/ti/sdo/edma3/drv/sample folder etc.

drv -> Top level folder for the EDMA3 Driver.

drv\build -> Build environment related files (PJT, TCF etc) for all the supported platforms.

o drv\build\ccs3: Build files for CCSv3

o drv\build\ccs4: Build files for CCSv4

o drv\build\eBinder: Build files for eBinder

drv\docs -> User guide, datasheet etc.

drv\lib -> EDMA3 Driver libraries for all the supported platforms.

drv\sample -> Sample code for how to use the EDMA3 Driver, along-with the pre-built libraries for the same.

o drv\sample\build: Build files for CCSv3/CCSv4/eBinder

o drv\sample\lib: Pre-built libraries for EDMA3 driver

sample initialization code

o drv\sample\src: Source code for EDMA3 driver sample

initialization

drv\src -> Source files for EDMA3 Driver.

Just to clarify, the

sample folder inside the edma3\drv folder DOESNOT

contain the sample applications. It provides the:

 Sample initialization code to properly configure the EDMA3 hardware,

and,

 Sample OS abstraction layer to provide the OS-specific hooks to the

EDMA3 package.

This sample code is provided for reference purpose only. To start with, the user is advised to use the sample code/library as it is, and later modify/create his own initialization code, as per the requirements.

The stand-alone applications are provided in the top level

examples folder as mentioned above. Please note that these examples use the above mentioned sample initialization/OS abstraction libraries and the EDMA3 Driver libraries.

Installation Guide

2-4

2.2 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. Including: 3rd party components/ libraries, Operating system and auxiliary Tools

Table 1: Development Tools/components

Development

tool/ component

Version Comments

Code Composer Studio (CCS)

3.3.80.11 (service release 10) IDE

DSP BIOS 5.41.01.09 Operating System XDC tool chain 3.16.00.18 RTSC tools Code Generation Tools

6.1.9 Code generation toolchain

eBinder 1.7 IDE PrKernel Version 4 Operating System

Installation Guide

I-2-5

2.3 Installation guide

This section describes the EDMA3 LLD installation and un-installation.

2.3.1 Installation and Usage Procedure

1) Install the products mentioned in the development tools requirements section, as per instructions provided along with the products.

2) Install the EDMA3 package using the self-extracting installer into preferred drive/folder. It is recommended to install the EDMA3 LLD into the default drive/folder as indicated by the self-extracting installer.

3) As a part of installation process, an environment variable “EDMA3LLD_BIOS5_INSTALLDIR” is created with its value as the current EDMA3 installation directory. Moreover, in case the variable exists prior to this installation, the same will be updated with the current (latest) EDMA3 installation directory. This environment variable can be used by other users of EDMA3 package for e.g. BIOS PSP Drivers package.

4) For building the downloadable images, refer to section 2.4 – Integration 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.

Installation Guide

2-6

2.4 Integration Guide

This section describes the EDMA3 LLD package usage. The package provides prebuilt libraries for all the different components: EDMA3 Driver, Resource Manager along with their sample initialization libraries. Moreover, demo applications are also provided to check the basic functionality for the supported components.

2.4.1 Building EDMA3 Libraries

The EDMA3 package contains pre-built libraries for all EDMA3 components. But user can also build them by following the below mentioned steps in case of source code modification or some other specific use cases described below.

For CCSv3: Use CCSv3 project files located in drv\build\ccs3\ folder to build the EDMA3 Driver libraries. Use CCSv3 project files located in drv\sample\build\<<platform_name>>\ccs3\ folder to build the EDMA3 Driver Sample Initialization libraries.

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 the desired target – C64P or C674X. Similarly, projects located in drv\sample\build\<<platform_name>>\ccs4\ folder needs to be imported via CCSv4 into a workspace to build the EDMA3 Driver Sample Initialization libraries for the desired platform.

2.4.2 Building the EDMA3 Driver Stand-alone Applications

The EDMA3 package contains separate sample applications for EDMA3 Driver for each of the supported platforms. Following steps are required to build the same:

For CCSv3: Use CCSv3 project files located in examples\edma3_driver\<<platform_name>>\ccs3\ folder to build the EDMA3 Driver examples.

For CCSv4: Projects located in examples\edma3_driver\<<platform_name>>\ccs4\ folder needs to be imported via CCSv4 into a workspace to build the EDMA3 Driver examples for the desired platform.

NOTES:

1. The following environmental variables must be set

a. XDCPATH –

Should include BIOS v5 package installation directory, in

case user is working in RTSC environment.

Example:

XDCPATH= D:/Program Files/Texas Instruments/bios_5_41_00_06_eng/packages

Installation Guide

I-2-7

2.4.3 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.

Installation Guide

2-8

2.4.4 Build Options

This section enumerates and describes alongside each of the allowed build options. It also tells the default configurations available.

Build option Reference Default Configuration Description

EDMA3_INSTRUMENTATIO N_ENABLED

Instrumentation disabled

To enable/disable Real Time Instrumentation support.

EDMA3_DRV_PARAM_CHE CK_DISABLE

Parameter checking enabled (public APIs)

Disable parameter checking for public APIs, if required. See note 1 below.

NDEBUG Parameter checking enabled

(private functions)

Disable parameter checking for private functions, if required. See note 2 below.

_DEBUG _DEBUG (Debug mode)

To select DEBUG mode.

_RELEASE _RELEASE (Release mode)

To select RELEASE mode.

pdr pdr (Release / Debug Mode)

To select the option “Issues remarks (non-serious warnings)”, which are suppressed by default.

o2 o2 (Release Mode)

To choose O2 level of optimization.

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. the CCSv3 project file), and re-build the libraries. By default, the parameter checking is enabled for all the public APIs.

Note 2: All EDMA3 private functions use the standard C assert mechanism to enable/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. the CCSv3 project file), and rebuild the libraries. By default, the parameter checking is enabled for all the private functions.

A-1

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.

Run-Time Interfaces/Integration Guide

A-2

3.1 Symbolic Constants and Enumerated Data types

This section summarizes all the symbolic constants specified as either #define macros and/or enumerated C data types. Described alongside the macro or enumeration is the semantics or interpretation of the same in terms of what value it stands for and what it means.

Table 3: Symbolic Constants and Enumerated Data types Table for common header file edma3_common.h

Group or Enumeration Class

Symbolic Constant Name Description or Evaluation

Driver Global Defines

EDMA3_DRV_DEBUG This define is used to

enable/disable EDMA3 Driver debug messages

EDMA3_DRV_PRINTF If EDMA3_DRV_DEBUG is defined,

EDMA3_DRV_PRINTF will be used to print the debug messages on the user specified output.

EDMA3_DRV_SOK EDMA3 Driver Result OK

EDMA3_OSSEM_NO_TIMEOUT This define is used to specify a

blocking call without timeout while requesting a semaphore.

EDMA3_MAX_ EDMA3_INSTANCES

Maximum EDMA3 Controllers on the SoC

EDMA3_MAX_DMA_CH Maximum DMA channels supported

by the EDMA3 Controller

EDMA3_MAX_QDMA_CH Maximum QDMA channels

supported by the EDMA3 Controller

EDMA3_MAX_PARAM_SETS Maximum PaRAM Sets supported

by the EDMA3 Controller

EDMA3_MAX_LOGICAL_CH Maximum Logical channels

supported by the EDMA3 Package

EDMA3_MAX_TCC Maximum TCCs (Interrupt

Channels) supported by the EDMA3 Controller

EDMA3_MAX_EVT_QUE Maximum Event Queues supported

by the EDMA3 Controller

EDMA3_MAX_TC Maximum Transfer Controllers

supported by the EDMA3 Controller

EDMA3_MAX_REGIONS Maximum Shadow Regions

supported by the EDMA3 Controller

Defines used to

support the maximum

resources supported

by the EDMA3

controller. These are

used to allocate the

maximum memory

for different data

structures of the

EDMA3 Driver and

Resource Manager.

EDMA3_MAX_DMA_CHAN_DWRDS Maximum Words (4-bytes region)

+ 101 hidden pages

Texas Instruments EDMA3 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual