Texas Instruments EDMA3 User manual

May 2013
Document Version 02.11.07.XX
EDMA3 Resource Manager
U s e r ' s G u i d e
User Guide

ii
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 license, 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 services 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 party 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
Copyright © 2009, Texas Instruments Incorporated
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 Resource Manager Version
02.11.07.XX. This manual provides necessary information
regarding how to effectively install, build and use EDMA3
Resource Manager in user systems and applications.
This manual provides details regarding how the EDMA3
Resource Manager 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 Resource Manager. Also included are appendix sections
on related Glossary, Web sites and Pointers for gathering further
information on the EDMA3 Resource Manager.

iv
Terms and Abbreviations
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
v
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.
Related Documentation
Internal
EDMA3 Channel Controller (TPCC), version 3.0.2 (Available at
PDS)
EDMA3 Transfer Controller (TPTC), version 3.0.1 (Available at
PDS)
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.

vi
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
October 16,
2008
Anuj
Aggarwal
First release supporting platform DA830
on BIOS 6.
02.00.00.XX
June 3, 2009 Anuj
Aggarwal
Patch release for DA830 platform on
BIOS 6.
02.00.01.XX
December 7,
2009
Anuj
Aggarwal
a) Migration to new BSD license
b) Added support for TCI6498 platform.
See release notes for more details.
02.10.00.XX
April 9,2010 Imtiaz SMA Added support for the C6748 and
OMAPL138 platforms. See release notes
for more details.
02.10.01.XX
May 12,
2010
Vinay K
Nooji
Added support for the OMAPL138 ARM
platform. See release notes for more
details.
02.10.02.XX
Sep 6, 2010 Sundaram
Raju
Support for the TI816X Simulator &
platform, C6472 & TCI6486 platform
and TI814X platform have been added.
02.10.03.XX
Oct 12, 2010 Sundaram
Raju
Support for C66x(ELF) in Generic
library of Resource Manager and bug
fixes
02.10.04.XX
Feb 02, 2011 Sundaram
Raju
Support for Make based build for all the
libraries and sample applications
02.11.00.XX
Feb 15, 2011 Raghu
Nambiath
Sundaram
Raju
Additional support for C66x platforms
TCI6608/TCI6616/C6670/C6678
02.11.01.XX
Apr 8, 2011 Prasad
Konnur
Addition of TI816x-m3vpss and TI816x-
m3video platform to EDMA3LLD 02.11.02.XX
Nov 15,
2011
Prasad
Konnur
Addition of M3 support for TI814X and
A8 support for TI816X and bug fixes 02.11.03.XX
Jan 27, 2012 Murtaza
Gaadiwala
Addition of Appleton (TCI6614) support 02.11.04.XX
Mar 9, 2012 Prasad Addition of TI811X platform support 02.11.05.01

viii
Aug 10,
2012
Prasad
Konnur
Bug Fixes 02.11.06.01
May 13,
2013
Prasad
Konnur
Addition of TDA2XX support 02.11.07.03
May 17,
2013
Murtaza
Gaadiwala
Addition of TCI6638K2K support 02.11.07.04

Contents
ix
Contents
Read This First ............................................................................................................ iii
About This Manual ..........................................................................................................iii
Terms and Abbreviations ............................................................................................. iv
Notations v
Information about Cautions and Warnings ................................................................ v
Related Documentation ................................................................................................. v
Internal v
Trademarks vi
Revision History .............................................................................................................vii
Contents........................................................................................................................ ix
Tables............................................................................................................................. xi
EDMA3 Resource Manager Introduction..........................................................1-1
1.1 Overview...............................................................................................1-2
1.1.1 System Partitioning.................................................................................... 1-2
1.1.2 Supported Services.................................................................................... 1-3
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 Build Options............................................................................................ 1-2-8
Run-Time Interfaces/Integration Guide.........................................................2-1
3.1 Symbolic Constants and Enumerated Data types .........................2-2
3.2 Data Structures.................................................................................2-12
3.2.1 RM Global Error Callback......................................................................... 2-12
3.2.2 EDMA3_RM_GblErrCallbackParams ....................................................... 2-12
3.2.3 EDMA3_RM_GblConfigParams................................................................ 2-12
3.2.4 EDMA3_RM_InstanceInitConfig.............................................................. 2-14
3.2.5 EDMA3_RM_Param................................................................................... 2-17
3.2.6 EDMA3_RM_MiscParam ........................................................................... 2-17
3.2.7 EDMA3_RM_GblXbarToChanConfigParams........................................... 2-17
3.2.8 EDMA3_RM_ResDesc ............................................................................... 2-18
3.3 API Specification ...............................................................................2-21
3.4 API Usage Example...........................................................................2-22
EDMA3 Resource Manager Porting ..................................................................3-31
4.1 Getting Started..................................................................................3-32
4.2 Step-by-Step procedure for porting ..............................................3-34

