Texas Instruments TMS320C2x, TMS320C2xx, TMS320C5x User Manual

Download

Page 1

TMS320C2x/C2xx/C5x

Optimizing C Compiler

User’s Guide

Literature Number: SPRU024E

August 1999

Printed on Recycled Paper

Page 2

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.

Page 3

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

Page 4

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.

Page 5

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

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

Page 15

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

Page 16

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

Page 17

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

Page 18

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

Page 19

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

Page 20

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

Page 21

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

Page 22

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

Page 23

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

Page 24

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

Page 25

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

Page 26

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

Page 27

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

Page 28

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

Page 29

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

Page 30

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

Page 31

Table 2−1. Shell Options Summary (Continued)

(g) Options that control the parser

Option Effect Page

−p? Enables trigraph expansion 2-27

−pe Treats code-E errors as warnings 2-37

−pf Generates function prototype listing file 2-27

−pk Allows K&R compatibility

−pl Generates preprocessed listing (.pp file) 2-26

Changing the Compiler’s Behavior With Options

−pm Combines source files to perform program-level optimization

−pn Suppresses #line directives in a .pp file 2-26

−po Preprocesses only 2-26

− pr Generates an error listing 2-37

−pw0 Disables all warning messages 2-37

−pw1 Enables serious warning messages (default) 2-37

−pw2 Enables all warning messages 2-37

−pxfilename Names the output file created when using the −pm

option

(h) Options that control the definition-controlled inline function expansion

Option

−x0 Disables inline expansion of intrinsic operators 2-29

−x1 Enables inline expansion of intrinsic operators

−x2 or −x Defines the symbol _INLINE and invokes the

Effect Page

(default)

optimizer with −o2

3-6

3-9

2-29

2-9C Compiler Description

Page 32

Changing the Compiler’s Behavior With Options

Table 2−1. Shell Options Summary (Continued)

(i) Options that control the assembler

Option

−aa Enables absolute listing 2-20

−adname Defines variables from the command line 2-20

−ahcfilename Copies filename before any source statements from

−ahifilename Includes filename before any source statements

−al Generates an assembly listing file 2-20

−ap Enables the ’C2x to ’C2xx or ’C5x port switch 2-20

−app Enables the ’C2x to ’C2xx port switch and defines

−as Puts labels in the symbol table 2-20

−auname Undefines variables from the command line 2-20

−ax

Effect Page

2-20

the input file are assembled

2-20

from the input file are assembled

2-20

.TMS32025 and .TMS3202xx

Generates the cross-reference file 2-20

2-10

Page 33

Table 2−1. Shell Options Summary (Continued)

(j) Options that control optimizations

Option Effect Page

−o0 Optimizes register usage 3-2

−o1 Uses −o0 optimizations and optimizes locally 3-2

−o2 or −o Uses −o1 optimizations and optimizes globally 3-2

−o3 Uses −o2 optimizations and optimizes the file 3-3

Changing the Compiler’s Behavior With Options

−oe Assumes no function in the module is called from an interrupt routine, and that none of the routines in the module are called recursively

−oisize Sets automatic inlining size (−o3 only) 3-12

−ol0 (−oL0) Informs the optimizer that your file alters a standard

library function

−ol1 (−oL1) Informs the optimizer that your file declares a stan- dard library function

−ol2 (−oL2) Informs the optimizer that your file does not declare or alter library functions. Overrides the −ol0 and −ol1 options (default).

−on0 Disables the optimization information file 3-5

−on1 Produces an optimization information file 3-5

−on2 Produces a verbose optimization information file 3-5

−op0 Specifies that the module contains functions and

variables that are called or modified from outside the source code provided to the compiler

−op1 Specifies that the module contains variables modi- fied from outside the source code provided to the compiler but does not use functions called from outside the source code

3-11

3-4

3-6

−op2 Specifies that the module contains no functions or variables that are called or modified from outside the source code provided to the compiler (default)

−op3

Specifies that the module contains functions that are called from outside the source code provided to the compiler but does not use variables modified from outside the source code

3-6

2-11C Compiler Description

Page 34

Changing the Compiler’s Behavior With Options

−os Interlists optimizer comments with assembly state- ments

3-13

2-12

Page 35

Table 2−1. Shell Options Summary (Continued)

(k) Options that control the linker

Changing the Compiler’s Behavior With Options

Options

−a Generates absolute executable output 4-6

−ar Generates relocatable executable output 4-6

−b Disables merge of symbolic debugging information 4-6

−c Autoinitializes variables at run time 4-6

−cr Initializes variables at reset 4-6

−eglobal_symbol Defines entry point 4-6

−ffill_value Defines fill value 4-6

−gglobal_symbol Keeps global_symbol global (overrides −h) 4-6

−h Makes global symbols static 4-6

−heap size Sets heap size (bytes) 4-6

−idirectory Defines library search path 4-6

−lfilename Supplies library or command filename 4-6

−mfilename Names the map file 4-6

−n Ignores all fill specifications in MEMORY directives 4-6

−ofilename Names the output file 4-7

Effect Page

−q Suppresses progress messages (quiet) 4-7

−r Generates relocatable nonexecutable output 4-7

−s Strips symbol table information and line number en-

tries from the output module

−stack size Sets stack size (bytes) 4-7

−usymbol Undefines symbol 4-7

−v0 Generates version 0 COFF format 4-7

−v1 Generates version 1 COFF format 4-7

−v2 Generates version 2 COFF format 4-7

−w Displays a message when an undefined output

section is created

−x

Forces rereading of libraries 4-7

4-7

2-13C Compiler Description

Page 36

Changing the Compiler’s Behavior With Options

2.3.1 Frequently Used Options

−@ filename Appends the contents of a file to the command line. You can

−c Suppresses the linker and overrides the −z option, which

−dname[=def] Predefines the constant name for the preprocessor. This is

−g Generates symbolic debugging directives that are used by

−idirectory Adds directory to the list of directories that the compiler

use this option to avoid limitations on command line length imposed by the host operating system. Use a # or j; at the beginning of a line in the command file to include comments.

specifies linking. Use this option when you have −z specified in the C_OPTION environment variable and you do not want to link. For more information, see section 4.3, Disabling the Linker (−c Shell Option), on page 4-5.

equivalent to inserting #define name def at the top of each C source file. If the optional [=def] is omitted, the name is set to 1.

the C-source-level debuggers and enables assembly source debugging in the assembler.

searches for #include files. You can use this option a maximum of 32 times to define several directories. You must separate − i options with spaces. If you do not specify a directory name, the preprocessor ignores the − i option. For more information, see section 2.5.3, Changing the #include File Search Path With the −i Option, on page 2-25.

−k Retains the assembly language output from the compiler.

Normally, the shell deletes the output assembly language file after assembling completes.

−n Compiles only. The specified source files are compiled but

not assembled or linked. This option overrides −z. The output is assembly language output from the compiler.

−q Suppresses banners and progress information from all the

tools. Only source filenames and error messages are output.

−qq Suppresses all output except error messages.

−rregister Reserves register globally so that the code generator and

optimizer cannot use it as a normal save-on-entry register.

2-14

Page 37

Changing the Compiler’s Behavior With Options

−s Invokes the interlist utility, which interweaves optimizer comments or C source with assembly source. If the optimizer is invoked (−on option), optimizer comments are interlisted with the assembly language output of the compiler. If the optimizer is not invoked, C source statements are interlisted with the assembly language output of the compiler, which allows you to inspect the code generated for each C statement. The −s option implies the −k option.

−ss Invokes the interlist utility, which interweaves original C source with compiler-generated assembly language. If the optimizer is invoked (−on option), this option might reorga- nize your code substantially. For more information, see section 2.7, Using the Interlist Utility, on page 2-34.

−uname Undefines the predefined constant name. This option overrides any − d options for the specified constant.

−vxxx Specifies the target processor. Choices for xxx are 25 for a ’C2x processor, 2xx for a ’C2xx, or 50 for a ’C5x.

−z Runs the linker on the specified object files. The −z option and its parameters follow all other options and parameters on the command line. All arguments that follow −z are passed to the linker. For more information, see section 4.1, Invoking the Linker as an Individual Program, on page 4-2.

2-15C Compiler Description

Page 38

Changing the Compiler’s Behavior With Options

2.3.2 Specifying Filenames

The input files that you specify on the command line can be C source files, assembly source files, or object files. The shell uses filename extensions to determine the file type.

Extension File Type

.c or none (.c is assumed) C source

.asm, .abs, or .s* (extension begins with s) Assembly source

.obj Object

Files without extensions are assumed to be C source files. The conventions for filename extensions allow you to compile C files and optimize and assemble assembly files with a single command.

For information about how you can alter the way that the shell interprets individual filenames, see section 2.3.3 on page 2-16. For information about how you can alter the way that the shell interprets and names the extensions of assembly source and object files, see section 2.3.5 on page 2-17.

You can use wildcard characters to compile or assemble multiple files. Wildcard specifications vary by system; use the appropriate form listed in your operating system manual. For example, to compile all of the C files in a directory, enter the following:

dspcl *.c

2.3.3 Changing How the Shell Program Interprets Filenames (−fa, −fc, and −fo Options)

You can use options to change how the shell interprets your filenames. If the extensions that you use are different from those recognized by the shell, you can use the −fa, −fc, and −fo options to specify the type of file. You can insert an optional space between the option and the filename. Select the appropriate option for the type of file you want to specify:

−fafilename for an assembly language source file

−fcfilename for a C source file

−fofilename for an object file

For example, if you have a C source file called file.s and an assembly language source file called assy, use the −fa and −fc options to force the correct interpretation:

dspcl −fc file.s −fa assy

You cannot use the −fa, −fc, and −fo options with wildcard specifications.

2-16

Page 39

Changing the Compiler’s Behavior With Options

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

−eo Options)

You can use options to change how the shell program interprets filename extensions and names the extensions of the files that it creates. The −ea and −eo options must precede the filenames they apply to on the command line. You can use wildcard specifications with these options. An extension can be up to nine characters in length. Select the appropriate option for the type of extension you want to specify:

−ea[.] new extension for an assembly language file

−eo[.] new extension for an object file

The following example assembles the file fit.rrr and creates an object file named fit.o:

dspcl −ea .rrr −eo .o fit.rrr

The period (.) in the extension and the space between the option and the extension are optional. You can also write the example above as:

dspcl −earrr −eoo fit.rrr

2.3.5 Specifying Directories

By default, the shell program places the object, assembly, and temporary files that it creates into the current directory. If you want the shell program to place these files in different directories, use the following options:

−frdirectory Specifies a directory for object files. To specify an object file direc-

−fsdirectory Specifies a directory for assembly files. To specify an assembly file

−ftdirectory Specifies a directory for temporary intermediate files. The −ft op-

tory, type the directory’s pathname on the command line after the

−fr option:

dspcl −fr d:\object

directory, type the directory’s pathname on the command line after the −fs option:

dspcl −fs d:\assembly

tion overrides the TMP environment variable. (For more information, see section 2.4.2, Specifying a Temporary File Directory (TMP), on page 2-22.) To specify a temporary directory, type the directory’s pathname on the command line after the −ft option:

dspcl −ft c:\temp

2-17C Compiler Description

Page 40

Changing the Compiler’s Behavior With Options

2.3.6 Options That Overlook ANSI C Type Checking

Following are options that you can use to overlook some of the strict ANSI C type checking on your code:

−tf Overlooks type checking on redeclarations of prototyped func- tions. In ANSI C, if a function is declared with an old-format declaration and later declared with a prototype (as in the example below), this generates an error because the parameter types in the prototype disagree with the default argument promotions (which convert float to double and char to int).

int func( ) /* old format */

int func(float a, char b) /* new format */

−tp Overlooks type checking on pointer combinations. This option has two effects:

- A pointer to a signed type can be combined in an operation with

a pointer to the corresponding unsigned type:

int *pi; unsigned *pu; pi = pu; /* Illegal unless -tp used */

- Pointers to differently qualified types can be combined:

char *p; const char *pc; p = pc; /* Illegal unless -tp used */

The −tp option is especially useful when you pass pointers to prototyped functions, because the passed pointer type would ordinarily disagree with the declared parameter type in the prototype.

2-18

Page 41

2.3.7 Run-Time-Model Options

−ma Assumes variables are aliased. The compiler assumes that pointers may alias (point to) named variables and aborts register optimizations when an assignment is made through a pointer.

−mb Disables the noninterruptible RPTK instruction for moving structures.

−ml Disables an optimization that the code generator performs to minimize the use of the LDPK instruction. This optimization can cause small holes in the .bss section of a program. Using the − ml option eliminates these holes entirely but at the expense of added LDPK instructions in the code. This could be a preferable tradeoff if your system uses a less expensive form of memory for program memory space than it does for data memory space.

−mn Reenables the optimizations disabled by − g. If you use the − g option to generate symbolic debugging information, many code generator optimizations are disabled because they disrupt the debugger.

−mr Lists register-use information. After the code generator compiles each C statement, −mr lists register content tables as comments in the assembly language file. The −mr option is useful for inspecting code that is difficult to follow due to register tracking optimizations.

Changing the Compiler’s Behavior With Options

−ms Optimizes for code space instead of for speed.

−mx Avoids ’C5x silicon bugs. Use of this switch is necessary when

preparing a program for use with ’C5x device versions earlier than

2.0 that implements interrupts or is compiled with optimization.

When the compiler is run with the OVLY and RAM status bits on, certain compiled code sequences do not execute correctly when both the code and the data reside in the 1K of on-chip RAM on the ’C51 or the same 2K block of the 9K of on-chip RAM on the ’C50. Use a linker command file to set the program and data spaces so that this conflict does not occur.

2-19C Compiler Description

Page 42

Changing the Compiler’s Behavior With Options

2.3.8 Options That Control the Assembler

Following are assembler options that you can use with the shell:

−aa Invokes the assembler with the −a assembler option, which creates an absolute listing. An absolute listing shows the absolute addresses of the object code.

−adname Invokes the assembler with the −hc assembler option to tell the assembler to copy the specified file for the assembly module. The file is inserted before source file statements. The copied file appears in the assembly listing files.

−ahcfilename Invokes the assembler with the −hc assembler option to tell the assembler to copy the specified file for the assembly module. The file is inserted before source file statements. The copied file appears in the assembly listing files.

−ahifilename Invokes the assembler with the −hi assembler option to tell the assembler to include the specified file for the assembly module. The file is included before source file statements. The included file does not appear in the assembly listing files.

−al Invokes the assembler with the −l (lowercase L) assembler option to produce an assembly listing file.

−ap Enables ’C2x to ’C2xx or ’C5x port switch. Use −ap with the corresponding −v2xx or −v50 option.

−app Enables ’C2x to ’C2xx port switch and defines the .TMS32025 and .TMS3202xx assembler symbols. Use −app with the −v2xx option.

−as Invokes the assembler with the −s assembler option to put labels in the symbol table. Label definitions are written to the COFF symbol table for use with symbolic debugging.

−auname Invokes the assembler with the −u assembler option to unde- fine the predefined constant name. The −au option overrides the −ad option for the specified constant.

−ax Invokes the assembler with the −x assembler option to pro- duce a symbolic cross-reference in the listing file.

For more information about assembler options, see the TMS320C6000

Assembly Language Tools User’s Guide.

2-20

Page 43

Changing the Compiler’s Behavior With Environment Variables

2.4 Changing the Compiler’s Behavior With Environment Variables

You can define environment variables that set certain software tool parameters you normally use. An environment variable is a special system symbol that you define and associate to a string in your system initialization file. The compiler uses this symbol to find or obtain certain types of information.

When you use environment variables, default values are set, making each individual invocation of the compiler simpler because these parameters are automatically specified. When you invoke a tool, you can use command-line options to override many of the defaults that are set with environment variables.

2.4.1 Setting Default Shell Options (C_OPTION)

You might find it useful to set the compiler, assembler, and linker shell default options using the C_OPTION environment variable. If you do this, the shell uses the default options and/or input filenames that you name with C_OPTION every time you run the shell.

Setting the default options with the C_OPTION environment variable is useful when you want to run the shell consecutive times with the same set of options and/or input files. After the shell reads the command line and the input filenames, it looks for the C_OPTION environment variable and processes it.

The table below shows how to set the C_OPTION environment variable. Select the command for your operating system:

Operating System Enter

DOS or OS/2 set C_OPTION=option1[;option2 . . .]

UNIX with C shell setenv C_OPTION ”option1 [option2 . . .]”

UNIX with Bourne or Korn shell

C_OPTION=”option1 [option2 . . .]” export C_OPTION

Environment variable options are specified in the same way and have the same meaning as they do on the command line. For example, if you want to always run quietly (the −q option), enable C source interlisting (the −s option), and link (the −z option) for Windows, set up the C_OPTION environment variable as follows:

set C_OPTION=−qs −z

2-21C Compiler Description

Page 44

Changing the Compiler’s Behavior With Environment Variables

In the following examples, each time you run the compiler shell, it runs the linker. Any options following −z on the command line or in C_OPTION are passed to the linker. This enables you to use the C_OPTION environment variable to specify default compiler and linker options and then specify additional compiler and linker options on the shell command line. If you have set −z in the environment variable and want to compile only, use the −c option of the shell. These additional examples assume C_OPTION is set as shown above:

dspcl *c ; compiles and links dspcl −c *.c ; only compiles dspcl *.c −z lnk.cmd ; compiles and links using a ; command file dspcl −c *.c −z lnk.cmd ; only compiles (−c overrides −z)

For more information about shell options, see section 2.3, Changing the Compiler’s Behavior With Options, on page 2-6. For more information about linker options, see section 4.4, Linker Options, on page 4-6.

2.4.2 Specifying a Temporary File Directory (TMP)

The compiler shell program creates intermediate files as it processes your program. By default, the shell puts intermediate files in the current directory. However, you can name a specific directory for temporary files by using the TMP environment variable.

Using the TMP environment variables allows use of a RAM disk or other file systems. It also allows source files to be compiled from a remote directory without writing any files into the directory where the source resides. This is useful for protected directories.

The table below shows how to set the TMP environment variable. Select the command for your operating system:

Operating System Enter

DOS or OS/2 set TMP=pathname

UNIX with C shell setenv TMP ”pathname”

UNIX with Bourne or Korn shell

Note: For UNIX workstations, be sure to enclose the directory name within quotes.

TMP=”pathname” export TMP

For example, to set up a directory named temp for intermediate files on your hard drive for Windows, enter:

set TMP=c:\temp

2-22

Page 45

2.5 Controlling the Preprocessor

During compilation, your code is run through the preprocessor, which is part of the parser. The shell program allows you to control the preprocessor with macros and various other preprocessor directives.

This section describes specific features that control the TMS320C2x/C2xx/ C5x preprocessor. Refer to Section A12 of K&R for a general description of C preprocessing. The TMS320C2x/C2xx/C5x C compiler includes standard C preprocessing functions, which are built into the first pass of the compiler. The preprocessor handles the following:

- Macro definitions and expansions

- #include files

- Conditional compilation

- Various other preprocessor directives (specified in the source file as lines

beginning with the # character)

The preprocessor produces self-explanatory error messages. The line number and the filename where the error occurred are printed along with a diagnostic message.

Controlling the Preprocessor

2.5.1 Predefined Macro Names

The compiler maintains and recognizes the predefined macro names listed in Table 2−2.

Table 2−2. Predefined Macro Names

Macro Name Description

__LINE__

__FILE__

__DATE__

__TIME__

_dsp Expands to 1 (identifies the TMS320C2x/C2xx/C5x compiler)

_TMS320C25 Expands to 1 under the −v25 option

_TMS320C2XX Expands to 1 under the −v2xx option

_TMS320C50 Expands to 1 under the −v50 option

_INLINE Expands to 1 under the −x or −x2 option; undefined otherwise

†

Specified by the ANSI standard

†

Expands to the current line number

Expands to the current source filename

Expands to the compilation date in the form mm dd yyyy

Expands to the compilation time in the form hh:mm:ss

2-23C Compiler Description

Page 46

Controlling the Preprocessor

You can use the names listed in Table 2−2 the same manner as any other defined name. For example:

printf ( ”%s %s” , _ _TIME _ _ , _ _ DATE _ _);

translates to a line such as:

printf (”%s %s” , ”Jan 14 1988”, ”13:58:17”);

2.5.2 The Search Path for #include Files

The #include preprocessor directive tells the compiler to read source statements from another file. When specifying the file, you can enclose the filename in double quotes or in angle brackets. The filename can be a complete pathname, partial path information, or a filename with no path information.

- If you enclose the filename in double quotes (” ”), the compiler searches

for the file in the following directories in this order:

1) The directory that contains the current source file. The current source file refers to the file that is being compiled when the compiler encounters the #include directive.

2) Directories named with the −i compiler

3) Directories set with the C_DIR environment variable

- If you enclose the filename in angle brackets (< >), the compiler searches

for the file in the following directories in this order:

1) Directories named with the −i option

2) Directories set with the C_DIR environment variable

See section 2.5.3, Changing the Include File Search Path with the −i Option, on page 2-25 for information on using the −i option. For information on how to use the C_DIR environment variable, see the TMS320C1x/C2x/C2xx/C5x

Code Generation Tools Getting Started Guide.

2-24

Page 47

Controlling the Preprocessor

2.5.3 Changing the #include File Search Path With the − i Option

The −i option names an alternative directory that contains #include files. The format of the − i option is:

−i directory1 [−i directory2 ...]

You can use up to 32 − i options per invocation of the compiler; each − i option names one directory. In C source, you can use the #include directive without specifying any directory information for the file; instead, you can specify the directory information with the −i option. For example, assume that a file called source.c is in the current directory. The file source.c contains the following directives statement:

#include ”alt.h”

Assume that the complete pathname for alt.h is:

UNIX /6xtools/files/alt.h

DOS or OS/2 c:\6xtools\files\alt.h

The table below shows how to invoke the compiler. Select the command for your operating system:

Operating System Enter

DOS or OS/2 dspcl −ic:\dsp\files source.c

UNIX dspcl −i/dsp/files source.c

2-25C Compiler Description

Page 48

Controlling the Preprocessor

2.5.4 Generating a Preprocessed Listing File (− pl Option)

The − pl option allows you to generate a preprocessed version of your source file with a .pp extension. The compiler’s preprocessing functions perform the following on the source file:

- Each source line ending in backslash (\) is joined with the following line.

- Trigraph sequences are expanded (if enabled with the −p? option).

- Comments are removed.

- #include files are copied into the file.

- Macro definitions are processed.

- Macros are expanded.

- All other preprocessing directives, including #line directives and condi-

tional compilation, are expanded.

