Texas Instruments TMS320 DSP User manual

TMS320 DSP Algorithm Standard
Rules and Guidelines
User's Guide
Literature Number: SPRU352GJune 2005 – Revised February 2007

2 SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

Contents
Preface ............................................................................................................................... 7
1 Overview ................................................................................................................... 91.1 Scope of the Standard ............................................................................................ 101.1.1 Rules and Guidelines .................................................................................... 111.2 Requirements of the Standard .................................................................................. 111.3 Goals of the Standard ............................................................................................ 121.4 Intentional Omissions ............................................................................................ 121.5 System Architecture ............................................................................................... 131.5.1 Frameworks ............................................................................................... 131.5.2 Algorithms ................................................................................................. 141.5.3 Core Run-Time Support ................................................................................. 14
2 General Programming Guidelines ............................................................................... 152.1 Use of C Language ............................................................................................... 162.2 Threads and Reentrancy ......................................................................................... 162.2.1 Threads .................................................................................................... 162.2.2 Preemptive vs. Non-Preemptive Multitasking......................................................... 172.2.3 Reentrancy ................................................................................................ 172.2.4 Example ................................................................................................... 182.3 Data Memory....................................................................................................... 192.3.1 Memory Spaces .......................................................................................... 202.3.2 Scratch versus Persistent ............................................................................... 202.3.3 Algorithm versus Application ............................................................................ 222.4 Program Memory ................................................................................................. 232.5 ROM-ability ........................................................................................................ 232.6 Use of Peripherals ................................................................................................ 24
3 Algorithm Component Model ..................................................................................... 253.1 Interfaces and Modules ........................................................................................... 263.1.1 External Identifiers ....................................................................................... 273.1.2 Naming Conventions ..................................................................................... 283.1.3 Module Initialization and Finalization .................................................................. 283.1.4 Module Instance Objects ................................................................................ 283.1.5 Design-Time Object Creation ........................................................................... 293.1.6 Run-Time Object Creation and Deletion .............................................................. 293.1.7 Module Configuration .................................................................................... 303.1.8 Example Module .......................................................................................... 303.1.9 Multiple Interface Support ............................................................................... 313.1.10 Interface Inheritance .................................................................................... 323.1.11 Summary ................................................................................................. 323.2 Algorithms .......................................................................................................... 333.3 Packaging .......................................................................................................... 343.3.1 Object Code ............................................................................................... 343.3.2 Header Files .............................................................................................. 353.3.3 Debug Verses Release .................................................................................. 35
SPRU352G – June 2005 – Revised February 2007 Contents 3Submit Documentation Feedback

4 Algorithm Performance Characterization ..................................................................... 374.1 Data Memory....................................................................................................... 384.1.1 Heap Memory ............................................................................................. 384.1.2 Stack Memory ............................................................................................ 394.1.3 Static Local and Global Data Memory ................................................................. 394.2 Program Memory .................................................................................................. 404.3 Interrupt Latency .................................................................................................. 414.4 Execution Time .................................................................................................... 414.4.1 MIPS Is Not Enough ..................................................................................... 414.4.2 Execution Time Model ................................................................................... 42
5 DSP-Specific Guidelines ............................................................................................ 455.1 CPU Register Types .............................................................................................. 465.2 Use of Floating Point .............................................................................................. 475.3 TMS320C6xxx Rules and Guidelines........................................................................... 475.3.1 Endian Byte Ordering .................................................................................... 475.3.2 Data Models ............................................................................................... 475.3.3 Program Model ........................................................................................... 475.3.4 Register Conventions .................................................................................... 485.3.5 Status Register ........................................................................................... 485.3.6 Interrupt Latency ......................................................................................... 495.4 TMS320C54xx Rules and Guidelines .......................................................................... 495.4.1 Data Models ............................................................................................... 495.4.2 Program Models .......................................................................................... 495.4.3 Register Conventions .................................................................................... 515.4.4 Status Registers .......................................................................................... 515.4.5 Interrupt Latency ......................................................................................... 525.5 TMS320C55x Rules and Guidelines ............................................................................ 525.5.1 Stack Architecture ........................................................................................ 525.5.2 Data Models ............................................................................................... 525.5.3 Program Models .......................................................................................... 535.5.4 Relocatability .............................................................................................. 535.5.5 Register Conventions .................................................................................... 545.5.6 Status Bits ................................................................................................. 555.6 TMS320C24xx Guidelines ....................................................................................... 575.6.1 General .................................................................................................... 575.6.2 Data Models ............................................................................................... 575.6.3 Program Models .......................................................................................... 575.6.4 Register Conventions .................................................................................... 575.6.5 Status Registers .......................................................................................... 585.6.6 Interrupt Latency ......................................................................................... 585.7 TMS320C28x Rules and Guidelines ............................................................................ 585.7.1 Data Models ............................................................................................... 585.7.2 Program Models .......................................................................................... 595.7.3 Register Conventions .................................................................................... 595.7.4 Status Registers .......................................................................................... 595.7.5 Interrupt Latency ......................................................................................... 60
6 Use of the DMA Resource .......................................................................................... 616.1 Overview ............................................................................................................ 62
4Contents SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