x
4.2.1 edma3_<PLATFORM_NAME>_cfg.c:......................................................3-34
4.2.2 Make file for the Resource Manager.......................................................3-35

Tables
xi
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-2
Table 4: Symbolic Constants and Enumerated Data types Table for
EDMA3 Resource Manager Header file edma3_rm.h...........................2-4

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

1-2
1.1 Overview
This section describes the functional scope of the EDMA3
Resource Manager 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 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 3rd party DMA services.
The EDMA3 Resource Manager comprises of the following two
parts:
Physical Resource Manager: This component is responsible
for the management of several resources within the EDMA3
peripheral like TCC codes, PARAM entry, DMA and QDMA
channels, all global EDMA3 registers, queues etc.
Interrupt Manager: This component handles EDMA3
interrupts, which are registered with the underlying OS
interrupt handling mechanism by the user. Since interrupts
are associated with TCC codes in EDMA3 module, this module
provides the functionality of accepting application registration
callbacks for TCC codes and calls the callback functions upon
receipt of the given interrupt (TCC). Note that the
application/driver using the EDMA3 Resource Manager has to
register/unregister the Interrupt Handlers with the underlying
operating system. The Resource Manager does not do this by
itself.

EDMA3 Resource Manager Introduction
I-1-3
1.1.2 Supported Services
Following are the services provided by the Physical Resource
Manager:
1.1.2.1 Allocation/de-allocation of EDMA3 resources: It provides interfaces that
allow applications to allocate and free EDMA3 resources:
EDMA channels
QDMA channels
PARAM Entries
TCC

1-4
These resources shall be provided to the instance of the resource manager at
run time.
1.1.2.2 Global EDMA3 settings configuration: It provides an interface that can be
used by applications to configure global EDMA3 settings. For e.g. number of
resources (DMA/QDMA channels, TCCs, PaRAM sets) available, number of
Transfer controllers, queue priorities etc.
1.1.2.3 Binding of specific EDMA3 resources: It provides an interface that can be
used by applications to bind specific EDMA3 resources like EDMA or QDMA
channel with PaRAM Set entries.
1.1.2.4 Multiple RM Instances Support: It supports multiple instances of the
Resource Manager, running on the same processor, but managing
same/different sets of resources and tied to same/different shadow regions.
1.1.2.5 Read/Write a specific CC register: It provides APIs to read as well as write
on a specific Channel Controller Register.
1.1.2.6 Non-RTSC Environment Support: Resource Manager module should gets
built in non-RTSC environment also. All the CCS PJT files should come for non-
RTSC environment too.
1.1.2.7 IOCTL interface support: EDMA3 Resource Manager 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.
1.1.2.8 Provides Poll mode support: It also provides APIs which could be used by
users, working in Poll Mode. These users don’t rely upon the trasnfer
completion interrupts generated by the Channel controller, and instead, Poll
the IPR/IPRH register for the transfer completion interrupt bit.
1.1.2.9 Big Endian platforms support: EDMA3 Resource Manager can also be used
for big endian platforms.
Following are the services provided by the Interrupt Manager:

EDMA3 Resource Manager Introduction
I-1-5
1.1.2.10 Error Interrupts Handling: It also handles error interrupts and
depending upon the nature of error, either calls a global application callback
or TCC callback with the appropriate error status. It provides APIs to
register/unregister these error interrupt handlers.
1.1.2.11 Registration and Un-registration of TCC callbacks: It provides
an interface that can be called by applications to register/un-register for TCC
callbacks. It handles EDMA3 interrupts and calls the respective TCC callback
function with appropriate status.
1.1.2.12 Map Cross bar events to the DMA channels: It provides and
interface than can be used to map the cross bar mapped events to the specific
DMA channel.

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

2-2
2.1 Component Folder
Upon installing the EDMA3 Resource Manager, the following
directory structure is found in the main directory.
Figure 1: EDMA3 Resource Manager 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.
eclipse
Contains eclipse related files for CCSv4.
examples
Contains the stand-alone applications for EDMA3 Driver
(for all the supported platforms) and the DAT example.