These operations correspond to translation phases 1−3 specified in section A12 of K&R.

The preprocessed output file contains no preprocessor directives other than #line. The compiler inserts #line directives to synchronize line and file information in the output files with input position from the original source files. You can use the − pn option to suppress #line directives. See section 2.5.4.2, Remov- ing the #line Directives From the Preprocessed Listing File (−pn Option) on page 2-26 for more information.

2.5.4.1 Generating a Preprocessed Listing File Without Code Generation (−po Option)

The −po option performs only the preprocessing functions and writes out the preprocessed listing file. The −po option is used instead of the −pl option. No syntax checking or code generation occurs. The −po option is useful when debugging macro definitions. The resulting listing file is a valid C source file that you can rerun through the compiler.

2.5.4.2 Removing the #line Directives From the Preprocessed Listing File (−pn Option)

The −pn option suppresses line and file information in the preprocessed listing file. The −pn option suppresses the #line directives in the .pp file generated with the −po or −pl option:

Here is an example of a #line directive:

#line 123 file.c

The −pn option is useful when compiling machine generated source.

2-26

Page 49

Controlling the Preprocessor

2.5.5 Creating Custom Error Messages with the #error and #warn Directives

The standard #error preprocessor directive forces the compiler to issue a diagnostic message and halt compilation. The compiler extends the #error directive with a #warn directive. The #warn directive forces a diagnostic message but does not halt compilation. The syntax of #warn is identical to that of #error:

#error token-sequence

#warn token-sequence

2.5.6 Enabling Trigraph Expansion (−p? Option)

A trigraph is three characters that have a meaning (as defined by the ISO 646-1983 Invariant Code Set). On systems with limited character sets, these characters cannot be represented. For example, the trigraph ??’ equates to ^. The ANSI C standard defines these sequences.

By default, the compiler does not recognize trigraphs. If you want to enable trigraph expansion, use the −pg option. During compilation, trigraphs are expanded to their corresponding single character. For more information about trigraphs, see the ANSI specification, § 2.2.1.1.

2.5.7 Creating a Function Prototype Listing File (−pf Option)

When you use the −pf option, the preprocessor creates a file containing the prototype of every function in all corresponding C files. Each function prototype file is named as its corresponding C file with a .pro extension.

2-27C Compiler Description

Page 50

Using Inline Function Expansion

2.6 Using Inline Function Expansion

When an inline function is called, the C source code for the function is inserted at the point of the call. This is known as inline function expansion. Inline function expansion is advantageous in short functions for the following reasons:

- It saves the overhead of a function call.

- Once inlined, the optimizer is free to optimize the function in context with

the surrounding code.

Inline function expansion is performed in one of the following ways:

- Intrinsic operators are expanded by default.

- Automatic inline expansion is performed on small functions that are

invoked by the optimizer with the −o3 option. For more information, see section 3.5, Automatic Inline Expansion (−oi Option), on page 3-12.

- Definition-controlled inline expansion is performed when you invoke the

compiler with optimization (−x option) and the compiler encounters the inline keyword in code.

Note: Function Inlining Can Greatly Increase Code Size

Expanding functions inline expands code size, and inlining a function that is called in a number of places increases code size. Function inlining is optimal for functions that are called only from a small number of places and for small functions. If your code size seems too large, try compiling with the −oi0 option and note the difference in code size.

2.6.1 Inlining Intrinsic Operators

The compiler automatically expands the intrinsic operators of the target system (such as abs) by default. This expansion happens whether or not you use the optimizer and whether or not you use any compiler or optimizer options on the command line. (You can defeat this automatic inlining by invoking the compiler with the −x0 option.) Functions that expand the intrinsic operators are:

- abs

- labs

- fabs

2-28

Page 51

2.6.2 Controlling Inline Function Expansion (−x Option)

The −x option controls the definition of the _INLINE preprocessor symbol and some types of inline function expansion. There are three levels of expansion:

−x0 Causes no definition-controlled inline expansion. This option overrides the default expansions of the intrinsic operator functions, but it does not override the inline function expansions described in section 3.5, Automatic Inline Expansion (−oisize Option), on page 3-12.

−x1 Resets the default behavior. The intrinsic operators (abs, labs, and fabs) are inlined wherever they are called. Use this option to reset the default behavior from the command line if you have used another −x option in an environment variable or command file.

−x2 or −x Defines the _INLINE preprocessor symbol to be 1. If the optimizer is not invoked with a separate command-line option, this option invokes the optimizer at the default level (−o2).

Using Inline Function Expansion

2.6.3 Using the inline Keyword

Definition-controlled inline expansion is performed when you invoke the compiler with optimization and the compiler encounters the inline keyword in code. Functions with local static variables or a variable number of arguments are not inlined, with the exception of functions declared as static inline. In functions declared as static inline, expansion occurs despite the presence of local static variables. In addition, a limit is placed on the depth of inlining for recursive or nonleaf functions. Inlining should be used for small functions or functions that are called in a few places (though the compiler does not enforce this). You can control this type of function inlining with the inline keyword.

The inline keyword specifies that a function is expanded inline at the point at which it is called rather than by using standard calling procedures. The compiler performs inline expansion of functions declared with the inline keyword, and can automatically inline small functions.

2-29C Compiler Description

Page 52

Using Inline Function Expansion

For a function to be eligible for inlining:

- The function must be declared with the inline keyword, or

- The optimizer must be invoked using the −o3 switch, and

A function may be disqualified from inlining if it:

- Returns a struct or union

- Has a struct or union parameter

- Has a volatile parameter

- Has a variable length argument list

- Declares a struct, union, or enum type

- Contains a static variable

- Contains a volatile variable

- Is recursive

- Contains # pragmas

- Has too large of a stack (too many local variables)

J The function is very small (controlled by the −oi switch), and J The function is declared before it is called

2-30

Page 53

2.6.3.1 Declaring a Function as Inline Within a Module

By declaring a function as inline within a module (with the inline keyword), you can specify that the function is inlined within that module. A global symbol for the function is created (code is generated), but the function is inlined only within the module where it is declared as inline. The global symbol can be called by other modules if they do not contain a static inline declaration for the function.

Functions declared as inline are expanded when the optimizer is invoked. Using the −x2 option automatically invokes the optimizer at the default level (−o2).

Use this syntax to define a function as inline within a module:

inline return-type function-name (parameter declarations) { function }

2.6.3.2 Declaring a Function as Static Inline

Declaring a function as static inline in a header file specifies that the function is inlined in any module that includes the header. This names the function and specifies to expand the function inline, but no code is generated for the function declaration itself. A function declared in this way can be placed in header files and included by all source modules of the program.

Using Inline Function Expansion

Use this syntax to declare a function as static inline:

static inline return-type function-name (parameter declarations) {function}

2-31C Compiler Description

Page 54

Using Inline Function Expansion

2.6.4 The _INLINE Preprocessor Symbol

The _INLINE preprocessor symbol is defined (and set to 1) if you invoke the parser (or compiler shell utility) with the −x2 (or −x) option. It allows you to write code so that it runs whether or not the optimizer is used. It is used by standard header files included with the compiler to control the declaration of standard C run-time functions.

Example 2−1 on page 2-33 illustrates how the run-time-support library uses the _INLINE preprocessor symbol.

The _INLINE preprocessor symbol is used in the string.h header file to declare the function correctly, regardless of whether inlining is used. The _INLINE preprocessor symbol conditionally defines _ _INLINE so that strlen is declared as static inline only if the _INLINE preprocessor symbol is defined.

If the rest of the modules are compiled with inlining enabled and the string.h header is included, all references to strlen are inlined and the linker does not have to use the strlen in the run-time-support library to resolve any references. Otherwise, the run-time-support library code resolves the references to strlen, and function calls are generated.

Use the _INLINE preprocessor symbol in your header files in the same way that the function libraries use it so that your programs run, regardless of whether inlining is selected for any or all of the modules in your program.

Functions declared as inline are expanded whenever the optimizer is invoked at any level. Functions declared as inline and controlled by the _INLINE preprocessor symbol, such as the run-time-library functions, are expanded whenever the optimizer is invoked and the _INLINE preprocessor symbol is equal to 1. When you declare an inline function in a library, it is recommended that you use the _INLINE preprocessor symbol to control its declaration. If you fail to control the expansion using _INLINE and subsequently compile without the optimizer, the call to the function is unresolved.

In Example 2−1, there are two definitions of the strlen function. The first, in the header file, is an inline definition. Note that this definition is enabled and the prototype is declared as static inline only if _INLINE is true; that is, the module including this header is compiled with the −x option.

The second definition, for the library, ensures that the callable version of strlen exists when inlining is disabled. Since this is not an inline function, the _INLINE preprocessor symbol is undefined (#undef) before string.h is included to generate a noninline version of strlen’s prototype.

2-32

Page 55

Using Inline Function Expansion

Example 2−1. How the Run-Time-Support Library Uses the _INLINE Preprocessor Symbol

(a) string.h

/****************************************************************************/ /* STRING.H HEADER FILE */ /****************************************************************************/ typdef unsigned size_t

#if _INLINE #define __INLINE static inline /* Declaration when inlining */ #else #define __INLINE /*No declaration when not inlining */ #endif

__INLINE void *memcpy (void *_s1, const void *_s2, size_t _n);

#if _INLINE /* Declare the inlined function */

static inline void *memcpy (void *to, const void *from, size_t n) {

for (rn = 0; rn < n; rn++) *rto++ =rfrom++; return (to);

}

#endif /* _INLINE */

#undef _ _INLINE

(b) strlen.c

/****************************************************************************/ /* MEMCPY.C (rts2xx.lib) */ /****************************************************************************/ #undef _INLINE /* Turn off so code will be generated */

#include <string.h>

void *memcpy (void *to, const void *from, size_t n) {

for (rn = 0; rn < n; rn++) *rto++ =rfrom++; return (to);

}

2-33C Compiler Description

Page 56

Using the Interlist Utility

2.7 Using the Interlist Utility

The compiler tools include a utility that interlists C source statements into the assembly language output of the compiler. The interlist utility enables you to inspect the assembly code generated for each C statement. The interlist utility behaves differently depending on whether or not the optimizer is used, and depending on which options you specify.

The easiest way to invoke the interlist utility is to use the −s option. To compile and run the interlist utility on a program called function.c, enter:

dspcl −s function

The −s option prevents the shell from deleting the interlisted assembly lan- guage file. The output assembly file, function.asm, is assembled normally.

When you invoke the interlist utility without the optimizer, the interlist utility runs as a separate pass between the code generator and the assembler. It reads both the assembly and C source files, merges them, and writes the C statements into the assembly file as comments.

Example 2−2 shows a typical interlisted assembly file.

2-34

Page 57

Example 2−2. An Interlisted Assembly Language File

;>>>> main()

;>>>> int i, j; ******************************************* * FUNCTION DEF : _main ******************************************* _main:

SAR AR0,*+ SAR AR1,* LARK AR0,3 LAR AR0,*0+,AR2

;>>>> i += j;

LARK AR2,1 MAR *0+ LAC *− ADD * SACL *+

;>>>> j = i + 123;

ADDK 123 SACL *,AR1

EPI0_1:

SBRK 4 LAR AR0,* RET .end

Using the Interlist Utility

For information on how to invoke the interlist utility, outside of dspcl, refer to section 2.9.5, Invoking the Interlist Utility, page 2-46.

Note: Using the −s Option With the Optimizer

Optimization makes normal source interlisting impractical because the optimizer extensively rearranges your program. When you use the −s option, the optimizer writes reconstructed C statements. The comments also include a list of the allocated register variables. Occasionally the optimizer interlist comments may be misleading because of copy propagation or assignment of multiple or equivalent variables to the same register.

2-35C Compiler Description

Page 58

Understanding and Handling Compiler Errors

2.8 Understanding and Handling Compiler Errors

One of the compiler’s primary functions is to detect and report errors in the source program. When the compiler encounters an error in your program, it displays a message in the following format:

“file.c”, line n: [ECODE] error message

“file.c” identifies the filename.

line n identifies the line number where the error occurs.

ECODE is a 4-character error code. A single upper-case letter

identifies the error class; a 3-digit number uniquely identifies the error.

error message is the text of the message.

Errors in C code are divided into classes according to severity; these classes are identified by the letters W, E, F, and I (upper-case i). The compiler also reports other errors that are not related to C but prevent compilation. Examples of each level of error message are located in Table 2−3.

- Code-W errors are warnings resulting from a condition that is technically

undefined according to the rules of the language or that can cause unexpected results. The compiler continues running when this occurs.

- Code-E errors are recoverable, resulting from a condition that violates

the semantic rules of the language. Although these are normally fatal errors, the compiler can recover and generate an output file if you use the −pe option. See to section 2.8.2, Treating Code-E Errors as Warnings (−pe Option), on page 2-37 for more information.

- Code-F errors are fatal, resulting from a condition that violates the syn-

tactic or semantic rules of the language. The compiler cannot recover and does not generate output for code-F errors.

- Code-I errors are implementation errors, occurring when one of the

compiler’s internal limits is exceeded. These errors are usually caused by extreme behavior in the source code rather than by explicit errors. In most cases, code-I errors cause the compiler to abort immediately. Most code-I messages contain the maximum value for the limit that was exceeded. (Those limits that are absolute are also listed in section 5.9, Compiler Limits, on page 5-16.)

- Other error messages, such as incorrect command line syntax or

inability to find specified files, are usually fatal. They are identified by the symbol >> preceding the message.

2-36

Page 59

Understanding and Handling Compiler Errors

Table 2−3. Example Error Messages

Error Level Example Error Message

Code W ”file.c”, line 42:[W029] extra text after preprocessor directive ignored

Code E ”file.c”, line 66: [E055] illegal storage class for function ’f’

Code F ”file.c”, line 71: [F0108] structure member ’a’ undefined

Code I ”file.c”, line 99: [I011] block nesting too deep (max=20)

Other >> Cannot open source file ’mystery.c’

2.8.1 Generating an Error Listing (−pr Option)

Use the −pr option to generate an error listing. The error listing has the name

source.err, where source is the name of the C source file.

2.8.2 Treating Code-E Errors as Warnings (−pe Option)

A fatal error prevents the compiler from generating an output file. Normally, code-E, -F, and -I errors are fatal, while -W errors are not. The −pe option causes the compiler to treat code-E errors as warnings, so that the compiler generates code for the file despite the error.

Using −pe allows you to bend the rules of the language, so be careful; as with any warning, the compiler might not generate what you expect.

There is no way to specify recovery from code-F or -I errors. These errors are always fatal.

See section 2.8.4, An Example of How You Can Use Error Options, for an example of the −pe option.

2.8.3 Altering the Level of Warning Messages (−pw Option)

You can determine which levels of warning messages to display by setting the warning message level with the −pw option. The number following −pw denotes the level (0,1, or 2). Use Table 2−4 to select the appropriate level. See section 2.8.4, An Example of How You Can Use Error Options, for an example of the −pw option.

2-37C Compiler Description

Page 60

Understanding and Handling Compiler Errors

Table 2−4. Selecting a Level for the −pw Option

If you want to… Use option

Disable all warning messages. This level is useful when you are aware of the condition causing the warning and consider it innocuous.

Enable serious warning messages. This is the default. −pw1

Enable all warning messages. −pw2

2.8.4 An Example of How You Can Use Error Options

The following example demonstrates how you can suppress errors with the

−pe option and/or alter the level of error messages with the − pw option. The examples use this code segment:

int *pi; char *pc;

#if STDC

pi = (int *) pc;

#else

pi = pc;

#endif

- If you invoke the compiler with the − q option, this is the result:

[err]

”, line3: [E104] operands of ’=’ point to different types

”err.c

−pw0

In this case, because code-E errors are fatal, the compiler does not generate code.

- If you invoke the compiler with the − pe option, this is the result:

[err] ”err.c”, line3: [E104] operands of ’=’ point to different types

In this case, the same message is generated, but because − pe is used, the compiler ignores the error and generates an output file.

- If you invoke the compiler with the −pew2 option (combining −pe and

−pw2), this is the result:

[err.c] ”err.c”, line5: [W038] undefined preprocessor symbol ’STDC’ ”err.c”, line8: [E122] operands of ’=’ point to different types

As in the previous case, −pe causes the compiler to overlook the error and generate code. Because the −pw2 option is used, all warning messages are generated.

2-38

Page 61

2.9 Invoking the Tools Individually

The TMS320C2x/C2xx/C5x C compiler offers you the versatility of invoking all of the tools at once using dspcl, or invoking each tool individually. To satisfy a variety of applications, you can invoke the compiler (parser, optimizer, and code generator), the assembler, and the linker as individual programs. This section also describes how to invoke the interlist utility outside dspcl.

- The compiler is composed of three distinct programs: the parser, the opti-

mizer, and the code generator.

Figure 2−2. Compiler Overview

Invoking the Tools Individually

C Source

File (.c)

Parser Optimizer

.if File .opt File .asm File

Code

Generator

The input for the parser is a C source file. The parser reads the source file, checks for syntax and semantic errors, and writes out an internal representation of the program called an intermediate file. Section 2.9.1, Invoking the Parser, on page 2-40 describes how to run the parser. The parser, in addition, can be run in two passes: the first pass preprocesses the code, and the second pass parses the code.

The optimizer is an optional pass that runs between the parser and the code generator. The input is the intermediate file (.if) produced by the parser. When you run the optimizer, you choose the level of optimization. The optimizer performs the optimizations on the intermediate file and produces a highly efficient version of the file in the same intermediate file format. Chapter 3, Optimizing Your Code, describes the optimizer.

The input for the code generator is the intermediate file produced by the parser (.if) or the optimizer (.opt). The code generator produces an assembly language source file. Section 2.9.4, Invoking the Code Genera- tor, on page 2-44, describes how to run the code generator.

- The input for the assembler is the assembly language file produced by

the code generator. The assembler produces a COFF object file. The assembler is described fully in the TMS320C1x/C2x/C2xx/C5x Assembly

Language Tools User’s Guide.

2-39C Compiler Description

Page 62

Invoking the Tools Individually

- The inputs for the interlist utility are the assembly file produced by the

compiler and the C source file. The utility produces an expanded assembly source file containing statements from the C file as assembly language comments. section 2.7, Using the Interlist Utility, on page 2-34 and section

2.9.5, Invoking the Interlist Utility, on page 2-46 describe the use of the interlist utility.

- The input for the linker is the COFF object file produced by the assembler.

The linker produces an executable object file. Chapter 4, Linking C Code, describes how to run the linker. The linker is described fully in the

TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide.

2.9.1 Invoking the Parser

The first step in compiling a TMS320C2x/C2xx/C5x C program is to invoke the C parser. The parser reads the source file, performs preprocessing functions, checks syntax, and produces an intermediate file that can be used as input for the code generator. To invoke the parser, enter the following:

dspac input file [output file] [options]

dspac is the command that invokes the parser.

input file names the C source file that the parser uses as input. If you

do not supply an extension, the parser assumes that the file’s extension is .c. If you do not specify an input filename, the parser prompts you for one.

output file names the intermediate file that the parser creates. If you do

not supply a filename for the output file, the parser uses the input filename with the extension of .if.

options affect the operation of the parser. Each option for the stand-

alone parser has a corresponding dspcl option that performs the same function. Table 2−5 on page 2-41 shows the parser options, the dspcl shell options, and the corresponding functions.

2-40

Page 63

Table 2−5. Parser Options and dspcl Options

dspac Options dspcl Options Effect

− dname [def] − dname [def] Predefine macro name

− e −pe Treat code-E errors as warnings

− f − pf Generate function prototype listing file

− i dir − i dir Define #include search path

− k −pk Allow K&R compatibility

− l (lowercase L) − pl Generate .pp file

− n −pn Suppress #line directives

− o −po Preprocess only

− q −q Suppress progress messages (quiet)

−tf −tf Relax prototype checking

−tp −tp Relax pointer combination

Invoking the Tools Individually

− uname −uname Undefine macro name

−v25 −v25 Enable use of TMS320C2x instructions

−v2xx −v2xx Enable use of TMS320C2xx instructions

−v50 −v50 Enable use of TMS320C5x instructions

−w − pw Suppress warning messages

−x −x2 Enable inlining of user functions (implies − o2)

−x0 −x0 Disable function inlining

−?

− p? Enable trigraph expansion

When running dspac stand-alone and using −l to generate a preprocessed listing file, you can specify the name of the file as the third filename on the command line. This filename can appear anywhere on the command line after the names of the source file and intermediate file.

2-41C Compiler Description

Page 64

Invoking the Tools Individually

2.9.2 Parsing in Two Passes

Compiling very large source programs on small host systems such as PCs can cause the compiler to run out of memory and fail. You can avoid host memory limitations by running the parser as two separate passes. The first pass can preprocess the file, and the second pass can parse the file.

When you run the parser as one pass, it uses host memory to store both macro definitions and symbol definitions simultaneously. When you run the parser as two passes, these functions can be separated. The first pass performs only preprocessing and memory is needed only for macro definitions. In the second pass, there are no macro definitions and memory is needed only for the symbol table.

The following example illustrates how to run the parser as two passes:

1) Run the parser with the −po option, specifying preprocessing only.

dspcl −po file.c

If you want to use the − d, −u, or −i options, use them on this first pass. This pass produces a preprocessed output file called file.pp. For more information about the preprocessor, see section 2.5, Controlling the Pre- processor, on page 2-23.

2) Rerun the whole compiler on the preprocessed file to finish compiling it.

dspcl file.pp

You can use any other options on this final pass.

2.9.3 Invoking the Optimizer

Optimizing is an optional second step in compiling a TMS320C2x/C2xx/C5x C program. After parsing a C source file, you can choose to process the intermediate file with the optimizer. The optimizer improves the execution speed and reduces the size of C programs. The optimizer reads the intermediate file, optimizes it according to the level you choose, and produces an intermediate file. The intermediate file has the same format as the original intermediate file, but it enables the code generator to produce more efficient code.

2-42

Page 65

Invoking the Tools Individually

To invoke the optimizer, enter:

dspopt [input file [output file ]] [options]

dspopt is the command that invokes the optimizer.

input file names the intermediate file produced by the parser. The

optimizer assumes that the extension is .if. If you do not specify an input file, the optimizer prompts you for one.

output file names the intermediate file that the optimizer creates. If you

do not supply a filename for the output file, the optimizer uses the input filename with the extension .opt.

options affect how the the optimizer processes the input file. The

options that you use in stand-alone optimization are the same as those used for dspcl. Table 2−6 shows the optimizer options, the dspcl shell options, and the corresponding functions. Section 3.1, Using the C Compiler Optimizer, on page 3-2 provides a detailed list of the optimizations performed at each level.

