Texas Instruments TMS320C2x, TMS320C2xx, TMS320C5x 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.

About This Manual

Preface

Read This First

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

iiiRead This First

How to Use This Manual

How to Use This Manual / Notational Conventions

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 specification. 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 syntax descriptions, the instruction, command, or directive is in a bold

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

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

Notational Conventions / Related Documentation From Texas Instruments

Square brackets ( [ and ] ) identify an optional parameter. If you use an optional 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]

J The clist command has three parameters.

J The first parameter, asmfile, is required.

J The second and third parameters, outfile and −options, are optional.

J If you omit the outfile, the file has the same name as the assembly file

with the extension .cl.

J Options are preceded by a hyphen.

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.

Related Documentation From Texas Instruments

Related Documentation / Trademarks

and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New Jersey, 1988.

Language C X3.159-1989, American National Standards Institute (ANSI standard for C)

Sun-OS and Sun Workstation are trademarks of Sun Microsystems, Inc.

XDS is a trademark of Texas Instruments Incorporated.

viiRead This First

viii

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 invoking the shell program, which compiles, assembles, and links a C source file. Discusses the interlist 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

2.3.4 Changing How the Shell Program Interprets and Names Extensions (−ea

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

Options) 2-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

and −eo Options) 2-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contents

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

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

Contents

3.8.7 Data-Flow Optimizations 3-18. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.8.8 Branch Optimizations and Control-Flow Simplification 3-20. . . . . . . . . . . . . . . . . . .

3.8.9 Loop Induction Variable Optimizations and Strength Reduction 3-21. . . . . . . . . . .

3.8.10 Loop Rotation 3-21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.8.11 Loop Invariant Code Motion 3-21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.8.12 Inline Expansion of Runtime-Support Library Functions 3-21. . . . . . . . . . . . . . . . . .

4 Linking C Code 4-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Describes how to link using a standalone program or with the compiler shell and how to meet the special requirements of linking C code.

4.1 Invoking the Linker as an Individual Program 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.2 Invoking the Linker With the Compiler Shell (−z Option) 4-4. . . . . . . . . . . . . . . . . . . . . . . . . .

4.3 Disabling the Linker (−c Shell Option) 4-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.4 Linker Options 4-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.5 Controlling the Linking Process 4-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.5.1 Linking With Runtime-Support Libraries 4-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.5.2 Specifying the Type of Initialization 4-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4.5.3 Specifying Where to Allocate Sections in Memory 4-11. . . . . . . . . . . . . . . . . . . . . .

4.5.4 A Sample Linker Command File 4-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5 TMS320C2x/C2xx/C5x C Language 5-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Discusses the specific characteristics of the TMS320C2x/C2xx/C5x C compiler as they relate to the ANSI C specification.

5.1 Characteristics of TMS320C2x/C2xx/C5x C Language 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.1 Identifiers and Constants 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.2 Data Types 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.3 Conversions 5-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.4 Expressions 5-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.5 Declarations 5-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.1.6 Preprocessor 5-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.2 Data Types 5-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.3 Register Variables 5-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.4 Pragma Directives 5-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.4.1 The CODE_SECTION Pragma 5-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.4.2 The DATA_SECTION Pragma 5-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.4.3 The FUNC_EXT_CALLED Pragma 5-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.5 The asm Statement 5-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.6 Creating Global Register Variables 5-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.6.1 When to Use a Global Register Variable 5-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.6.2 Avoiding Corrupting Register Values 5-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.6.3 Disabling the Compiler From Using AR6 and AR7 5-11. . . . . . . . . . . . . . . . . . . . . .

5.7 Initializing Static and Global Variables 5-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.7.1 Initializing Static and Global Variables With the const Type Qualifier 5-12. . . . . . .

5.7.2 Accessing I/O Port Space 5-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.8 Compatibility with K&R C 5-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5.9 Compiler Limits 5-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiContents

Contents

6 Runtime Environment 6-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Contains technical information on how the compiler uses the TMS320C2x/C2xx/C5x architecture. Discusses memory and register conventions, stack organization, function-call conventions, system initialization, and TMS320C2x/C2xx/C5x C compiler optimizations. Provides information needed for interfacing assembly language to C programs.

6.1 Memory Model 6-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.1 Sections 6-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.2 C System Stack 6-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.3 Allocating .const to Program Memory 6-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.4 Dynamic Memory Allocation 6-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.5 Initialization of Variables 6-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.6 Allocating Memory for Static and Global Variables 6-7. . . . . . . . . . . . . . . . . . . . . . .

6.1.7 Field/Structure Alignment 6-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.1.8 Character String Constants 6-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.2 Register Conventions 6-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.2.1 Status Register Fields 6-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.2.2 Stack Pointer, Frame Pointer, and Local Variable Pointer 6-11. . . . . . . . . . . . . . . .

6.2.3 The TMS320C5x INDX Register 6-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.2.4 Register Variables 6-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.2.5 Expression Registers 6-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.2.6 Return Values 6-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.3 Function Structure and Calling Conventions 6-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.3.1 How a Function Makes a Call 6-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.3.2 How a Called Function Responds 6-15. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.3.3 Special Cases for a Called Function 6-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.3.4 Accessing Arguments and Local Variables 6-18. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.4 Interfacing C with Assembly Language 6-19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.4.1 Using Assembly Language Modules With C Code 6-19. . . . . . . . . . . . . . . . . . . . . .

6.4.2 Using Inline Assembly Language 6-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.4.3 Accessing Assembly Language Variables From C Code 6-23. . . . . . . . . . . . . . . . .

6.4.4 Modifying Compiler Output 6-24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.5 Interrupt Handling 6-25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.5.1 General Points About Interrupts 6-25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.5.2 Using C Interrupt Routines 6-26. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.5.3 Using Assembly Language Interrupt Routines 6-27. . . . . . . . . . . . . . . . . . . . . . . . . .

6.5.4 TMS320C5x Shadow Register Capability 6-27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.6 Integer Expression Analysis 6-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.6.1 Arithmetic Overflow and Underflow 6-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.6.2 Integer Division and Modulus 6-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.6.3 Long (32-Bit) Expression Analysis 6-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.6.4 C Code Access to the Upper 16 Bits of 16-Bit Multiply 6-29. . . . . . . . . . . . . . . . . . .

6.7 Floating-Point Expression Analysis 6-30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xii

Contents

6.8 System Initialization 6-31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.8.1 Runtime Stack 6-32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.8.2 Automatic Initialization of Variables 6-32. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.8.3 Initialization Tables 6-33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.8.4 Autoinitialization of Variables at Runtime 6-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6.8.5 Initialization of Variables at Load Time 6-35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7 Runtime-Support Functions 7-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Describes the header files included with the C compiler, as well as the macros, functions, and types they declare. Summarizes the runtime-support functions according to category (header), and provides an alphabetical reference of the runtime-support functions.

7.1 Libraries 7-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.1.1 Linking Code With the Object Library 7-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.1.2 Modifying a Library Function 7-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.1.3 Building a Library With Different Options 7-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2 Header Files 7-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.1 Diagnostic Messages (assert.h) 7-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.2 Character-Typing and Conversion (ctype.h) 7-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.3 Error Reporting (errno.h) 7-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.4 Limits (float.h and limits.h) 7-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.5 Inport/Outport Macros (ioports.h) 7-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.6 Floating-Point Math (math.h) 7-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.7 Nonlocal Jumps (setjmp.h) 7-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.8 Variable Arguments (stdarg.h ) 7-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.9 Standard Definitions (stddef.h) 7-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.10 General Utilities (stdlib.h) 7-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.11 String Functions (string.h) 7-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.2.12 Time Functions (time.h ) 7-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7.3 Summary of Runtime-Support Functions and Macros 7-13. . . . . . . . . . . . . . . . . . . . . . . . . . .

7.4 Description of Runtime-Support Functions and Macros 7-20. . . . . . . . . . . . . . . . . . . . . . . . .

8 Library-Build Utility 8-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Describes the utility that custom-makes runtime-support libraries for the options used to compile code. This utility can also be used to install header files in a directory and to create custom libraries from source archives.

8.1 Invoking the Library-Build Utility 8-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8.2 Library-Build Utility Options 8-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8.3 Options Summary 8-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A Glossary A-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Defines terms and acronyms used in this book.

xiiiContents

Figures

1−1 TMS320C2x/C2xx/C5x Software Development Flow 1-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−1 The Shell Program Overview 2-3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−2 Compiler Overview 2-38. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−1 Compiling a C Program With the Optimizer 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−1 Stack Use During a Function Call 6-14. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−2 Format of Initialization Records in the .cinit Section 6-33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−3 Autoinitialization at Run time 6-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−4 Initialization at Load Time 6-35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Tables

2−1 Shell Options Summary 2-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−2 Predefined Macro Names 2-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−3 Example Error Messages 2-36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−4 Selecting a Level for the −pw Option 2-37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−5 Parser Options and dspcl Options 2-40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−6 Optimizer Options and dspcl Options 2-42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2−7 Code Generator Options and dspcl Options 2-44. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−1 Options That You Can Use With −o3 3-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−2 Selecting a Level for the −ol Option 3-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−3 Selecting a Level for the −on Option 3-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−4 Selecting a Level for the −op Option 3-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−5 Special Considerations When Using the −op Option 3-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4−1 Run-Time-Support Source Libraries 4-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4−2 Sections Created by the Compiler 4-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5−1 TMS320C2x/C2xx/C5x C Data Types 5-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5−2 Absolute Compiler Limits 5-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−1 Register Use and Preservation Conventions 6-10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−2 Status Register Fields 6-11. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7−1 Macros That Supply Integer Type Range Limits (limits.h) 7-6. . . . . . . . . . . . . . . . . . . . . . . . . . .

7−2 Macros That Supply Floating-Point Range Limits (float.h) 7-7. . . . . . . . . . . . . . . . . . . . . . . . . .

7−3 Summary of Run-Time-Support Functions and Macros 7-14. . . . . . . . . . . . . . . . . . . . . . . . . . . .

8−1 Summary of Options and Their Effects 8-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xiv

Examples

2−1 How the Runtime-Support Library Uses the _INLINE Preprocessor Symbol 2-32. . . . . . . . . .

2−2 An Interlisted Assembly Language File 2-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−1 Repeat Blocks, Autoincrement Addressing, Parallel Instructions, Strength

3−2 Delayed Branch, Call, and Return Instructions 3-17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−3 Data-Flow Optimizations 3-19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−4 Copy Propagation and Control-Flow Simplification 3-20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3−5 Inline Function Expansion 3-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4−1 An Example of a Linker Command File 4-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5−1 Using the CODE_SECTION Pragma 5-7. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5−2 Using the DATA_SECTION Pragma 5-8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−1 TMS320C2x Code as a Called Function 6-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−2 An Assembly Language Function 6-21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−3 Accessing a Variable Defined in .bss From C 6-23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6−4 Accessing a Variable Not Defined in .bss From C 6-24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Reduction, Induction Variable Elimination, Register Variables, and Loop

Test Replacement 3-16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xvContents

Notes

Version Information 1-1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Function Inlining Can Greatly Increase Code Size 2-27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the −s Option With the Optimizer 2-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Symbolic Debugging and Optimized Code 3-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The _c_int0 Symbol 4-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

TMS320C2x/C2xx/C5x Byte Is 16 Bits 5-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Avoid Disrupting the C Environment With asm Statements 5-9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

The Linker Defines the Memory Map 6-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Stack Overflow 6-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using AR6 and AR7 as Global Register Variables 6-13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the asm Statement 6-22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Customizing Time Functions 7-12. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Writing Your Own Clock Function 7-27. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Writing Your Own Time Function 7-57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

TMS320C2x/C2xx/C5x Byte Is 16 Bits A-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xvi

Chapter 1

Introduction

The TMS320C2x, TMS320C2xx, and TMS320C5x devices are members of the TMS320 family of high-performance CMOS microprocessors optimized for digital signal processing applications.

The TMS320C2x/C2xx/C5x DSPs are supported by a set of software development tools, which includes an optimizing C compiler, an assembler, a linker, an archiver, a software simulator, a full-speed emulator, and a software development board.

This chapter provides an overview of these tools and introduces the features of the optimizing C compiler. The assembler and linker are discussed in detail in the TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide.

Note: Version Information

To use the TMS320C2x/C2xx/C5x C compiler, you must also have version

5.0 (or later) of the TMS320C1x/C2x/C2xx/C5x assembler and linker.

Topic Page

1.1 Software Development Tools Overview 1-2. . . . . . . . . . . . . . . . . . . . . . . . . .

1.2 C Compiler Overview 1-5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1Introduction

Software Development Tools Overview

1.1 Software Development Tools Overview

Figure 1−1 illustrates the TMS320C2x/C2xx/C5x software development flow. The shaded portion of the figure highlights the most common path of software development for C language programs. The unshaded portions represent peripheral functions that enhance the development process.

Figure 1−1. TMS320C2x/C2xx/C5x Software Development Flow

source

files

Macro

source

files

C compiler

Archiver

Macro library

Archiver

Library of

object files

Hex conversion

utility

EPROM

programmer

Absolute lister

Assembler

source

Assembler

COFF object

files

Linker

Executable

COFF

file

Cross-reference

lister

Library-build

utility

Run-time-

support

library

Debugging

tools

TMS320C2x

TMS320C2xx

TMS320C5x

1-2

Software Development Tools Overview

The following list describes the tools that are shown in Figure 1−1.

- The C compiler accepts C source code and produces TMS320C2x,

TMS320C2xx, or TMS320C5x assembly language source code. A shell program, an optimizer, and an interlist utility are included in the compiler package.

J The shell program enables you to automatically compile, assemble,

and link source modules.

J The optimizer modifies code to improve the efficiency of C programs.

J The interlist utility interlists C source statements with assembly lan-

guage output.

Chapter 2 describes how to invoke and operate the compiler, the shell, the optimizer, and the interlist utility.

- The assembler translates assembly language source files into machine

language object files. The machine language is based on common object file format (COFF). The TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide explains how to use the assembler.

- The TMS320C1x/C2x/C5x Assembly Language Tools User’s Guide ex-

plains how to use the archiver. The linker combines object files into a single executable object module. As it creates the executable module, it performs relocation and resolves external references. The linker accepts relocatable COFF object files and object libraries as input.

- The archiver allows you to collect a group of files into a single archive file,

called a library. Using the archiver, you can modify a library by deleting, replacing, extracting, or adding members. One of the most useful applications of the archiver is building a library of object modules. Three object libraries are shipped with the C compiler:

J rts25.lib contains ANSI standard run-time-support functions and

compiler-utility functions for the TMS320C2x.

J rts50.lib contains ANSI standard run-time-support functions and

compiler-utility functions for the TMS320C5x.

J rts2xx.lib contains ANSI standard run-time-support functions and

compiler-utility functions for the TMS320C2xx.

- The library-build utility allows you to build a customized run-time-sup-

port library. Standard run-time-support library functions are provided as source code. These are located in rts.src. See Chapter 8, Library-Build Utility, for more information.

1-3Introduction

Software Development Tools Overview

- The hex conversion utility converts a COFF object file into TI-Tagged,

ASCII-hex, Intel, Motorola-S, or Tektronix object format. The converted file can be downloaded to an EPROM programmer.

- The absolute lister is a debugging tool. It accepts linked object files as

input and creates .abs files as output. Once assembled, these .abs files produce lists that contain absolute rather than relative addresses. See the TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide for more information about how to use the absolute lister.

- The cross-reference lister uses object files to produce a cross-reference

listing showing symbols, their definitions, and their references in the linked source files. See the TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide for more information about how to use the cross-reference lister.

- The main product of this development process is a module that you can

execute on a TMS320C2x/C2xx/C5x device. You can use one of several debugging tools to refine and correct your code. Available products include:

J An instruction-accurate software simulator J An extended development system (XDS-510) emulator J An evaluation module (EVM)

1-4

1.2 C Compiler Overview

The TMS320C2x/C2xx/C5x C compiler is a full-featured optimizing compiler that translates standard ANSI C programs into TMS320C2x/C2xx/C5x assembly language source. The following list describes key characteristics of the compiler:

- ANSI-standard C

The TMS320C2x/C2xx/C5x compiler fully conforms to the ANSI C standard as defined by the ANSI specification and described in the second edition of Kernighan and Ritchie’s The C Programming Language (K&R). The ANSI C standard includes extensions to C that provide maximum portability and increased capability.

- ANSI-standard run-time support

The compiler tools include a complete run time library for each device. All library functions conform to the ANSI C library standard. The libraries include functions for string manipulation, dynamic memory allocation, data conversion, timekeeping, trigonometry, and exponential and hyperbolic functions. Functions for I/O and signal handling are not included because these are target-system specific. For more information, see Chapter 7,

Run-Time-Support Functions.

C Compiler Overview

- Assembly source output

The compiler generates assembly language source files that you can inspect easily, enabling you to see the code generated from the C source files.

- COFF object files

The common object file format (COFF) allows you to define your system’s memory map at link time. This maximizes performance by enabling you to link C code and data objects into specific memory areas. COFF also supports source-level debugging.

- Compiler shell program

The compiler tools include a shell program used to compile, and link programs in a single step. For more information, see section 2.1, About the Shell Program, on page 2-2.

- Flexible assembly language interface