6.2 Algorithm and Framework ........................................................................................ 626.3 Requirements for the Use of the DMA Resource ............................................................. 636.4 Logical Channel ................................................................................................... 636.5 Data Transfer Properties ......................................................................................... 646.6 Data Transfer Synchronization .................................................................................. 646.7 Abstract Interface .................................................................................................. 656.8 Resource Characterization ....................................................................................... 666.9 Runtime APIs ...................................................................................................... 676.10 Strong Ordering of DMA Transfer Requests ................................................................... 676.11 Submitting DMA Transfer Requests ............................................................................ 686.12 Device Independent DMA Optimization Guideline ............................................................ 686.13 C6xxx Specific DMA Rules and Guidelines .................................................................... 696.13.1 Cache Coherency Issues for Algorithm Producers ................................................. 696.14 C55x Specific DMA Rules and Guidelines ..................................................................... 706.14.1 Supporting Packed/Burst Mode DMA Transfers .................................................... 706.14.2 Minimizing Logical Channel Reconfiguration Overhead ........................................... 716.14.3 Addressing Automatic Endianism Conversion Issues ............................................. 716.15 Inter-Algorithm Synchronization ................................................................................. 716.15.1 Non-Preemptive System ............................................................................... 716.15.3 Preemptive System ..................................................................................... 72
A Rules and Guidelines ................................................................................................ 75A.1 General Rules ..................................................................................................... 76A.2 Performance Characterization Rules ........................................................................... 77A.3 DMA Rules ......................................................................................................... 77A.4 General Guidelines ................................................................................................ 78A.5 DMA Guidelines ................................................................................................... 79
B Core Run-Time APIs ................................................................................................. 81B.1 TI C-Language Run-Time Support Library ..................................................................... 82B.2 DSP/BIOS Run-time Support Library ........................................................................... 82
C Bibliography ............................................................................................................ 83C.1 Books ............................................................................................................... 83C.2 URLS ................................................................................................................ 83
D Glossary .................................................................................................................. 85D.1 Glossary of Terms ................................................................................................. 85
SPRU352G – June 2005 – Revised February 2007 Contents 5Submit Documentation Feedback

List of Figures
1-1 TMS320 DSP Algorithm Standard Elements ........................................................................... 101-2 DSP Software Architecture ................................................................................................ 132-1 Scratch vs Persistent Memory Allocation ............................................................................... 212-2 Data Memory Types ....................................................................................................... 223-1 Module Interface and Implementation ................................................................................... 263-2 Module Object Creation ................................................................................................... 293-3 Example Module Object ................................................................................................... 293-4 Example Implementation of IALG Interface ............................................................................. 334-1 Execution Timeline for Two Periodic Tasks ............................................................................ 425-1 Register Types .............................................................................................................. 466-1 Transfer Properties for a 1-D Frame ..................................................................................... 646-2 Frame Index and 2-D Transfer of N-1 Frames ......................................................................... 64
6List of Figures SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

PrefaceSPRU352G – June 2005 – Revised February 2007
Read This First
This document defines a set of requirements for DSP algorithms that, if followed, allowsystem integrators to quickly assemble production-quality systems from one or moresuch algorithms. Thus, this standard is intended to enable a rich commercialoff-the-shelf (COTS) marketplace for DSP algorithm technology and to significantlyreduce the time-to-market for new DSP-based products.
The TMS320 DSP Algorithm Standard is part of TI's eXpressDSP technology initiative.Algorithms that comply with the standard are tested and awarded an"eXpressDSP-compliant" mark upon successful completion of the test.
In describing these requirements and their purpose, it is often necessary to describehow applications might be structured to take advantage of eXpressDSP-compliantalgorithms. It is important to keep in mind, however, that the TMS320 DSP AlgorithmStandards make no substantive demands on the clients of these algorithms.
Intended Audience
This document assumes that the reader is fluent in the C programming language, has a good workingknowledge of digital signal processing (DSP) and the requirements of DSP applications, and has someexposure to the principles and practices of object-oriented programming.
This document describes the rules that must be followed by all eXpressDSP-compliant algorithm softwareand interfaces between algorithms and applications that use these algorithms. There are two audiencesfor this document:
•Algorithm writers learn how to ensure that an algorithm can coexist with other algorithms in a singlesystem and how to package an algorithm for deployment into a wide variety of systems.•System integrators learn how to incorporate multiple algorithms from separate sources into a completesystem.
Document Overview
Throughout this document, the rules and guidelines of the TMS320 DSP Algorithm Standard (referred toas XDAIS) are highlighted. Rules must be followed to be compliant with the TMS320 DSP AlgorithmStandard Guidelines. Guidelines should be obeyed but may be violated by eXpressDSP-compliantsoftware. A complete list of all rules and guidelines is provided in Appendix A. Electronic versions of thisdocument contain hyperlinks from each rule and guideline in Appendix A to the main body of thedocument.
This document contains the following chapters:•Chapter 1 - Overview, provides the motivation for the standard and describes how algorithms (asdefined by the TMS320 DSP Algorithm Standard) are used in DSP systems.•Chapter 2 - General Programming Guidelines, describes a general programming model for DSPsoftware and contains rules and guidelines that apply to all eXpressDSP-compliant software.•Chapter 3 - Algorithm Component Model, describes rules and guidelines that enableeXpressDSP-compliant algorithms from multiple sources to operate harmoniously in a single system.•Chapter 4 - Algorithm Performance Characterization, describes how an eXpressDSP-compliantalgorithm's performance must be characterized.•Chapter 5 - DSP-Specific Guidelines, defines a model for describing the DSP's on-chip registers andcontains rules and guidelines for each specific DSP architecture covered by this specification.
SPRU352G – June 2005 – Revised February 2007 Read This First 7Submit Documentation Feedback