Table 2−6. Optimizer Options and dspcl Options

dspopt Option dspcl Option Function

−a − ma Assume variables are aliased

−b − mb Disable the noninterruptible RPTK instruction for

− gregister − rregister Reserve global register

−hsize − olsize Control assumptions about library function calls

−in −oin Set automatic inlining size threshold (− o3 only)

− j −oe Assume no functions call, or are called by, inter-

− k − pk Allow K&R compatibility

− nn − onn Generate optimization information file (− o3 only)

− o0 − o0 Optimize at level 0; register optimization

− o1 − o1 Optimize at level 1; + local optimization

†

The −g option tells the code generator that the register named is reserved for global use. See sec- tion 5.6, Creating Global Register Variables, on page 5-10, for more information.

moving structures

†

rupt functions

2-43C Compiler Description

Page 66

Invoking the Tools Individually

Table 2−6. Optimizer Options and dspcl Options (Continued)

dspopt Option dspcl Option Function

− o2 or −o − o2 Optimize at level 2; + global optimization

− o3 − o3 Optimize at level 3; + file optimization

− q −q Suppress progress messages (quiet)

−s −s Interlist C source

−v25 −v25 Enable use of TMS320C2x instructions

−v2xx −v2xx Enable use of TMS320C2xx instructions

−v50

†

The −g option tells the code generator that the register named is reserved for global use. See sec- tion 5.6, Creating Global Register Variables, on page 5-10, for more information.

2.9.4 Invoking the Code Generator

The third step in compiling a TMS320C2x/C2xx/C5x C program is to invoke the C code generator. The code generator converts the intermediate file produced by the parser into an assembly language source file. You can modify this output file or use it as input for the assembler. The code generator produces re-entrant relocatable code, which, after assembling and linking, can be stored in ROM.

To invoke the code generator as a stand-alone program, enter:

dspcg [input file [output file [tempfile ]]] [options ]

dspcg is the command that invokes the code generator.

input file names the intermediate file that the code generator uses as

input. If you do not supply an extension, the code generator assumes that the extension is .if. If you do not specify an input file, the code generator prompts you for one.

−v50 Enable use of TMS320C5x instructions

output file names the assembly language file that the code generator

creates. If you do not supply a filename for the output file, the code generator uses the input filename with the extension

.asm.

2-44

Page 67

tempfile names a temporary file that the code generator creates and

uses. If you do not supply a filename for the temporary file, the code generator uses the input filename with the extension

.tmp. The code generator deletes this file after using it.

options affect the way the code generator processes the input file.

Each option available for the stand-alone code generator mode has a corresponding dspcl shell option that performs the same function.

Table 2−7 shows the code generator options, the dspcl shell options, and their corresponding functions.

Table 2−7. Code Generator Options and dspcl Options

dspcg Options dspcl Options Function

−a − ma Assume variables are aliased

− b −mb Disable the noninterruptible RPTK instruction

for moving structures

Invoking the Tools Individually

− gregister − rregister Reserve global register

†

− l −ml Disable optimization for reducing LDPK

instructions

− n −mn Reenable optimizations disabled by symbolic

debugging

− o −g Enable C source level debugging

− q −q Suppress progress messages (quiet)

− r − mr List register use information

−s − ms Optimize for space instead of for speed

−v25 −v25 Enable use of TMS320C2x instructions

−v2xx −v2xx Enable use of TMS320C2xx instructions

−v50 −v50 Enable use of TMS320C5x instructions

−x − mx Avoid ’C5x silicon bugs

−z

†

The −g option tells the code generator that the register named is reserved for global use. See sec- tion 5.6, Creating Global Register Variables, on page 5-10, for more information.

‡

The −z option tells the code generator to retain the input file (the intermediate file created by the parser). If you do not specify the −z option, the intermediate file is deleted.

Retain the input file

‡

2-45C Compiler Description

Page 68

Invoking the Tools Individually

2.9.5 Invoking the Interlist Utility

The fourth step in compiling a TMS320C2x/C2xx/C5x C program is optional. After you have compiled a program, you can run the interlist utility as a standalone program. To run the interlist utility from the command line, the syntax is:

clist asmfile [outfile ] [options]

clist is the command that invokes the interlist utility.

asmfile is the assembly language output from the compiler.

outfile names the interlisted output file. If you do not supply a filename

options control the operation of the utility as follows:

for the outfile, the interlist utility uses the assembly language filename with the extension .cl.

−b removes blanks and useless lines (lines containing comments and lines containing only { or }).

−q removes banner and status information.

−r removes symbolic debugging directives.

The interlist utility uses .line directives produced by the code generator to associate assembly language code with C source. For this reason, you must use the − g dspcl option to specify symbolic debugging when compiling the program if you want to interlist it. If you do not want the debugging directives in the output, use the − r interlist option to remove them from the interlisted file.

The following example shows how to compile and interlist function.c. To compile, enter:

dspcl −gk −mn function

This compiles, produces symbolic debugging directives, and keeps the assembly language file. To produce an interlist file, enter:

clist −r function

This creates an interlist file and removes the symbolic debugging directives. The output from this example is function.cl.

2-46

Page 69

2-47C Compiler Description

Page 70

Chapter 3

Optimizing Your Code

The compiler tools include an optimization program that improves the execution speed and reduces the size of C programs by performing such tasks as simplifying loops, software pipelining, rearranging statements and expressions, and allocating variables into registers.

This chapter describes how to invoke the optimizer and describes which optimizations are performed when you use it. This chapter also describes how you can use the interlist utility with the optimizer and how you can profile or debug optimized code.

Topic Page

3.1 Using the C Compiler Optimizer 3-2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.2 Using the −o3 Option 3-4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.3 Performing Program-Level Optimization

(−pm and −o3 Options) 3-6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3.4 Special Considerations When Using the Optimizer 3-10. . . . . . . . . . . . . .

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

Page 71

Using the C Compiler Optimizer

3.1 Using the C Compiler Optimizer

The optimizer runs as a separate pass between the parser and the code generator. Figure 3−1 illustrates the execution flow of the compiler with stand- alone optimization.

Figure 3−1. Compiling a C Program With the Optimizer

C source

file (.c)

Parser

.if file

Optimizer

.opt file

Code

generator

.asm file

The easiest way to invoke the optimizer is to use the dspcl shell program, specifying the −on option on the dspcl command line. The n denotes the level of optimization (0, 1, 2, and 3), which controls the type and degree of optimization:

- −o0

J Performs control-flow-graph simplification J Allocates variables to registers J Performs loop rotation J Eliminates unused code J Simplifies expressions and statements J Expands calls to functions declared inline

- −o1

Performs all −o0 optimizations, plus:

J Performs local copy/constant propagation J Removes unused assignments J Eliminates local common expressions

- −o2

Performs all −o1 optimizations, plus:

J Performs loop optimizations J Eliminates global common subexpressions J Eliminates global unused assignments J Converts array references in loops to incremented pointer form J Performs loop unrolling

The optimizer uses −o2 as the default if you use −o without an optimization level.

3-2

Page 72

Using the C Compiler Optimizer

−o3

Performs all −o2 optimizations, plus:

J Removes all functions that are never called

J Simplifies functions with return values that are never used

J Inlines calls to small functions

J Reorders function declarations so that the attributes of called func-

tions are known when the caller is optimized

J Propagates arguments into function bodies when all calls pass the

same value in the same argument position

J Identifies file-level variable characteristics

If you use −o3, see section 3.2, Using the −o3 Option, on page 3-4 for more information.

The levels of optimization described above are performed by the stand-alone optimization pass. The code generator performs several additional optimizations, particularly ’C6000-specific optimizations; it does so regardless of whether or not you invoke the optimizer. These optimizations are always enabled and are not affected by the optimization level you choose.

You can also invoke the optimizer outside dspcl; see section 2.9.3, Invoking the Optimizer, on page 2-42 for information about invoking the optimizer as a separate step.

3-3Optimizing Your Code

Page 73

Using the −o3 Option

3.2 Using the −o3 Option

The −o3 option instructs the compiler to perform file-level optimization. You can use the −o3 option alone to perform general file-level optimization, or you can combine it with other options to perform more specific optimizations. The options listed in Table 3−1 work with −o3 to perform the indicated optimization:

Table 3−1. Options That You Can Use With −o3

If you ... Use this option Page

Have files that redeclare standard library functions −oln 3-4

Want to create an optimization information file −onn 3-5

Want to compile multiple source files

3.2.1 Controlling File-Level Optimization (−oln Option)

When you invoke the optimizer with the −o3 option, some of the optimizations use known properties of the standard library functions. If your file redeclares any of these standard library functions, these optimizations become ineffective. The −ol (lowercase L) option controls file-level optimizations. The number following the −ol denotes the level (0, 1, or 2). Use Table 3−2 to select the appropriate level to append to the −ol option.

Table 3−2. Selecting a Level for the −ol Option

If your source file... Use this option

Declares a function with the same name as a standard library function

Contains but does not alter functions declared in the standard library

Does not alter standard library functions, but you used the −ol0 or −ol1 option in a command file or an environment variable. The

−ol2 option restores the default behavior of the optimizer.

−pm 3-6

−ol0

−ol1

−ol2

3-4

Page 74

3.2.2 Creating an Optimization Information File (−onn Option)

When you invoke the optimizer with the −o3 option, you can use the −on option to create an optimization information file that you can read. The number following the −on denotes the level (0, 1, or 2). The resulting file has an .nfo extension. Use Table 3−3 to select the appropriate level to append to the −on option.

Table 3−3. Selecting a Level for the −on Option

If you... Use this option

Using the −o3 Option

Do not want to produce an information file, but you used the −on1 or −on2 option in a command file or an environment variable. The

−on0 option restores the default behavior of the optimizer.

Want to produce an optimization information file −on1

Want to produce a verbose optimization information file

−on0

−on2

3-5Optimizing Your Code

Page 75

Performing Program-Level Optimization (−pm and −o3 Options)

3.3 Performing Program-Level Optimization (−pm and −o3 Options)

You can specify program-level optimization by using the −pm option with the

−o3 option. With program-level optimization, all of your source files are

compiled into one intermediate file called a module. The module moves to the optimization and code generation passes of the compiler. Because the compiler can see the entire program, it performs several optimizations that are rarely applied during file-level optimization:

- If a particular argument in a function always has the same value, the com-

piler replaces the argument with the value and passes the value instead of the argument.

- If a return value of a function is never used, the compiler deletes the return

code in the function.

- If a function is not called, directly or indirectly, the compiler removes the

function.

To see which program-level optimizations the compiler is applying, use the

−on2 option to generate an information file. See section 3.2.2, Creating an Op- timization Information File (−onn Option)

, on page 3-5 for more information.

3.3.1 Controlling Program-Level Optimization (−opn Option)

You can control program-level optimization, which you invoke with −pm −o3, by using the −op option. Specifically, the −op option indicates if functions in other modules can call a module’s external functions or modify a module’s external variables. The number following −op indicates the level you set for the module that you are allowing to be called or modified. The −o3 option com- bines this information with its own file-level analysis to decide whether to treat this module’s external function and variable declarations as if they had been declared static. Use Table 3−4 to select the appropriate level to append to the

−op option.

3-6

Page 76

Performing Program-Level Optimization (−pm and −o3 Options)

Table 3−4. Selecting a Level for the −op Option

If your module … Use this option

Has functions that are called from other modules and global variables that are modified in other modules