The compiler has clear calling conventions, allowing you to easily write assembly and C functions that call each other. For more information, see Chapter 6, Run-Time Environment.

1-5Introduction

C Compiler Overview

- Integrated preprocessor

The C preprocessor is integrated with the parser, allowing for faster compilation. Standalone preprocessing or preprocessed listing is also available. For more information, see section 2.5, Controlling the Preprocessor, on page 2-23.

- Optimization

The compiler uses an optimization pass that employs several advanced techniques for generating efficient, compact code from C source. General optimizations can be applied to any C code, and TMS320C2x/C2xx/C5xspecific optimizations take advantage of the TMS320C2x/C2xx/C5x architecture. For more information about the C compiler’s optimization techniques, see Chapter 3, Optimizing Your Code.

- Code to initialized data into ROM

For standalone embedded applications, the compiler enables you to link all code and initialization data into ROM, allowing C code to run from reset.

- Source interlist utility

The compiler tools include a utility that interlists your original C source statements into the assembly language output of the compiler. Using this utility, you can easily inspect the assembly code generated for each C statement. For more information, see section 2.7, Using the Interlist Utility, on page 2-34.

- Library-build utility

The compiler tools include a utility that lets you easily custom-build object libraries from source for any combination of run time models or target CPUs. For more information, see Chapter 8, Library-Build Utility.

1-6

Chapter 2

C Compiler Description

Translating your source program into code that the TMS320C2x/C2xx/C5x can execute is a multistep process. You must compile, assemble, and link your source files to create an executable object file. The TMS320C2x/C2xx/C5x package contains a special shell program that enables you to execute all of these steps with one command. This chapter provides a complete description of how to use the dspcl shell to compile, assemble, and link your programs.

This chapter also describes the preprocessor, inline function expansion features, and interlist utility:

Topic Page

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.4 Changing the Compiler’s Behavior

With Environment Variables 2-21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.5 Controlling the Preprocessor 2-23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.6 Using Inline Function Expansion 2-28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.7 Using the Interlist Utility 2-34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2.8 Understanding and Handling Compiler Errors 2-36. . . . . . . . . . . . . . . . . . .

2.9 Invoking the Tools Individually 2-39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-1C Compiler Description

About the Shell Program

2.1 About the Shell Program

The compiler shell program (dspcl) lets you compile, assemble, and optionally link in one step. The shell runs one or more source modules through the following:

- The compiler, which includes the parser, optimizer, and code generator,

accepts C source code and produces ’C2x, ’C2xx, ’C5x, assembly language source code.

- The assembler generates a COFF object file.

- The linker links your files to create an executable object file. Use of the

linker is optional at this point. You can compile and assemble various files with the shell and link them later. See Chapter 4, Linking C Code, for information about linking the files in a separate step.

The shell compiles and assembles files by default. If you use the −z option, dspcl will compile, assemble, and link your files. Figure 2−1 illustrates the paths the shell follows as it both uses and omits the linker.

2-2

Figure 2−1. The Shell Program Overview

source

files

C Compiler

Parser

Optimizer

(optional)

Code

generator

Assembler

source

About the Shell Program

With the −z Option

Assembler

COFF object

files

Linker

Executable

COFF file

For a complete description of the assembler and the linker, see the TMS320C2x/C2xx/C5x Assembly Language Tools User’s Guide. For information about invoking the compiler tools individually, see section 2.9, Invoking the Tools Individually, on page 2-39.

2-3C Compiler Description

Invoking the Compiler Shell

2.2 Invoking the Compiler Shell

To invoke the compiler shell, enter:

dspcl [options] filenames [−z] [linker options] [object files]]

dspcl is the command that runs the compiler and the assembler.

options affect the way the shell processes input files.

filenames are one or more C source files, assembly source files, or

−z is the option that runs the linker. See Chapter 4, Linking C

linker options control the linking process.

object files name the object files that the compiler creates.

The −z option and its associated information (linker options and object files) must follow all filenames and compiler options on the command line. You can specify all other options (except linker options) and filenames in any order on the command line. For example, if you wanted to compile two files named symtab.c and file.c, assemble a third file named seek.asm, and suppress progress messages (−q), you enter:

object files.

Code, for more information about invoking the linker.

dspcl −q symtab file seek.asm

As dspcl encounters each source file, it prints the C filenames in square brackets ( [ ] ) and assembly language filenames in angle brackets ( < > ). This example uses the −q option to suppress the additional progress information that dspcl produces. Entering the command above produces these messages:

[symtab] [file] <seek.asm>

2-4

Invoking the Compiler Shell

The normal progress information consists of a banner for each compiler pass and the names of functions as they are defined. The example below shows the output from compiling a single module without the − q option:

”symtab.c”: ==> main

PASS 1

PASS 2

No Errors, No Warnings

2-5C Compiler Description

Changing the Compiler’s Behavior With Options

2.3 Changing the Compiler’s Behavior With Options

Options control the operation of both the shell and the programs it runs. This section provides a description of option conventions and an option summary table. It also provides detailed descriptions of the most frequently used options, including options used for type-checking and assembling.

The following apply to the compiler options:

- Options are either single letters or two-letter pairs.

- Options are not case sensitive.

- Options are preceded by a hyphen.

- Single-letter options without parameters can be combined. For example,

−sgq is equivalent to −s −g −q.

- Two-letter pair options that have the same first letter can be combined. For

example, −pe, −pf, and −pk can be combined as −pefk.

- Options that have parameters, such as −uname and −idirectory, cannot

be combined. They must be specified separately.

- Options with parameters can have a space between the option and the

parameter or be right next to each other.

- Files and options can occur in any order except the −z option. The −z op-

tion must follow all other compiler options and precede any linker options.

You can define default options for the shell by using the C_OPTION environment variable. For a detailed description of the C_OPTION environment variable, see section 2.4.1, Setting Default Shell Options (C_OPTION), on page 2-21.

Table 2−1 summarizes all shell and linker options. Use the page references in the table to refer to more complete descriptions of the options.

For an online summary of all the shell and linker options, enter dspcl with no parameters on the command line.

2-6

Table 2−1. Shell Options Summary

(a) Options that control the compiler shell

Option Effect Page(s)

Changing the Compiler’s Behavior With Options

−@filename Interprets contents of a file as one extension to the command line

−c Disables linking (negate −z) 2-14,

−d name[=def] Predefines name 2-14

−g Enables symbolic debugging 2-14

−i directory Defines #include search path 2-14

−k Keeps the assembly language (.asm) file 2-14

−n Compiles only 2-14

−q Suppresses progress messages (quiet) 2-14

−qq Suppresses all messages (super quiet) 2-14

−r <register> Reserves global register 2-14

−s Interlists optimizer comments (if available) and

assembly source statements; otherwise, interlists C and assembly source statements

−ss Interlists optimizer comments with C source and assembly statements

−uname Undefines name 2-15

2-14

4-5

2-15; 2-34

2-15

−v xx Determines processor: xx = 25, 2xx or 50 2-15

−z

(b) Options that specify file and directory names

Option

−fafilename Identifies assembly language file (default for .asm

−fcfilename Identifies C source file (default for .c or no extension) 2-16

−fofilename Identifies object file (default for .o*) 2-16

Enables linking 2-15

Effect Page

2-16

or .s*)

2-7C Compiler Description

Changing the Compiler’s Behavior With Options

Table 2−1. Shell Options Summary (Continued)

Option

−eaextension Sets default extension for assembly files 2-17

−eoextension Sets default extension for object files 2-17

(d) Options that specify directories

Option

−frdirectory Specifies object file directory 2-17

−fsdirectory Specifies assembly file directory 2-17

−ftdirectory Override TMP environment variable 2-17

(e) Options that overlook ANSI C type-checking

Option

−tf Relaxes prototype checking 2-18

−tp Relaxes pointer combination 2-18

(f) Options that change the C run-time model

Option

Effect Page

−ma Assumes variables are aliased 2-19

− mb Disables RPTK instruction 2-19

−ml No LDPK optimization 2-19

−mn Enables optimizations disabled by −g 2-19

− mp Generates prolog/epilog inline 2-19

− mr Lists register-use information 2-19

− ms Optimizes for code space 2-19

− mx Avoids ’C5x silicon bugs 2-19

2-8

+ 220 hidden pages

Texas Instruments TMS320C2x, TMS320C2xx, TMS320C5x User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

IMPORTANT NOTICE

About This Manual

Preface

Read This First

How to Use This Manual

Notational Conventions

Related Documentation From Texas Instruments

Related Documentation

Trademarks

Contents

Figures

Tables

Examples

Notes

Introduction

Topic Page

1.1 Software Development Tools Overview

1.2 C Compiler Overview

C Compiler Description

Topic Page

2.1 About the Shell Program

2.2 Invoking the Compiler Shell

2.3 Changing the Compiler’s Behavior With Options