Texas Instruments TMS320C2x User manual

TMS320C2x/C2xx/C5x
Optimizing C Compiler
User’s Guide
Literature Number: SPRU024E
August 1999
Printed on Recycled Paper

IMPORTANT NOTICE
Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue
any product or service without notice, and advise customers to obtain the latest version of relevant information
to verify, before placing orders, that information being relied on is current and complete. All products are sold
subject to the terms and conditions of sale supplied at the time of order acknowledgement, including those
pertaining to warranty, patent infringement, and limitation of liability.
TI warrants performance of its semiconductor products to the specifications applicable at the time of sale in
accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent
TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily
performed, except those mandated by government requirements.
CERTAIN APPLICATIONS USING SEMICONDUCTOR PRODUCTS MAY INVOLVE POTENTIAL RISKS OF
DEATH, PERSONAL INJURY, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE (“CRITICAL
APPLICATIONS”). TI SEMICONDUCTOR PRODUCTS ARE NOT DESIGNED, AUTHORIZED, OR
WARRANTED TO BE SUITABLE FOR USE IN LIFE-SUPPORT DEVICES OR SYSTEMS OR OTHER
CRITICAL APPLICATIONS. INCLUSION OF TI PRODUCTS IN SUCH APPLICATIONS IS UNDERSTOOD TO
BE FULLY AT THE CUSTOMER’S RISK.
In order to minimize risks associated with the customer’s applications, adequate design and operating
safeguards must be provided by the customer to minimize inherent or procedural hazards.
TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent
that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other
intellectual property right of TI covering or relating to any combination, machine, or process in which such
semiconductor products or services might be or are used. TI’s publication of information regarding any third
party’s products or services does not constitute TI’s approval, warranty or endorsement thereof.
Copyright 1999, Texas Instruments Incorporated

iiiRead This First
Preface
Read This First
About This Manual
The TMS320C2x/C2xx/C5x Optimizing C Compiler User’s Guide tells you how
to use these compiler tools:
-Compiler
-Source interlist utility
-Optimizer
-Parser
-Library-build utility
The TMS320C2x/C2xx/C5x C compiler accepts American National Standards
Institute (ANSI) standard C source code and produces assembly language
source code for the TMS320C2x/C2xx/C5x devices. This user’s guide dis-
cusses the characteristics of the C compiler. It assumes that you already know
how to write C programs. The C Programming Language (second edition), by
Brian W. Kernighan and Dennis M. Ritchie (hereafter referred to as K & R),
describes C based on the ANSI C standard. You can use the Kernighan and
Ritchie book as a supplement to this manual.
Before you use the information about the C compiler in this User’s Guide, you
should read the TMS320C1x/C2x/ C2xx/C5x Code Generation Tools Getting
Started to install the C compiler tools.

How to Use This Manual
iv
How to Use This Manual
The goal of this book is to help you learn how to use the Texas Instruments C
compiler tools specifically designed for the TMS320C2x/C2xx/C5x devices.
This book is divided into three distinct parts:
-Introductory information, consisting of Chapter 1, provides an overview
of the TMS320C2x/C2xx/C5x development tools.
-Compiler description, consisting of Chapters 2, 5, 6, 7, and 8, describes
how to operate the C compiler and the shell program, and discusses
specific characteristics of the C compiler as they relate to the ANSI C spec-
ification. It contains technical information on the TMS320C2x/ C2xx/C5x
architecture and includes information needed for interfacing assembly
language to C programs. It describes libraries and header files in addition
to the macros, functions, and types they declare. Finally, it describes the
library-build utility.
-Reference material, consisting of Appendix B, provides a glossary.
Notational Conventions
This document uses the following conventions.
-Program listings, program examples, and interactive displays are shown
in a special typeface similar to a typewriter’s. Examples use a bold
version of the special typeface for emphasis; interactive displays use a
bold version of the special typeface to distinguish commands that you
enter from items that the system displays (such as prompts, command
output, error messages, etc.).
Here is a sample of C code:
# ifdef NDEBUG
# define assert
-In syntax descriptions, the instruction, command, or directive is in a bold
face font and parameters are in italics. Portions of a syntax that are in bold
face must be entered as shown; portions of a syntax that are in italics de-
scribe the type of information that should be entered. Here is an example
of a directive syntax:
#include “filename”
The #include preprocessor directive has one required parameter, file-
name. The filename must be enclosed in double quotes or angle brackets.
How to Use This Manual / Notational Conventions