www.ti.com
Related Documentation
•Chapter 6 - Use of the DMA Resource, develops guidelines and rules for creatingeXpressDSP-compliant algorithms that utilize the DMA resource.•Appendix A - Rules and Guidelines, contains a complete list of all rules and guidelines in thisspecification.
•Appendix B - Core Run-time Support APIs, contains a complete description of the APIs that aneXpressDSP-compliant algorithm may reference.
Related Documentation
The TMS320 DSP Algorithm Standard is documented in the following manuals:•TMS320 DSP Algorithm Standard Rules and Guidelines (this document). Describes all the rulesand guidelines that make up the TMS320 DSP Algorithm Standard (may be referred to as XDAISthroughout this document).•TMS320 DSP Algorithm Standard API Reference (SPRU360). Contains APIs that are required bythe TMS320 DSP Algorithm Standard and full source examples of eXpressDSP-compliant algorithmcomponents.
•TMS320 DSP Algorithm Standard Developer's Guide (SPRU424). Contains examples that assist thedeveloper in implementing the XDAIS interface and to create a test application.•Using DMA with Framework Components for C64x+ Application Report (SPRAAG1). Describesthe standard DMA software abstractions and interfaces for TMS320 DSP Algorithm Standard (XDAIS)compliant algorithms designed for the C64x+ EDMA3 controller using DMA Framework Componentsutilities.
Although these documents are largely self-contained, there are times when it is best not to duplicatedocumentation that exists in other documents. The following documents contain supplementaryinformation necessary to adhere to the TMS320 DSP Algorithm Standards.•DSP/BIOS User's Guide•TMS320 C54x/C6x/C2x Optimizing C Compiler User's Guide
Text Conventions
The following typographical conventions are used in this specification:•Text inside back-quotes (") represents pseudo-code•Program source code, function and macro names, parameters, and command line commands areshown in a mono-spaced font.
Rule n
Text is shown like this to indicate a requirement of the TMS320 DSP Algorithm Standard.
Guideline n
Text is shown like this to indicate a recommendation of the TMS320 DSP Algorithm Standard.
Read This First8 SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

Chapter 1SPRU352G – June 2005 – Revised February 2007
Overview
This chapter provides an overview of the TMS320 DSP Algorithm Standard.
Topic .................................................................................................. Page
1.1 Scope of the Standard ............................................................... 101.2 Requirements of the Standard ................................................... 111.3 Goals of the Standard ................................................................ 121.4 Intentional Omissions ............................................................... 121.5 System Architecture .................................................................. 13
SPRU352G – June 2005 – Revised February 2007 Overview 9Submit Documentation Feedback

www.ti.com
1.1 Scope of the Standard
Rules for TMS320C2x
Level 1
Level 2
Level 3
Level 4 Telecom
Rules for TMS320C5x Rules for TMS320C6x
Imaging Audio Automotive Other
Algorithm Component Model
General Programming Guidelines
SC callable
SNo hard coded addresses
SReentrant
Setc.
SModules
SGeneric interfaces
SPackaging
Setc.
SInterrupt usage
SMemory usage
SRegister usage
Setc.
SInterrupt usage
SMemory usage
SRegister usage
Setc.
SInterrupt usage
SMemory usage
SRegister usage
Setc.
Svocoders
Secho cancel
Setc.
SJPEG
Setc.
Scoders
Setc.
Setc.
Scope of the Standard
Digital Signal Processors (DSPs) are often programmed like "traditional" embedded microprocessors. Thatis, they are programmed in a mix of C and assembly language, they directly access hardware peripherals,and, for performance reasons, almost always have little or no standard operating system support. Thus,like traditional microprocessors, there is very little use of commercial off-the-shelf (COTS) softwarecomponents for DSPs.
However, unlike general-purpose embedded microprocessors, DSPs are designed to run sophisticatedsignal processing algorithms and heuristics. For example, they may be used to detect DTMF digits in thepresence of noise, to compress toll quality speech by a factor of 20, or for speech recognition in a noisyautomobile traveling at 65 miles per hour.
Such algorithms are often the result of many years of doctoral research. However, because of the lack ofconsistent standards, it is not possible to use an algorithm in more than one system without significantreengineering. Since few companies can afford a team of DSP PhDs, and the reuse of DSP algorithms isso labor intensive, the time-to-market for a new DSP-based product is measured in years rather than inmonths.
This document defines a set of requirements for DSP algorithms that, if followed, allow system integratorsto quickly assemble production-quality systems from one or more such algorithms. Thus, this standard isintended to enable a rich COTS marketplace for DSP algorithm technology and to significantly reduce thetime-to-market for new DSP-based products.
The TMS320 DSP Algorithm Standard defines three levels of guidelines.
Figure 1-1. TMS320 DSP Algorithm Standard Elements
Level 1 contains programming guidelines that apply to all algorithms on all DSP architectures regardlessof application area. Almost all recently developed software modules follow these common senseguidelines already, so this level just formalizes them.
Level 2 contains rules and guidelines that enable all algorithms to operate harmoniously within a singlesystem. Conventions are established for the algorithm's use of data memory and names for externalidentifiers, for example. In addition, simple rules for how algorithms are packaged are also specified.
10 Overview SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

www.ti.com
1.1.1 Rules and Guidelines
1.2 Requirements of the Standard
Requirements of the Standard
Level 3 contains the guidelines for specific families of DSPs. Today, there are no agreed-upon guidelinesfor algorithms with regard to the use of processor resources. These guidelines will provide guidance onthe dos and don'ts for the various architectures. There is always the possibility that deviations from theseguidelines will occur, but then the algorithm vendor can explicitly draw attention to the deviation in therelevant documentation or module headers.
The shaded boxes represent the areas that are covered in this version of the specification.
Level 4 contains the various vertical markets. Due to the inherently different nature of each of thesebusinesses, it seems appropriate for the stakeholders in each of these markets to define the interfaces forgroups of algorithms based on the vertical market. If each unique algorithm were specified with aninterface, the standard would never be able to keep up and thus not be effective. It is important to notethat at this level, any algorithm that conforms to the rules defined in the top three levels is consideredeXpressDSP-compliant.
The TMS320 DSP Algorithm Standard specifies both rules and guidelines. Rules must be followed inorder for software to be eXpressDSP-compliant. Guidelines, on the other hand, are strongly suggestedrecommendations that should be obeyed, but are not required, in order for software to beeXpressDSP-compliant.
This section lists the required elements of the TMS320 DSP Algorithm Standard. These requirements areused throughout the remainder of the document to motivate design choices. They also help clarify theintent of many of the stated rules and guidelines.•Algorithms from multiple vendors can be integrated into a single system.•Algorithms are framework-agnostic. That is, the same algorithm can be efficiently used in virtually anyapplication or framework.•Algorithms can be deployed in purely static as well as dynamic run-time environments.•Algorithms can be distributed in binary form.•Integration of algorithms does not require recompilation of the client application, althoughreconfiguration and relinking may be required.
A huge number of DSP algorithms are needed in today's marketplace, including modems, vocoders,speech recognizers, echo cancellation, and text-to-speech. It is not possible for a product developer, whowants to leverage this rich set of algorithms, to obtain all the necessary algorithms from a single source.On the other hand, integrating algorithms from multiple vendors is often impossible due to incompatibilitiesbetween the various implementations. In order to break this Catch-22, eXpressDSP-compliant algorithmsfrom different vendors must all interoperate.
Dozens of distinct third-party DSP frameworks exist in the telephony vertical market alone. Each vendorhas hundreds and sometimes thousands of customers. Yet, no one framework dominates the market. Toachieve the goal of algorithm reuse, the same algorithm must be usable in all frameworks.
Marketplace fragmentation by various frameworks has a legitimate technical basis. Each frameworkoptimizes performance for an intended class of systems. For example, client systems are designed assingle-channel systems with limited memory, limited power, and lower-cost DSPs. As a result, they arequite sensitive to performance degradation. Server systems, on the other hand, use a single DSP tohandle multiple channels, thus reducing the cost per channel. As a result, they must support a dynamicenvironment. Yet, both client-side and server-side systems may require exactly the same vocoders.
It is important that algorithms be deliverable in binary form. This not only protects the algorithm vendor'sintellectual property; it also improves the reusability of the algorithm. If source code were required, allclients would require recompilation. In addition to being destabilizing for the clients, version control for thealgorithms would be close to impossible.
SPRU352G – June 2005 – Revised February 2007 Overview 11Submit Documentation Feedback

www.ti.com
1.3 Goals of the Standard
1.4 Intentional Omissions
Goals of the Standard
This section contains the goals of this standard. While it may not be possible to perfectly attain thesegoals, they represent the primary concerns that should be addressed after addressing the requiredelements described in the previous section.•Easy to adhere to the standard•Possible to verify conformance to standard•Enable system integrators to easily migrate between TI DSPs•Enable host tools to simplify a system integrator's tasks, including configuration, performancemodeling, standard conformance, and debugging.•Incur little or no "overhead" for static systems
Although TI currently enjoys a leadership role in the DSP marketplace, it cannot directly control thealgorithm software base. This is especially true for relatively mature DSPs, such as the C54xx family,where significant algorithm technology currently exists. Thus, for any specification to achieve the status ofa standard, it must represent a low hurdle for the legacy code base.
While we can all agree to a guideline that states that every algorithm must be of high quality, this type ofguideline cannot be measured or verified. This non-verification or non-measurement enables systemintegrators to claim that all their algorithms are of high quality, and therefore will not place a value on theguideline in this instance. Thus, it is important that each guideline be measurable or, in some sense,verifiable.
While this standard does define an algorithm's APIs in a DSP-independent manner, it does not seek tosolve the DSP migration problem. For example, it does not require that algorithms be provided on both aC54x and a C6x platform. It does not specify a multiple binary object file format to enable a single binaryto be used in both a C5x and a C6x design. Nor does it supply tools to translate code from onearchitecture to another or require the use of an architecture independent language (such as C) in theimplementation of algorithms.
Wherever possible, this standard tries to anticipate the needs of the system integrator and provide rulesfor the development of algorithms that allow host tools to be created that will assist the integration of thesealgorithms. For example, rules related to algorithm naming conventions enable tools that automaticallyresolve name conflicts and select alternate implementations as appropriate.
Maurice Wilkes once said, "There is no problem in computer programming that cannot be solved by anadded level of indirection." Frameworks are perfect examples of how indirection is used to "solve" DSPsoftware architecture problems; device independence is achieved by adding a level of indirection betweenalgorithms and physical peripherals, and algorithm interchangeability is achieved by using functionpointers.
On the other hand, Jim Gray has been quoted as saying, "There is no performance problem that cannotbe solved by eliminating a level of indirection." It is essential that the TMS320 DSP Algorithm Standardremain true to the spirit of the DSP developer: any overhead incurred by adherence to the standard mustbe minimized.
In this section, we describe those aspects of the standard that are intentionally omitted. This is not to saythat these issues are not important, but in the interest of timeliness, this version does not make anyrecommendation. Future versions will address these omissions.•Version control•Licensing, encryption, and IP protection•Installation and verification (i.e., digital signatures)•Documentation and online help
Like all software, algorithms evolve over time, and therefore require version control. Moreover, as theTMS320 DSP Algorithm Standard evolves, older algorithm components may fail to be compliant with thelatest specification. Ideally, a version numbering scheme would be specified that allowed host-based toolsto automatically detect incompatible versions of algorithm components.
12 Overview SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

www.ti.com
1.5 System Architecture
ALG
ALG
ALG
Framework
Status
Cmd
Status
Cmd
Core run time support
1.5.1 Frameworks
System Architecture
To support the ability of a system integrator to rapidly evaluate algorithms from various vendors, amechanism should be defined that allows a component to be used for evaluation only. This wouldencourage algorithm vendors to provide free evaluations of their technology. It is important to providemechanisms, such as encryption of the code, that protect the vendor's IP; otherwise, vendors will notmake their components readily available.
Each algorithm component is typically delivered with documentation, on-line help files, and exampleprograms. Ideally, this set of files would be standardized for each algorithm, and installation into the CodeComposer Studio environment would be standardized. The standardization will greatly simplify the rapidevaluation and system integration process. In addition, it is important that when a component is obtained,its origin can be reliably determined, to prevent component theft among algorithm vendors.
Many modern DSP system architectures can be partitioned along the lines depicted in Figure 1-2 .
Figure 1-2. DSP Software Architecture
Algorithms are "pure" data transducers; i.e., they simply take input data buffers and produce some numberof output data buffers. The core run-time support includes functions that copy memory, and functions toenable and disable interrupts. The framework is the "glue" that integrates the algorithms with the real-timedata sources and links using the core run time support, to create a complete DSP sub-system.Frameworks for the DSP often interact with the real-time peripherals (including other processors in thesystem) and often define the I/O interfaces for the algorithm components.
Unfortunately, for performance reasons, many DSP systems do not enforce a clear line between algorithmcode and the system-level code (i.e., the framework). Thus, it is not possible to easily reuse an algorithmin more than one system. The TMS320 DSP Algorithm Standard is intended to clearly define this line insuch a way that performance is not sacrificed and algorithm reusability is significantly enhanced.
Frameworks often define a device independent I/O sub-system and specify how essential algorithmsinteract with this sub-system. For example, does the algorithm call functions to request data or does theframework call the algorithm with data buffers to process? Frameworks also define the degree ofmodularity within the application; i.e., which components can be replaced, added, removed, and when cancomponents be replaced (compile time, link time, or real-time).
Even within the telephony application space, there are a number of different frameworks available andeach is optimized for a particular application segment (e.g., large volume client-side products and lowvolume high-density server-side products). Given the large number of incompatibilities between thesevarious frameworks and the fact that each framework has enjoyed success in the market, this standarddoes not make any significant requirements of a framework.
SPRU352G – June 2005 – Revised February 2007 Overview 13Submit Documentation Feedback

www.ti.com
1.5.2 Algorithms
1.5.3 Core Run-Time Support
System Architecture
Careful inspection of the various frameworks in use reveals that, at some level, they all have algorithmcomponents. While there are differences in each of the frameworks, the algorithm components sharemany common attributes.•Algorithms are C callable•Algorithms are reentrant•Algorithms are independent of any particular I/O peripheral•Algorithms are characterized by their memory and MIPS requirements
In approximately half of the frameworks reviewed, algorithms are also required to simply process datapassed to the algorithm. The others assume that the algorithm will actively acquire data by callingframework-specific, hardware-independent, I/O functions. In all cases, algorithms are designed to beindependent of the I/O peripherals in the system.
In an effort to minimize framework dependencies, this standard requires that algorithms process data thatis passed to them via parameters. It seems likely that conversion of an "active" algorithm to one thatsimply accepts data in the form of parameters is straightforward and little or no loss of performance will beincurred.
Given the similarities between the various frameworks, it seems possible to standardize at the level of thealgorithm. Moreover, there is real benefit to the framework vendors and system integrators to thisstandardization: algorithm integration time will be reduced, it will be possible to easily comparison shop forthe "best" algorithm, and more algorithms will be available.
It is important to realize that each particular implementation of, say a speech detector, represents acomplex set of engineering trade-offs between code size, data size, MIPS, and quality. Moreover,depending on the system designed, the system integrator may prefer an algorithm with lower quality andsmaller footprint to one with higher quality detection and larger footprint (e.g., an electronic toy doll versesa corporate voice mail system). Thus, multiple implementations of exactly the same algorithm sometimesmake sense; there is no single best implementation of many algorithms.
Unfortunately, the system integrator is often faced with choosing all algorithms from a single vendor toensure compatibility between the algorithms and to minimize the overhead of managing disparate APIs.Moreover, no single algorithm vendor has all the algorithms for all their customers. The system integratoris, therefore, faced with having to chose a vendor that has "most" of the required algorithms and negotiatewith that vendor to implement the remaining DSP algorithms.
By enabling system integrators to plug or replace one algorithm for another, we reduce the time to marketbecause the system integrator can chose algorithms from multiple vendors. We effectively create a hugecatalog of interoperable parts from which any system can be built.
In order to enable algorithms to satisfy the minimum requirements of reentrancy, I/O peripheralindependence, and debuggability, algorithms must rely on a core set of services that are always present.Since most algorithms are still produced using assembly language, many of the services provided by thecore must be accessible and appropriate for assembly language.
The core run-time support includes a subset of HWI functions of DSP/BIOS to support atomic modificationof control/status registers (to set the overflow mode, for example). It also includes a subset of the standardC language run-time support libraries; e.g., memcpy, strcpy, etc. The run-time support is described indetail in Appendix B of this document.
14 Overview SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

Chapter 2SPRU352G – June 2005 – Revised February 2007
General Programming Guidelines
In this chapter, we develop programming guidelines that apply to all algorithms on allDSP architectures, regardless of application area.
Topic .................................................................................................. Page
2.1 Use of C Language .................................................................... 162.2 Threads and Reentrancy ............................................................ 162.3 Data Memory ............................................................................ 192.4 Program Memory ..................................................................... 232.5 ROM-ability .............................................................................. 232.6 Use of Peripherals .................................................................... 24
SPRU352G – June 2005 – Revised February 2007 General Programming Guidelines 15Submit Documentation Feedback

www.ti.com
2.1 Use of C Language
2.2 Threads and Reentrancy
2.2.1 Threads
Use of C Language
Almost all recently developed software modules follow these common sense guidelines already, so thischapter just formalizes them. In addition to these guidelines, we also develop a general model of datamemory that enables applications to efficiently manage an algorithm's memory requirements.
All algorithms will follow the run-time conventions imposed by the C programming language. This ensuresthat the system integrator is free to use C to "bind" various algorithms together, control the flow of databetween algorithms, and interact with other processors in the system easily.
Rule 1
All algorithms must follow the run-time conventions imposed by TI’s implementation of the Cprogramming language.
It is very important to note that this does not mean that algorithms must be written in the C language.Algorithms may be implemented entirely in assembly language. They must, however, be callable from theC language and respect the C language run-time conventions. Most significant algorithms are notimplemented as a single function; like any sophisticated software, they are composed of many interrelatedinternal functions. Again, it is important to note that these internal functions do not need to follow the Clanguage conventions; only the top-most interfaces must obey the C language conventions. On the otherhand, these internal functions must be careful not to cause the top-most function to violate the C run-timeconventions; e.g., no called function may use a word on the stack with interrupts enabled without firstupdating the stack pointer.
Because of the variety of frameworks available for DSP systems, there are many differing types ofthreads, and therefore, reentrancy requirements. In this section, we try to precisely define the types ofthreads supported by this standard and the reentrancy requirements of algorithms.
A thread is an encapsulation of the flow of control in a program. Most people are accustomed to writingsingle-threaded programs; i.e., programs that only execute one path through their code "at a time."Multi-threaded programs may have several threads running through different code paths "simultaneously."
Why are some phrases above in quotes? In a typical multi-threaded program, zero or more threads mayactually be running at any one time. This depends on the number of CPUs in the system in which theprocess is running, and on how the thread system is implemented. A system with n CPUs can, intuitivelyrun no more than n threads in parallel, but it may give the appearance of running many more than n"simultaneously," by sharing the CPUs among threads. The most common case is that of n equal to one;i.e., a single CPU running all the threads of an application.
Why are threads interesting? An OS or framework can schedule them, relieving the developer of anindividual thread from having to know about all the other threads in the system. In a multi-CPU system,communicating threads can be moved among the CPUs to maximize system performance without havingto modify the application code. In the more common case of a single CPU, the ability to createmulti-threaded applications allows the CPU to be used more effectively; while one thread is waiting fordata, another can be processing data.
Virtually all DSP systems are multi-threaded; even the simplest systems consist of a main program andone or more hardware interrupt service routines. Additionally, many DSP systems are designed to managemultiple "channels" or "ports," i.e., they perform the same processing for two or more independent datastreams.
General Programming Guidelines16 SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

www.ti.com
2.2.2 Preemptive vs. Non-Preemptive Multitasking
2.2.3 Reentrancy
Threads and Reentrancy
Non-preemptive multitasking relies on each thread to voluntarily relinquish control to the operating systembefore letting another thread execute. This is usually done by requiring threads to periodically call anoperating system function, say yield(), to allow another thread to take control of the CPU or by simplyrequiring all threads to complete within a specified short period. In a non-preemptive multi-threadingenvironment, the amount of time a thread is allowed to run is determined by the thread, whereas in apreemptive environment, the time is determined by the operating system and the entire set of tasks thatare ready to run.
Note that the difference between those two flavors of multi-threading can be a very big one; for example,under a non-preemptive system, you can safely assume that no other thread executes while a particularalgorithm processes data using on-chip data memory. Under preemptive execution, this is not true; athread may be preempted while it is in the middle of processing. Thus, if your application relies on theassumption that things do not change in the middle of processing some data, it might break under apreemptive execution scheme.
Since preemptive systems are designed to preserve the state of a preempted thread and restore it whenits execution continues, threads can safely assume that most registers and all of the thread's data memoryremain unchanged. What would cause an application to fail? Any assumptions related to the maximumamount of time that can elapse between any two instructions, the state of any global system resourcesuch as a data cache, or the state of a global variable accessed by multiple threads, can cause anapplication to fail in a preemptive environment.
Non-preemptive environments incur less overhead and often result in higher performance systems; forexample, data caches are much more effective in non-preemptive systems since each thread can controlwhen preemption (and therefore, cache flushing) will occur.
On the other hand, non-preemptive environments require that either each thread complete within aspecified maximum amount of time, or explicitly relinquish control of the CPU to the framework (oroperating system) at some minimum periodic rate. By itself, this is not a problem since most DSP threadsare periodic with real-time deadlines. However, this minimum rate is a function of the other threads in thesystem and, consequently, non-preemptive threads are not completely independent of one another; theymust be sensitive to the scheduling requirements of the other threads in the system. Thus, systems thatare by their nature multirate and multichannel often require preemption; otherwise, all of the algorithmsused would have to be rewritten whenever a new algorithm is added to the system.
If we want all algorithms to be framework-independent, we must either define a framework-neutral way foralgorithms to relinquish control, or assume that algorithms used in a non-preemptive environment alwayscomplete in less than the required maximum scheduling latency time. Since we require documentation ofworst-case execution times, it is possible for system integrators to quickly determine if an algorithm willcause a non-preemptive system to violate its scheduling latency requirements. Thus, the TMS320 DSPAlgorithm Standard does not define a framework-neutral "yield" operation for algorithms.
Since algorithms can be used in both preemptive and non-preemptive environments, it is important that allalgorithms be designed to support both. This means that algorithms should minimize the maximum timethat they can delay other algorithms in a non-preemptive system.
Reentrancy is the attribute of a program or routine that allows the same copy of the program or routine tobe used concurrently by two or more threads.
Reentrancy is an extremely valuable property for functions. In multichannel systems, for example, anyfunction that can be invoked as part of one channel's processing must be reentrant ; otherwise, thatfunction would not be usable for other channels. In single channel multirate systems, any function thatmust be used at two different rates must be reentrant; for example, a general digital filter function used forboth echo cancellation and pre-emphasis for a vocoder. Unfortunately, it is not always easy to determine ifa function is reentrant.
SPRU352G – June 2005 – Revised February 2007 General Programming Guidelines 17Submit Documentation Feedback

www.ti.com
2.2.4 Example
yn+xn*xn*1)13
32 xn*2
Threads and Reentrancy
The definition of reentrant code often implies that the code does not retain "state" information. That is, ifyou invoke the code with the same data at different times, by the same or other thread, it will yield thesame results. This is not always true, however. How can a function maintain state and still be reentrant?Consider the rand() function. Perhaps a better example is a function with state that protects that state bydisabling scheduling around its critical sections. These examples illustrate some of the subtleties ofreentrant programming.
The property of being reentrant is a function of the threading model; after all, before you can determinewhether multiple threads can use a particular function, you must know what types of threads are possiblein a system. For example, if threads are not preemptive, a function may freely use global variables if ituses them for scratch storage only; i.e., it does not assume these variables have any values upon entry tothe function. In a preemptive environment, however, use of these global variables must be protected by acritical section or they must be part of the context of every thread that uses them.
Although there are exceptions, reentrancy usually requires that algorithms:•only modify data on the stack or in an instance "object"•treat global and static variables as read-only data•never employ self modifying code
These rules can sometimes be relaxed by disabling all interrupts (and therefore, disabling all threadscheduling) around the critical sections that violate the rules above. Since algorithms are not permitted todirectly manipulate the interrupt state of the processor, the allowed DSP/BIOS HWI module functions (orequivalent implementations) must be called to create these critical sections.
Rule 2
All algorithms must be reentrant within a preemptive environment (including time-sliced preemption).
In the remainder of this section we consider several implementations of a simple algorithm, digital filteringof an input speech data stream, and show how the algorithm can be made reentrant and maintainacceptable levels of performance. It is important to note that, although these examples are written in C,the principles and techniques apply equally well to assembly language implementations.
Speech signals are often passed through a pre-emphasis filter to flatten their spectrum prior to additionalprocessing. Pre-emphasis of a signal can be accomplished by applying the following difference equationto the input data:
The following implementation is not reentrant because it references and updates the global variables z0and z1. Even in a non-preemptive environment, this function is not reentrant; it is not possible to use thisfunction to operate on more than one data stream since it retains state for a particular data stream in twofixed variables (z0 and z1).int z0 = 0, z1 = 0; /* previous input values */
void PRE_filter(int input[], int length){
int I, tmp;
for (I = 0; I < length; I++) {tmp = input[i] - z0 + (13 * z1 + 16) / 32;z1 = z0;z0 = input[i];
input[i] = tmp;}}
We can make this function reentrant by requiring the caller to supply previous values as arguments to thefunction. This way, PRE_filter1 no longer references any global data and can be used, therefore, on anynumber of distinct input data streams.
18 General Programming Guidelines SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback

www.ti.com
2.3 Data Memory
Data Memory
void PRE_filter1(int input[], int length, int *z){
int I, tmp;
for (I = 0; I< length; I++) {tmp = input[i] - z[0] + (13 * z[1] + 16) / 32;z[1] = z[0];z[0] = input[i];
input[i] = tmp;}}
This technique of replacing references to global data with references to parameters illustrates a generaltechnique that can be used to make virtually any Code reentrant. One simply defines a "state object" asone that contains all of the state necessary for the algorithm; a pointer to this state is passed to thealgorithm (along with the input and output data).typedef structPRE_Obj { /* state obj for pre-emphasis alg */int z0;int z1;} PRE_Obj;
void
PRE_filter2(PRE_Obj *pre, int input[], int length){
int I, tmp;
for (I = 0; I < length; I++){
tmp = input[i] - pre->z0 + (13 * pre->z1 + 16) /32;
pre->z1 = pre->z0;pre->z0 = input[i];input[i] = tmp;}}
Although the C Code looks more complicated than our original implementation, its performance iscomparable, it is fully reentrant, and its performance can be configured on a "per data object" basis. Sinceeach state object can be placed in any data memory, it is possible to place some objects in on-chipmemory and others in external memory. The pointer to the state object is, in effect, the function's private"data page pointer." All of the function's data can be efficiently accessed by a constant offset from thispointer.
Notice that while performance is comparable to our original implementation, it is slightly larger and slowerbecause of the state object redirection. Directly referencing global data is often more efficient thanreferencing data via an address register. On the other hand, the decrease in efficiency can usually befactored out of the time-critical loop and into the loop-setup Code. Thus, the incremental performance costis minimal and the benefit is that this same Code can be used in virtually any system—independent ofwhether the system must support a single channel or multiple channels, or whether it is preemptive ornon-preemptive.
"We should forget about small efficiencies, say about 97% of the time: premature optimization is the rootof all evil." —Donald Knuth "Structured Programming with go to Statements," Computing Surveys, Vol. 6,No. 4, December, 1974, page 268.
The large performance difference between on-chip data memory and off-chip memory (even 0 wait-stateSRAM) is so large that every algorithm vendor designs their Code to operate as much as possible withinthe on-chip memory. Since the performance gap is expected to increase dramatically in the next 3-5years, this trend will continue for the foreseeable future. The TMS320C6000 series, for example, incurs a25 wait state penalty for external SDRAM data memory access. Future processors may see this penaltyincrease to 80 or even 100 wait states!
SPRU352G – June 2005 – Revised February 2007 General Programming Guidelines 19Submit Documentation Feedback

www.ti.com
2.3.1 Memory Spaces
2.3.2 Scratch versus Persistent
Data Memory
While the amount of on-chip data memory may be adequate for each algorithm in isolation, the increasednumber of MIPS available on modern DSPs encourages systems to perform multiple algorithmsconcurrently with a single chip. Thus, some mechanism must be provided to efficiently share this preciousresource among algorithm components from one or more third parties.
In an ideal DSP, there would be an unlimited amount of on-chip memory and algorithms would simplyalways use this memory. In practice, however, the amount of on-chip memory is very limited and there areeven two common types of on-chip memory with very different performance characteristics: dual-accessmemory which allows simultaneous read and write operations in a single instruction cycle, and singleaccess memory that only allows a single access per instruction cycle.
Because of these practical considerations, most DSP algorithms are designed to operate with acombination of on-chip and external memory. This works well when there is sufficient on-chip memory forall the algorithms that need to operate concurrently; the system developer simply dedicates portions ofon-chip memory to each algorithm. It is important, however, that no algorithm assume specific region ofon-chip memory or contain any "hard Coded" addresses; otherwise the system developer will not be ableto optimally allocate the on-chip memory among all algorithms.
Rule 3
Algorithm data references must be fully relocatable (subject to alignment requirements). That is, theremust be no “hard-coded” data memory locations.
Note that algorithms can directly access data contained in a static data structure located by the linker. Thisrule only requires that all such references be done symbolically; i.e., via a relocatable label rather than afixed numerical address.
In systems where the set of algorithms is not known in advance or when there is insufficient on-chipmemory for the worst-case working set of algorithms, more sophisticated management of this preciousresource is required. In particular, we need to describe how the on-chip memory can be shared at run-timeamong an arbitrary number of algorithms.
In this section, we develop a general model for sharing regions of memory among algorithms. This modelis used to share the on-chip memory of a DSP, for example. This model is essentially a generalization ofthe technique commonly used by compilers to share CPU registers among functions. Compilers oftenpartition the CPU registers into two groups: "scratch" and "preserve." Scratch registers can be freely usedby a function without having to preserve their value upon return from the function. Preserve registers, onthe other hand, must be saved prior to being modified and restored prior to returning from the function. Bypartitioning the register set in this way, significant optimizations are possible; functions do not need tosave and restore scratch registers, and callers do not need to save preserve registers prior to calling afunction and restore them after the return.
Consider the program execution trace of an application that calls two distinct functions, say a() and b().Void main()
{
... /* use scratch registers r1 and r2 */
/* call functiona() */a() {... /* use scratch registers r0, r1, and r2 */}
/* call function b()*/
b() {... /* use scratch registers r0 and r1*/}}
20 General Programming Guidelines SPRU352G – June 2005 – Revised February 2007Submit Documentation Feedback