Does not have functions that are called by other modules but has global variables that are modified in other modules

Does not have functions that are called by other modules or global variables that are modified in other modules

Has functions that are called from other modules but does not have global variables that are modified in other modules

In certain circumstances, the compiler reverts to a different −op level from the one you specified, or it might disable program-level optimization altogether. Table 3−5 lists the combinations of −op levels and conditions that cause the compiler to revert to other −op levels.

Table 3−5. Special Considerations When Using the −op Option

If your −op is... Under these conditions...

Not specified The −o3 optimization level was specified Defaults to −op2

Not specified The compiler sees calls to outside functions

under the −o3 optimization level

−op0

−op1

−op2

−op3

Then the −op level...

Reverts to −op0

Not specified Main is not defined Reverts to −op0

−op1 or −op2 No function has main defined as an entry point

−op1 or −op2 No interrupt function is defined Reverts to −op0

−op1 or −op2 Functions are identified by the

FUNC_EXT_CALLED pragma

−op3

Any condition Remains −op3

Reverts to −op0

In some situations when you use −pm and −o3, you must use an −op option or the FUNC_EXT_CALLED pragma. See section 3.3.2, Optimization Consid- erations When Mixing C and Assembly, on page 3-8 for information about these situations.

3-7Optimizing Your Code

Page 77

Performing Program-Level Optimization (−pm and −o3 Options)

3.3.2 Optimization Considerations When Mixing C and Assembly

If you have any assembly functions in your program, you need to exercise caution when using the −pm option. The compiler recognizes only the C source code and not any assembly code that might be present. Because the compiler does not recognize the assembly code calls and variable modifications to C functions, the −pm option optimizes out those C functions. To keep these functions, place the FUNC_EXT_CALLED pragma (see section 5.4.3, The FUNC_EXT_CALLED Pragma, on page 5-8) before any declaration or reference to a function that you want to keep.

Another approach you can take when you use assembly functions in your program is to use the −opn option with the −pm and −o3 options (see section 3.3.1, Controlling Program-Level Optimization, on page 3-6).

In general, you achieve the best results through judicious use of the FUNC_EXT_CALLED pragma in combination with −pm −o3 and −op1 or

−op2.

If any of the following situations apply to your application, use the suggested solution:

Situation Your application consists of C source code that calls assem-

bly functions. Those assembly functions do not call any C functions or modify any C variables.

Solution Compile with −pm −o3 −op2 to tell the compiler that outside

functions do not call C functions or modify C variables.

If you compile with the −pm −o3 options only, the compiler reverts from the default optimization level (−op2) to −op0. The compiler uses −op0, because it presumes that the calls to the assembly language functions that have a definition in C may call other C functions or modify C variables.

Situation Your application consists of C source code that calls assem-

bly functions. The assembly language functions do not call C functions, but they modify C variables.

Solution Try both of these solutions and choose the one that works

best with your code:

J Compile with −pm −o3 −op1.

J Add the volatile keyword to those variables that may be

modified by the assembly functions and compile with

−pm −o3 −op2.

See section 3.3.1 on page 3-6 for information about the −opn option.

3-8

Page 78

Performing Program-Level Optimization (−pm and −o3 Options)

Situation Your application consists of C source code and assembly

source code. The assembly functions are interrupt service routines that call C functions; the C functions that the assembly functions call are never called from C. These C functions act like main: they function as entry points into C.

Solution Add the volatile keyword to the C variables that may be modi-

fied by the interrupts. Then, you can optimize your code in one of these ways:

J You achieve the best optimization by applying the

FUNC_EXT_CALLED pragma to all of the entry-point functions called from the assembly language interrupts, and then compiling with −pm −o3 −op2. Be sure that you use the pragma with all of the entry-point functions. If you do not, the compiler removes the entry-point functions that are not preceded by the FUNC_EXT_CALL pragma.

J Compile with −pm −o3 −op3. Because you do not use the

FUNC_EXT_CALL pragma, you must use the −op3 option, which is less aggressive than the −op2 option, and your optimization may not be as effective.

Keep in mind that if you use −pm −o3 without additional op- tions, the compiler removes the C functions that the assembly functions call. Use the FUNC_EXT_CALLED pragma to keep these functions.

Use the −on2 option to generate an information file to see which program-level optimizations the compiler is applying. See section 3.2.2, Creating an Optimi- zaton Information File, on page 3-5 for more information.

3.3.3 Naming the Program Compilation Output File (−px Option)

When you specify whole program compilation with the −pm option, you can use the −px filename option to specify the name of the output file. If you specify no assembly (−n shell option), the default file extension for the output file is .asm. If you allow assembly (default shell behavior), the default file extension for the output file is .obj. If you specify linking, you must name the output file with the −o option after the −z option, or the name of the output file is the default a.out.

3-9Optimizing Your Code

Page 79

Special Considerations When Using the Optimizer

3.4 Special Considerations When Using the Optimizer

The optimizer is designed to improve your ANSI-conforming C programs while maintaining their correctness. However, when you write code for the optimizer, you should note the following special considerations to ensure that your program performs as you intend.

3.4.1 Use Caution With asm Statements in Optimized Code

You must be extremely careful when using asm (inline assembly) statements in optimized code. The optimizer rearranges code segments, uses registers freely, and can completely remove variables or expressions. Although the compiler never optimizes out an asm statement (except when it is unreachable), the surrounding environment where the assembly code is inserted can differ significantly from the original C source code. It is usually safe to use asm statements to manipulate hardware controls such as interrupt masks, but asm statements that attempt to interface with the C environment or access C variables can have unexpected results. After compilation, check the assembly output to make sure your asm statements are correct and maintain the integrity of the program.

3.4.2 Use Caution With the Volatile Keyword

The optimizer analyzes data flow to avoid memory accesses whenever possible. If you have code that depends on memory accesses exactly as written in the C code, you must use the volatile keyword to identify these accesses. A variable qualified with a volatile keyword is allocated to an uninitialized section. The compiler will not optimize out any references to volatile variables.

In the following example, the loop waits for a location to be read as 0xFF:

unsigned int *ctrl; while (*ctrl !=0xFF);

In this example, *ctrl is a loop-invariant expression, so the loop is optimized down to a single memory read. To correct this, declare

volatile unsigned int *ctrl

ctrl as:

3-10

Page 80

Use Caution With asm Statements in Optimized Code

3.4.3 Use Caution When Accessing Aliased Variables

Aliasing occurs when you can access a single object in more than one way, such as when two pointers point to the same object or when a pointer points to a named object. Aliasing can disrupt optimization, because any indirect reference could potentially refer to any other object. The optimizer analyzes the code to determine where aliasing can and cannot occur, then optimizes as much as possible while still preserving the correctness of the program. The optimizer behaves conservatively. If there is a chance that two pointers are pointing to the same object, the optimizer assumes that the pointers point to the same object.

The compiler assumes that if the address of a local variable is passed to a function, the function might change the local variable by writing through the pointer. This makes its address unavailable for use elsewhere after returning. For example, the called function cannot assign the local variable’s address to a global variable or return the local variable’s address.

3.4.4 Assume Functions Are Not Interrupts

The −oe option assumes that none of the functions in the module are inter- rupts, can be called by interrupts, or can be otherwise executed in an asynchronous manner. This enables the optimizer to do certain variable allocation optimizations. The −oe option automatically invokes the optimizer at level 2.

The −oe option also presumes that none of the modules are called recursively (directly or indirectly). Be careful not to combine the use of −oe with modules containing recursive functions.

3-11Optimizing Your Code

Page 81

Automatic Inline Expansion (−oi Option)

3.5 Automatic Inline Expansion (−oi Option)

The optimizer automatically inlines small functions when it is invoked with the

−o3 option. A command-line option, −oisize, specifies the size of the functions inlined. When you use −oi, specify the size limit for the largest function to be inlined. You can use the −oisize option in the following ways:

- If you set the size parameter to 0 (−oi0), all size-controlled inlining is dis-

abled.

- If you set the size parameter to a nonzero integer, the compiler inlines

functions based on size. The optimizer multiplies the number of times the function is inlined (plus 1 if the function is externally visible and its declaration cannot be safely removed) by the size of the function. The optimizer inlines the function only if the result is less than the size parameter. The compiler measures the size of a function in arbitrary units; however, the optimizer information file (created with the −on1 or −on2 option) reports the size of each function in the same units that the −oi option uses.

The −oisize option controls only the inlining of functions that are not explicitly declared as inline. If you do not use the −oisize option, the optimizer inlines very small functions. The −x option controls the inlining of functions declared as inline (see section 2.6.3.1 on page 2-31).

3-12

Page 82

Using the Interlist Utility With the Optimizer / Debugging Optimized Code

3.6 Using the Interlist Utility With the Optimizer

You control the output of the interlist utility when running the optimizer (the −on option) with the −os and −ss options.

- The −os option interlists optimizer comments with assembly source state-

ments.

- The −ss and −os options together interlist the optimizer comments and the

original C source with the assembly code.

When you use the −os option with the optimizer, the interlist utility does not run as a separate pass. Instead, the optimizer inserts comments into the code, indicating how the optimizer has rearranged and optimized the code. These comments appear in the assembly language file as comments starting with ;**. The C source code is not interlisted, unless you use the −ss option also.

The interlist utility can affect optimized code because it might prevent some optimization from crossing C statement boundaries. Optimization makes normal source interlisting impractical, because the optimizer extensively rearranges your program. Therefore, when you use the −os option, the optimizer writes reconstructed C statements.

Using the Interlist Utility With the Optimizer

3.7 Debugging Optimized Code

Ideally, you should debug a program in an unoptimized form and reverify its correctness after it has been optimized. You can use the debugger with optimized code, but the optimizer’s extensive rearrangement of code and the many-to-one allocation of variables to registers often makes it difficult to correlate source code with object code.

Note: Symbolic Debugging and Optimized Code

If you use the − g option to generate symbolic debugging information, many code generator optimizations are disabled because they disrupt the debugger. If you want to use symbolic debugging and still generate fully optimized code, use the −mn option. − mn re-enables the optimizations disabled by − g.

3-13Optimizing Your Code

Page 83

What Kind of Optimization Is Being Performed?

3.8 What Kind of Optimization Is Being Performed?

The TMS320C2x/C2xx/C5x C compiler uses a variety of optimization techniques to improve the execution speed of your C programs and to reduce their size. Optimization occurs at various levels throughout the compiler.

Most of the optimizations described here are performed by the separate optimizer pass that you enable and control with the −o compiler options (see section 3.1, Using the Compiler Optimizer, on page 3-2). However, the code gen- erator performs some optimizations, which you cannot selectively enable or disable.

Following are the optimizations performed by the compiler. These optimizations improve any C code:

Optimizations Page

Cost-based register allocation 3-15

Autoincrement addressing 3-15

Repeat Blocks 3-15

Delays, branches, calls, and returns 3-16

Algebraic reordering, symbolic simplification, constant folding 3-18

Alias disambiguation 3-18

Data flow optimizations

- Copy propagation

- Common subexpression elimination

- Redundant assignment elimination

Branch optimizations and control-flow simplification 3-20

Loop induction variable optimizations and strength reduction 3-21

Loop rotation 3-21

Loop-invariant code motion 3-21

Inline expansion of run-time-support library functions 3-21

3-18

3-14

Page 84

3.8.1 Cost-based Register Allocation

The optimizer, when enabled, allocates registers to user variables and compiler temporary values according to their type, use, and frequency. Variables used within loops are weighted to have priority over others, and those variables whose uses do not overlap may be allocated to the same register.

3.8.2 Autoincrement Addressing

For pointer expressions of the form *p++, the compiler uses efficient TMS320C2x/C2xx/C5x autoincrement addressing modes. In many cases, where code steps through an array in a loop, such as for (i = 0; i < n; ++i) a[i]..., the loop optimizations convert the array references to indirect references through autoincremented register variable pointers. See Example 3−1.

3.8.3 Repeat Blocks

The TMS320C2x/C2xx/C5x supports zero-overhead loops with the RPTB (repeat block) instruction. With the optimizer, the compiler can detect loops controlled by counters and generate them using the efficient repeat forms. The iteration count can be either a constant or an expression. For the TMS320C2x, which does not have a repeat block instruction, the compiler allocates an AR as the loop counter and implements the loop with a BANZ instruction. See Example 3−1 and Example 3−5.

What Kind of Optimization Is Being Performed?

3-15Optimizing Your Code

Page 85

What Kind of Optimization Is Being Performed?

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

Reduction, Induction Variable Elimination, Register Variables, and Loop Test Replacement

int a[10], b[10]; scale(int k) { int i; for (i = 0; i < 10; ++i) a[i] = b[i] * k;

. . .

TMS320C2x/C2xx/C5x C Compiler Output:

_scale:

. . . LRLK AR6,_a ; AR6 = &a[0] LRLK AR5,_b ; AR5 = &b[0] LACK 9 SAMM BRCR ; BRCR = 9 LARK AR2,−3+LF1 ; AR2 = &k MAR *0+,AR5 RPTB L4−1 ; repeat block 10 times LT *+,AR2 ; t = *AR5++ MPY * ,AR6 ; p = t * *AR2 SPL *+,AR5 ; *AR6++ = p

L4:

. . .

Induction variable elimination and loop test replacement allow the compiler to recognize the loop as a simple counting loop and then generate a repeat block. Strength reduction turns the array references into efficient pointer autoincrements.

3.8.4 Delays, Banches, Calls, and Returns

The TMS320C5x provides a number of of delayed branch, call, and return instructions. Three of these are used by the compiler: branch unconditional (BD), call to a named function (CALLD), and simple return (RETD). These instructions execute in two fewer cycles than their nondelayed counterparts. They execute two instructions words after they enter the instruction stream. Sometimes it is necessary to insert a NOP after a delayed instruction to ensure proper operation of the sequence. This is one word of code longer than a nondelayed sequence, but it is still one cycle faster. Note that the compiler emits a comment in the instruction sequence where the delayed instruction executes. See Example 3−2.

3-16

Page 86

What Kind of Optimization Is Being Performed?

Example 3−2. Delayed Branch, Call, and Return Instructions

main() { int i0, i1;

while (input(&i0) && input(&i1)) process(i0, i1); }

TMS320C2x/C2xx/C5x C Compiler Output:

_main:

SAR AR0,*+ ; function prolog POPD *+ ; save AR0 and return address SAR AR1,* ; begin to set up local frame BD L2 ; begin branch to loop control LARK AR0,3 ; finish setting up local frame LAR AR0,*0+

*** B L2 OCCURS ; branch to loop control L1: ; loop body

LARK AR2,2 ; AR2 = &i1 MAR *0+ LAC *−,AR1 ; ACC = *AR2, AR2 = &i0 SACL *+,AR2 ; stack ACC CALLD _process ; begin call LAC * ,AR1 ; ACC = *AR2 SACL *+ ; stack ACC

*** CALL _process OCCURS ; call occurs

SBRK 2 ; pop stack

L2: ; loop control

MAR * ,AR5 ; AR5 = &i0 LARK AR5,1 CALLD _input ; begin call MAR *0+,AR1 SAR AR5,*+ ; stack AR5

*** CALL _input OCCURS ; call occurs

MAR *− ; clear stack BZ EPI0_1 ; quit if _input returns 0 MAR * ,AR4 ; AR4 = &i1 LARK AR4,2 CALLD _input ; begin call MAR *0+,AR1 SAR AR4,*+ ; stack AR4

*** CALL _input OCCURS ; call occurs

MAR *−,AR2 ; clear stack BNZ L1 ; continue if _input returns !0

EPI0_1:

MAR * ,AR1 ; function epilog SBRK 4 ; clear local frame PSHD *− ; push return address on hardware stack RETD ; begin return LAR AR0,* ; restore AR0 NOP ; necessary, no PSHD in delay slot

*** RET OCCURS ; return occurs

. . .

3-17Optimizing Your Code

Page 87

What Kind of Optimization Is Being Performed?

3.8.5 Algebraic Reordering / Symbolic Simplification / Constant Folding

For optimal evaluation, the compiler simplifies expressions into equivalent forms requiring fewer instructions or registers. For example, the expression (a + b) − (c + d) takes six instructions to evaluate; it can be optimized to ((a + b)

− c) − d, which takes only four instructions. Operations between constants are folded into single constants. For example, a = (b + 4) − (c + 1) becomes a = b

− c + 3. See Example 3−3.

3.8.6 Alias Disambiguation

Programs written in the C language generally use many pointer variables. Frequently, compilers are unable to determine whether or not two or more I (lowercase L) values (symbols, pointer references, or structure references) refer to the same memory location. This aliasing of memory locations often prevents the compiler from retaining values in registers because it cannot be sure that the register and memory continue to hold the same values over time. Alias disambiguation is a technique that determines when two pointer expressions cannot point to the same location, allowing the compiler to freely optimize such expressions.

3.8.7 Data-Flow Optimizations

Collectively, the following three data-flow optimizations replace expressions with less costly ones, detect and remove unnecessary assignments, and avoid operations that produce values already computed. The optimizer performs these data-flow optimizations both locally (within basic blocks) and globally (across entire functions). See Example 3−3 and Example 3−4.

- Copy propagation

Following an assignment to a variable, the compiler replaces references to the variable with its value. The value could be another variable, a constant, or a common subexpression. This may result in increased opportunities for constant folding, common subexpression elimination, or even total elimination of the variable. See Example 3−3 and Example 3−4.

- Common subexpression elimination

When the same value is produced by two or more expressions, the compiler computes the value once, saves it, and reuses it. See Example 3−3.

- Redundant assignment elimination

Often, copy propagation and common subexpression elimination optimizations result in unnecessary assignments to variables (variables with no subsequent reference before another assignment or before the end of the function). The optimizer removes these dead assignments. See Example 3−3.

3-18

Page 88

Example 3−3. Data-Flow Optimizations

simp(int j) {

int a = 3; int b = (j * a) + (j * 2); int c = (j << a); int d = (j >> 3) + (j << b);

call(a,b,c,d); ...

}

TMS320C2x/C2xx/C5x C Compiler Output:

_simp:

. . .

***************************************************** * b = j * 5; *****************************************************

LARK AR2,−3+LF1 ; AR2 = &j MAR *0+ LT * ; t = *AR2 MPYK 5 ; p = t * 5 ADRK 4−LF1 ; AR2 = &b

SPL * ; *AR2 = p ***************************************************** * call(3, b, j << 3, (j >> 3) + (j << b)); *****************************************************

LT * ; t = *AR2 (b)

SBRK 4−LF1 ; AR2 = &j

LACT * ,AR1 ; ACC = j << b

SACL * ,AR2 ; save off ACC on TOS (top of stack)

SSXM ; need sign extension for right shift

LAC * ,12,AR1 ; high ACC = j >> 3

ADD * ,15 ; add TOS to high ACC

SACH *+,1,AR2 ; stack high ACC

LAC * ,3,AR1 ; ACC = j << 3

SACL *+,AR2 ; stack ACC

ADRK 4−LF1 ; AR2 = &b

LAC * ,AR1 ; ACC = b

SACL *+ ; stack ACC

CALLD _call ; call begins

LACK 3 ; ACC = 3

SACL *+ ; stack ACC *** CALL _call OCCURS ; call occurs

. . .

The constant 3, assigned to a, is copy propagated to all uses of a; a becomes a dead variable and is eliminated. The sum of multiplying j by 3 (a) and 2 is simplified into b = j * 5, which is recognized as a common subexpression. The assignments to c and d are dead and are replaced with their expressions. These optimizations are performed across jumps.

What Kind of Optimization Is Being Performed?

3-19Optimizing Your Code

Page 89

What Kind of Optimization Is Being Performed?

3.8.8 Branch Optimizations and Control-Flow Simplification

The compiler analyzes the branching behavior of a program and rearranges the linear sequences of operations (basic blocks) to remove branches or redundant conditions. Unreachable code is deleted, branches to branches are bypassed, and conditional branches over unconditional branches are simplified to a single conditional branch. When the value of a condition can be determined at compile time (through copy propagation or other data flow analysis), a conditional branch can be deleted. Switch case lists are analyzed in the same way as conditional branches and are sometimes eliminated entirely. Some simple control-flow constructs can be reduced to conditional instructions, totally eliminating the need for branches. See Example 3−4.

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

fsm() {

enum { ALPHA, BETA, GAMMA, OMEGA } state = ALPHA; int *input;

while (state != OMEGA)

switch (state) {

case ALPHA: state = ( *input++ == 0 ) ? BETA: GAMMA; break; case BETA : state = ( *input++ == 0 ) ? GAMMA: ALPHA; break; case GAMMA: state = ( *input++ == 0 ) ? GAMMA: OMEGA; break;

}

TMS320C2x/C2xx/C5x C Compiler Output:

_fsm:

. . . * * AR5 assigned to variable ’input’ *

LAC *+ ; initial state == ALPHA

BNZ L5 ; if (input != 0) go to state GAMMA L2:

LAC *+ ; state == BETA

BZ L4 ; if (input == 0) go to state GAMMA

LAC *+ ; state == ALPHA

BZ L2 ; if (input == 0) go to state BETA

B L5 ; else go to state GAMMA L4:

LAC *+ ; state == GAMMA

BNZ EPI0_1 ; if (input != 0) go to state OMEGA L5:

LARP AR5 L6:

LAC *+ ; state = GAMMA

BZ L6 ; if (input == 0) go to state GAMMA EPI0_1: ; state == OMEGA

. . .

The switch statement and the state variable from this simple finite state machine example are optimized completely away, leaving a streamlined series of conditional branches.

3-20

Page 90

What Kind of Optimization Is Being Performed?

3.8.9 Loop Induction Variable Optimizations and Strength Reduction

Loop induction variables are variables whose value within a loop is directly related to the number of executions of the loop. Array indices and control variables for loops are very often induction variables. Strength reduction is the process of replacing costly expressions involving induction variables with more efficient expressions. For example, code that indexes into a sequence of array elements is replaced with code that increments a pointer through the array. Loops controlled by incrementing a counter are written as TMS320C2x/C2xx/C5x repeat blocks or by using efficient decrement-andbranch instructions. Induction variable analysis and strength reduction together often remove all references to your loop control variable, allowing it to be eliminated entirely. See Example 3−1 and Example 3−5.

3.8.10 Loop Rotation

The compiler evaluates loop conditionals at the bottom of loops, saving a costly extra branch out of the loop. In many cases, the initial entry conditional check and the branch are optimized out.

3.8.11 Loop Invariant Code Motion

This optimization identifies expressions within loops that always compute the same value. The computation is moved in front of the loop, and each occurrence of the expression in the loop is replaced by a reference to the precomputed value. See Example 3−5.

3.8.12 Inline Expansion of Run−Time-Support Library Functions

The compiler replaces calls to small run-time-support functions with inline code, saving the overhead associated with a function call, as well as providing increased opportunities to apply other optimizations. See Example 3−5.

3-21Optimizing Your Code

Page 91

What Kind of Optimization Is Being Performed?

Example 3−5. Inline Function Expansion

#include <string.h> struct s { int a,b,c[10]; }; struct t { int x,y,z[10]; };

proc_str(struct s *ps, struct t *pt) {

. . .

memcpy(ps,pt,sizeof(*ps));

. . . } _proc_str:

. . .

TMS320C2x/C2xx/C5x C Compiler Output:

* * AR5 assigned to variable ’memcpy_1_rfrom’ * AR6 assigned to variable ’memcpy_1_rto’ * BRCR assigned to temp var ’L$1’ *

. . .

LARK AR2,−3+LF1 ; AR2 = &ps MAR *0+ LAR AR6,*− ; AR6 = ps, AR2 = &pt LAR AR5,* ,AR5 ; AR5 = pt LACK 11 SAMM BRCR ; repeat 12 times RPTB L4−1 LAC *+,AR6 ; *ps++ = *pt++ SACL *+,AR5 NOP ; must have 3 words in repeat block

L4:

. . .

The compiler finds the intermediate file code for the C function memcpy( ) in the inline library and copies it in place of the call. Note the creation of variables memcpy_1_from and memcpy_1_to, corresponding to the parameters of memcpy. (Often, copy propagation can eliminate such assignments to parameters of inlined functions when the arguments are not referenced after the call.)

3-22

Page 92

Chapter 4

LinkingCCode

The C compiler and assembly language tools provide two methods for linking your programs:

- You can compile individual modules and link them together. This method

is especially useful when you have multiple source files.

- You can compile and link in one step by using dspcl. This method is useful

when you have a single source module.

This chapter describes how to invoke the linker with each method. It also discusses special requirements of linking C code, including the run-time-support libraries, specifying the type of initialization, and allocating the program into memory. For a complete description of the linker, see the TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide.

Topic Page

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

Page 93

Invoking the Linker as an Individual Program

4.1 Invoking the Linker as an Individual Program

This section shows how to invoke the linker in a separate step after you have compiled and assembled your programs. This is the general syntax for linking C programs in a separate step:

dsplnk {−c|−cr} filenames [-options] [−o name.out] −l libraryname [lnk.cmd]

lnk6x is the command that invokes the linker.

−c | −cr are options that tell the linker to use special conventions defined by the C environment. When you use dsplnk, you must use −c or −cr. The −c option uses automatic variable initialization at runtime; the −cr option uses variable initialization at load time.

filenames are names of object files, linker command files, or archive

libraries. The default extension for all input files is .obj; any other extension must be explicitly specified. The linker can determine whether the input file is an object or ASCII file that contains linker commands. The default output filename is a.out, unless you use the −o option to name the output file.

options affect how the linker handles your object files. Options can

appear anywhere on the command line or in a linker command file. (Options are discussed in section 4.4)

−o name.out

−l libraryname (lowercase L) Identifies the appropriate archive library

lnk.cmd

The −o option names the output file.

containing C run-time-support and floating-point math functions. (The −l option tells the linker that a file is an archive library.) If you are linking C code, you must use a runtime-support library. You can use the libraries included with the compiler, or you can create your own run-timesupport library. If you have specified a run-time-support library in a linker command file, you do not need this parameter.

contains options, filenames, directives, or commands for the linker.

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

Library Name Library Source Contents

rts25.lib TMS320C2x runtime support

rts2xx.lib TMS320C2xx runtime support

rts50.lib TMS320C5x runtime support

4-2

Page 94

Invoking the Linker as an Individual Program

When you specify a library as linker input, the linker includes and links only those library members that resolve undefined references. For example, you can link a C program consisting of modules prog1, prog2, and prog3 (the output file is named prog.out), enter:

dsplnk −c prog1 prog2 prog3 −o prog.out −l rts25.lib

The linker uses a default allocation algorithm to allocate your program into memory. You can use the MEMORY and SECTIONS directives in the linker command file to customize the allocation process. For more information, see the TMS320C2x/C2x/C2xx/C5x Assembly Language Tools User’s Guide.

4-3Linking C Code

Page 95

Invoking the Linker With the Compiler Shell (−z Option)

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

The options and parameters discussed in this section apply to both methods of linking; however, when you link while compiling, the linker options must follow the −z option (see section 2.2, Invoking the C Compiler Shell, on page 2-4).

By default, the compiler does not run the linker. However, if you use the −z option, a program is compiled, assembled, and linked in one step. When using

−z to enable linking, remember that:

- The −z option divides the command line into compiler options (the options

before −z) and linker options (the options following −z).

- The −z option must follow all source files and other compiler options on the

command line or be specified with the C_OPTION environment variable.

All arguments that follow −z on the command line are passed on to the linker. These arguments can be linker command files, additional object files, linker options, or libraries. For example, to compile and link all the .c files in a directory, enter:

dspcl −sq *.c −z c.cmd −o prog.out −l rts25.lib

First, all of the files in the current directory that have a .c extension are compiled using the −s (interlist C and assembly code) and −q (run in quiet mode) options. Second, the linker links the resulting object files by using the c.cmd command file. The −o option names the output file, and the −l option names the run-time-support library.

The order in which the linker processes arguments is important. The compiler passes arguments to the linker in the following order:

1) Object filenames from the command line

2) Arguments following the −z option on the command line

3) Arguments following the −z option from the C_OPTION environment variable

4-4

Page 96

4.3 Disabling the Linker (−c Shell Option)

You can override the −z option by using the −c shell option. The −c option is especially helpful if you specify the −z option in the C_OPTION environment variable and want to selectively disable linking with the −c option on the command line.

The −c linker option has a different function than, and is independent of, the

−c shell option. By default, the compiler uses the −c linker option when you use the −z option. This tells the linker to use C linking conventions (autoinitialization of variables at runtime). If you want to initialize variables at load time, use the −cr linker option following the −z option.

Disabling the Linker (−c Shell Option)

4-5Linking C Code

Page 97

Linker Options

4.4 Linker Options

All command-line input following the −z shell option is passed to the linker as parameters and options. The following are options that control the linker along with detailed descriptions of their effects.

−a Produces an absolute, executable module. This is the default; if neither −a nor −r is specified, the linker acts as if −a is specified.

−ar Produces a relocatable, executable object module

−b Disables merging of symbolic debugging information

−c Autoinitializes variables at runtime. See section 6.8.4 on

page 6-34, for more information.

−cr Initializes variables at load time. See section 6.8.5 on page 6-35, for more information.

−e global_symbol Defines a global_symbol that specifies the primary entry point for the output module

−f fill_value Sets the default fill value for holes within output sections; fill_value is a 16-bit constant

−g global_symbol Defines global_symbol as global even if the global sym- bol has been made static with the −h linker option

−h Makes all global symbols static

−heap size Sets heap size (for dynamic memory allocation) to size

words and defines a global symbol that specifies the heap size. Default is 1K words.

−i directory Alters the library-search algorithm to look in directory be- fore looking in the default location. This option must appear before the −l linker option. The directory must follow operating system conventions.

−l libraryname (lower case L) Names an archive library file or linker com- mand filename as linker input. The libraryname is an archive library name and must follow operating system conventions.

−m filename Produces a map or listing of the input and output sec- tions, including holes, and places the listing in filename. The filename must follow operating system conventions.

−n Ignores all fill specifications in memory directives. Use this option in the development stage of a project to avoid generating large .out files, which can result from using memory directive fill specifications.

4-6

Page 98

Linker Options

−o filename Names the executable output module. The filename must follow operating system conventions. If the −o op- tion is not used, the default filename is a.out.

−q Requests a quiet run (suppresses the banner and prog- ress information)

−r Retains relocation entries in the output module

−s Strips symbol table information and line number entries

from the output module

−stack size Sets the C system stack size to size words and defines a global symbol that specifies the stack size. Default is 1K words.

−u symbol Places the unresolved external symbol symbol into the output module’s symbol table

−v0 Generates version 0 COFF format

−v1 Generates version 1 COFF format

−v2 Generates version 2 COFF format

−w Displays a message when an undefined output section

is created

−x Forces rereading of libraries. Resolves back references

For more information on linker options, see the Linker Description chapter in the TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide.

4-7Linking C Code

Page 99

Controlling the Linking Process

4.5 Controlling the Linking Process

Regardless of the method you choose for invoking the linker, special requirements apply when linking C programs. You must:

- Include the compiler’s run-time-support library

- Specify the type of initialization

- Determine how you want to allocate your program into memory

This section discusses how these factors are controlled and provides an example of the standard default linker command file.

For more information about how to operate the linker, see the TMS320C1x/

C2x/C2xx/C5x Assembly Language Tools User’s Guide.

4.5.1 Linking With Run-Time-Support Libraries

You must link all C programs with a run-time-support library. The library contains standard C functions as well as functions used by the compiler to manage the C environment. You must use the −l linker option to specify which TMS320C2x/C2xx/C5x run-time-support library to use. The −l option also tells the linker to look at the −i options and then the C_DIR environment variable to find an archive path or object file. To use the −l linker option, type on the command line:

dsplnk {−c | −cr} filenames −l libraryname

Generally, you should specify the library as the last name on the command line because the linker searches libraries for unresolved references in the order that files are specified on the command line. If any object files follow a library, references from those object files to that library are not resolved. You can use the −x linker option to force the linker to reread all libraries until references are resolved. Whenever you specify a library as linker input, the linker includes and links only those library members that resolve undefined references.

Three versions of the standard run-time-support library are included with the compiler: rts25.lib for TMS320C2x programs, rts2xx.lib for TMS320C2xx programs, and rts50.lib for TMS320C5x programs.

You must link all C programs with an object module called boot.obj. When a C program begins running, it must execute boot.obj first. The boot.obj file contains code and data to initialize the run-time environment; the linker automatically extracts boot.obj and links it when you use −c or −cr and include rts25.lib, rts2xx.lib or rts50.lib in the link.

4-8

Page 100

Controlling the Linking Process

Note: The _c_int0 Symbol

One important function contained in the run-time-support library is _c_int0. The symbol _c_int0 is the starting point in boot.obj; if you use the −c or −cr linker option, _c_int0 is automatically defined as the entry point for the program. If your program begins running from reset, you should set up the reset vector to branch to _c_int0 so that the processor executes boot.obj first.

The boot.obj module contains code and data for initializing the run-time environment. The module performs the following tasks:

1) Sets up the stack

2) Processes the run-time initialization table and autoinitializes global variables (when using the −c option)

3) Calls main

4) Calls exit when main returns

Chapter 7 describes additional run-time-support functions that are included in the library. These functions include ANSI C standard run-time support.

4.5.2 Specifying the Type of Initialization

The C compiler produces data tables for initializing global variables. Section

6.8.3, Initialization Tables, on page 6-33 discusses the format of these tables.

These tables are in a named section called .cinit. The initialization tables are used in one of the following ways:

- Global variables are initialized at run time. Use the −c linker option (see

section 6.8.4, Autoinitialization of Variables at Run Time, on page 6-34).

- Global variables are initialized at load time. Use the −cr linker option (see

section 6.8.5, Initialization of Variables at Load Time, on page 6-35).

4-9Linking C Code