Related Documentation From Texas Instruments
vRead This First
-Square brackets ( [ and ] ) identify an optional parameter. If you use an op-
tional parameter, you specify the information within the brackets; you do
not enter the brackets themselves. Here is an example of a command that
has an optional parameter:
clist asmfile [outfile] [−options]
JThe clist command has three parameters.
JThe first parameter, asmfile, is required.
JThe second and third parameters, outfile and −options, are optional.
JIf you omit the outfile, the file has the same name as the assembly file
with the extension .cl.
JOptions are preceded by a hyphen.
Related Documentation From Texas Instruments
The following books describe the TMS320C2x/C2xx/C5x and related support
tools. To obtain a copy of any of these TI documents, call the Texas Instru-
ments Literature Response Center at (800) 477−8924. When ordering, identify
the book by its title and literature number (located on the bottom-right corner
of the back cover).
TMS320C2x User’s Guide (literature number SPRU014) discusses the hard-
ware aspects of the ’C2x fixed-point digital signal processors. It de-
scribes pin assignments, architecture, instruction set, and software and
hardware applications. It also includes electrical specifications and pack-
age mechanical data for all ’C2x devices. The book features a section
with a ’C1x-to-’C2x DSP system migration.
TMS320C2xx User’s Guide (literature number SPRU127) discusses the
hardware aspects of the ’C2xx fixed-point digital signal processors. It de-
scribes pin assignments, architecture, instruction set, and software and
hardware applications. It also includes electrical specifications and pack-
age mechanical data for all ’C2xx devices. The book features a section
comparing instructions from ’C2x to ’C2xx.
TMS320C5x User’s Guide (literature number SPRU056) describes the
TMS320C5x 16-bit, fixed-point, general-purpose digital signal proces-
sors. Covered are its architecture, internal register structure, instruction
set, pipeline, specifications, DMA, and I/O ports. Software applications
are covered in a dedicated chapter.
Notational Conventions / Related Documentation From Texas Instruments

Related Documentation From Texas Instruments
vi
TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide (lit-
erature number SPRU018) describes the assembly language tools (as-
sembler, linker, and other tools used to develop assembly language
code), assembler directives, macros, common object file format, and
symbolic debugging directives for the ’C1x, ’C2x, ’C2xx, and ’C5x gen-
erations of devices.
TMS320C2x Software Development System Technical Reference (liter-
ature number SPRU072) provides specific application and design in-
formation for using the TMS320C2x Software Development System
(SWDS) board.
TMS320C5x Software Development System Technical Reference (liter-
ature number SPRU066) provides specific application and design in-
formation for using the TMS320C5x Software Development System
(SWDS) board.
TMS320C2x C Source Debugger User’s Guide (literature number
SPRU070) tells how to use the ’C2x C source debugger with the ’C2x
emulator, software development system (SWDS), and simulator.
TMS320C5x C Source Debugger User’s Guide (literature number
SPRU055) tells you how to invoke the ’C5x emulator, EVM, and simulator
versions of the C source debugger interface. This book discusses
various aspects of the debugger interface, including window
management, command entry, code execution, data management, and
breakpoints, and includes a tutorial that introduces basic debugger
functionality.

Related Documentation From Texas Instruments
viiRead This First
Related Documentation
The C Programming Language (second edition), by Brian W. Kernighan
and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs,
New Jersey, 1988.
You may find these documents helpful as well:
American National Standard for Information Systems—Programming
Language C X3.159-1989, American National Standards Institute
(ANSI standard for C)
Programming in C,Kochan, Steve G., Hayden Book Company
Trademarks
MS-DOS is a registered trademark of Microsoft Corp.
PC-DOS is a trademark of International Business Machines Corp.
SPARC is a trademark of SPARC International, Inc.
Sun-OS and Sun Workstation are trademarks of Sun Microsystems, Inc.
XDS is a trademark of Texas Instruments Incorporated.
Related Documentation / Trademarks

viii

Contents
ix
Contents
1 Introduction 1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Provides an overview of the TMS320C2x/C2xx/C5x software development tools, specifically,
the optimizing C Compiler.
1.1 Software Development Tools Overview 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2 C Compiler Overview 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2 C Compiler Description 2-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Describes how to operate the C compiler and the shell program. Contains instructions for invok-
ing the shell program, which compiles, assembles, and links a C source file. Discusses the in-
terlist utility and compiler errors.
2.1 About the Shell Program 2-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2 Invoking the Compiler Shell 2-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3 Changing the Compiler’s Behavior With Options 2-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.1 Frequently Used Options 2-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.2 Specifying Filenames 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.3 Changing How the Shell Program Interprets Filenames (−fa, −fc, and −fo
Options) 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.4 Changing How the Shell Program Interprets and Names Extensions (−ea
and −eo Options) 2-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.5 Specifying Directories 2-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.6 Options That Overlook ANSI C Type Checking 2-17. . . . . . . . . . . . . . . . . . . . . . . . .
2.3.7 Runtime-Model Options 2-18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.3.8 Options That Control the Assembler 2-19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4 Changing the Compiler’s Behavior With Environment Variables 2-20. . . . . . . . . . . . . . . . . .
2.4.1 Setting Default Shell Options (C_OPTION) 2-20. . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.4.2 Specifying a Temporary File Directory (TMP) 2-21. . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5 Controlling the Preprocessor 2-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.1 Predefined Macro Names 2-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.2 The Search Path for #include Files 2-23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.3 Changing the #include File Search Path With the −i Option 2-24. . . . . . . . . . . . . .
2.5.4 Generating a Preprocessed Listing File (−pl Option) 2-25. . . . . . . . . . . . . . . . . . . . .
2.5.5 Creating Custom Error Messages with the #error and #warn Directives 2-26. . . .
2.5.6 Enabling Trigraph Expansion (−p? Option) 2-26. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.7 Creating a Function Prototype Listing File (−pf Option) 2-26. . . . . . . . . . . . . . . . . .

Contents
x
2.6 Using Inline Function Expansion 2-27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.1 Inlining Intrinsic Operators 2-27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.2 Controlling Inline Function Expansion (−x Option) 2-28. . . . . . . . . . . . . . . . . . . . . . .
2.6.3 Using the inline Keyword 2-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.6.4 The _INLINE Preprocessor Symbol 2-31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.7 Using the Interlist Utility 2-33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8 Understanding and Handling Compiler Errors 2-35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8.1 Generating an Error Listing (−pr Option) 2-36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.8.2 Treating Code-E Errors as Warnings (−pe Option) 2-36. . . . . . . . . . . . . . . . . . . . . .
2.8.3 Altering the Level of Warning Messages (−pw Option) 2-36. . . . . . . . . . . . . . . . . . .
2.8.4 An Example of How You Can Use Error Options 2-37. . . . . . . . . . . . . . . . . . . . . . . .
2.9 Invoking the Tools Individually 2-38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9.1 Invoking the Parser 2-39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9.2 Parsing in Two Passes 2-41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9.3 Invoking the Optimizer 2-41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9.4 Invoking the Code Generator 2-43. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.9.5 Invoking the Interlist Utility 2-45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3 Optimizing Your Code 3-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Describes how to optimize your C code, including such features as software pipelining and loop
unrolling. Also describes the types of optimizations that are performed when you use the opti-
mizer.
3.1 Using the C Compiler Optimizer 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2 Using the −o3 Option 3-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.1 Controlling File-Level Optimization (−oln Option) 3-4. . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Creating an Optimization Information File (−onn Option) 3-5. . . . . . . . . . . . . . . . . .
3.3 Performing Program-Level Optimization (−pm and −o3 Options) 3-6. . . . . . . . . . . . . . . . . .
3.3.1 Controlling Program-Level Optimization (−opn Option) 3-6. . . . . . . . . . . . . . . . . . .
3.3.2 Optimization Considerations When Mixing C and Assembly 3-8. . . . . . . . . . . . . . .
3.3.3 Naming the Program Compilation Output File (−px Option) 3-9. . . . . . . . . . . . . . . .
3.4 Special Considerations When Using the Optimizer 3-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.1 Use Caution With asm Statements in Optimized Code 3-10. . . . . . . . . . . . . . . . . . .
3.4.2 Use Caution With the Volatile Keyword 3-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.4.3 Use Caution When Accessing Aliased Variables 3-11. . . . . . . . . . . . . . . . . . . . . . . .
3.4.4 Assume Functions Are Not Interrupts 3-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.5 Automatic Inline Expansion (−oi Option) 3-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.6 Using the Interlist Utility With the Optimizer 3-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.7 Debugging Optimized Code 3-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8 What Kind of Optimization Is Being Performed? 3-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.1 Cost-based Register Allocation 3-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.2 Autoincrement Addressing 3-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.3 Repeat Blocks 3-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.4 Delays, Banches, Calls, and Returns 3-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.8.5 Algebraic Reordering / Symbolic Simplification / Constant Folding 3-18. . . . . . . .
3.8.6 Alias Disambiguation 3-18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .