TMS320C2x/C2xx/C5x Optimizing C Compiler User’s Guide Literature Number: SPRU024E August 1999 Printed on Recycled Paper IMPORTANT NOTICE Texas Instruments and its subsidiaries (TI) reserve the right to make changes to their products or to discontinue any product or service without notice, and advise customers to obtain the latest version of relevant information to verify, before placing orders, that information being relied on is current and complete. All products are sold subject to the terms and conditions of sale supplied at the time of order acknowledgement, including those pertaining to warranty, patent infringement, and limitation of liability. TI warrants performance of its semiconductor products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are utilized to the extent TI deems necessary to support this warranty. Specific testing of all parameters of each device is not necessarily performed, except those mandated by government requirements. CERTAIN APPLICATIONS USING SEMICONDUCTOR PRODUCTS MAY INVOLVE POTENTIAL RISKS OF DEATH, PERSONAL INJURY, OR SEVERE PROPERTY OR ENVIRONMENTAL DAMAGE (“CRITICAL APPLICATIONS”). TI SEMICONDUCTOR PRODUCTS ARE NOT DESIGNED, AUTHORIZED, OR WARRANTED TO BE SUITABLE FOR USE IN LIFE-SUPPORT DEVICES OR SYSTEMS OR OTHER CRITICAL APPLICATIONS. INCLUSION OF TI PRODUCTS IN SUCH APPLICATIONS IS UNDERSTOOD TO BE FULLY AT THE CUSTOMER’S RISK. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards must be provided by the customer to minimize inherent or procedural hazards. TI assumes no liability for applications assistance or customer product design. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right of TI covering or relating to any combination, machine, or process in which such semiconductor products or services might be or are used. TI’s publication of information regarding any third party’s products or services does not constitute TI’s approval, warranty or endorsement thereof. Copyright 1999, Texas Instruments Incorporated Preface Read This First About This Manual The TMS320C2x/C2xx/C5x Optimizing C Compiler User’s Guide tells you how to use these compiler tools: - Compiler - Source interlist utility - Optimizer - Parser - Library-build utility The TMS320C2x/C2xx/C5x C compiler accepts American National Standards Institute (ANSI) standard C source code and produces assembly language source code for the TMS320C2x/C2xx/C5x devices. This user’s guide dis- cusses the characteristics of the C compiler. It assumes that you already know how to write C programs. The C Programming Language (second edition), by Brian W. Kernighan and Dennis M. Ritchie (hereafter referred to as K & R), describes C based on the ANSI C standard. You can use the Kernighan and Ritchie book as a supplement to this manual. Before you use the information about the C compiler in this User’s Guide, you should read the TMS320C1x/C2x/ C2xx/C5x Code Generation Tools Getting Started to install the C compiler tools. Read This First iii 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 spec- ification. It contains technical information on the TMS320C2x/ C2xx/C5x architecture and includes information needed for interfacing assembly language to C programs. It describes libraries and header files in addition to the macros, functions, and types they declare. Finally, it describes the library-build utility. - Reference material, consisting of Appendix B, provides a glossary. Notational Conventions This document uses the following conventions. - Program listings, program examples, and interactive displays are shown in a special typeface similar to a typewriter’s. Examples use a bold version of the special typeface for emphasis; interactive displays use a bold version of the special typeface to distinguish commands that you enter from items that the system displays (such as prompts, command output, error messages, etc.). Here is a sample of C code: # ifdef NDEBUG # define assert - In syntax descriptions, the instruction, command, or directive is in a bold face font and parameters are in italics. Portions of a syntax that are in bold face must be entered as shown; portions of a syntax that are in italics de- scribe the type of information that should be entered. Here is an example of a directive syntax: #include “filename” The #include preprocessor directive has one required parameter, file- name. The filename must be enclosed in double quotes or angle brackets. iv Notational Conventions / Related Documentation From Texas Instruments - Square brackets ( [ and ] ) identify an optional parameter. If you use an op- tional parameter, you specify the information within the brackets; you do not enter the brackets themselves. Here is an example of a command that has an optional parameter: clist asmfile [outfile] [−options] 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. Related Documentation From Texas Instruments The following books describe the TMS320C2x/C2xx/C5x and related support tools. To obtain a copy of any of these TI documents, call the Texas Instru- ments Literature Response Center at (800) 477−8924. When ordering, identify the book by its title and literature number (located on the bottom-right corner of the back cover). TMS320C2x User’s Guide (literature number SPRU014) discusses the hard- ware aspects of the ’C2x fixed-point digital signal processors. It de- scribes pin assignments, architecture, instruction set, and software and hardware applications. It also includes electrical specifications and pack- age mechanical data for all ’C2x devices. The book features a section with a ’C1x-to-’C2x DSP system migration. TMS320C2xx User’s Guide (literature number SPRU127) discusses the hardware aspects of the ’C2xx fixed-point digital signal processors. It de- scribes pin assignments, architecture, instruction set, and software and hardware applications. It also includes electrical specifications and pack- age mechanical data for all ’C2xx devices. The book features a section comparing instructions from ’C2x to ’C2xx. TMS320C5x User’s Guide (literature number SPRU056) describes the TMS320C5x 16-bit, fixed-point, general-purpose digital signal proces- sors. Covered are its architecture, internal register structure, instruction set, pipeline, specifications, DMA, and I/O ports. Software applications are covered in a dedicated chapter. Read This First v Related Documentation From Texas Instruments TMS320C1x/C2x/C2xx/C5x Assembly Language Tools User’s Guide (lit- erature number SPRU018) describes the assembly language tools (as- sembler, linker, and other tools used to develop assembly language code), assembler directives, macros, common object file format, and symbolic debugging directives for the ’C1x, ’C2x, ’C2xx, and ’C5x gen- erations of devices. TMS320C2x Software Development System Technical Reference (liter- ature number SPRU072) provides specific application and design in- formation for using the TMS320C2x Software Development System (SWDS) board. TMS320C5x Software Development System Technical Reference (liter- ature number SPRU066) provides specific application and design in- formation for using the TMS320C5x Software Development System (SWDS) board. TMS320C2x C Source Debugger User’s Guide (literature number SPRU070) tells how to use the ’C2x C source debugger with the ’C2x emulator, software development system (SWDS), and simulator. TMS320C5x C Source Debugger User’s Guide (literature number SPRU055) tells you how to invoke the ’C5x emulator, EVM, and simulator versions of the C source debugger interface. This book discusses various aspects of the debugger interface, including window management, command entry, code execution, data management, and breakpoints, and includes a tutorial that introduces basic debugger functionality. vi Related DocumentationRelated Documentation From Texas / TrademarksInstruments Related Documentation The C Programming Language (second edition), by Brian W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New Jersey, 1988. You may find these documents helpful as well: American National Standard for Information Systems—Programming Language C X3.159-1989, American National Standards Institute (ANSI standard for C) Programming in C, Kochan, Steve G., Hayden Book Company Trademarks MS-DOS is a registered trademark of Microsoft Corp. PC-DOS is a trademark of International Business Machines Corp. SPARC is a trademark of SPARC International, Inc. Sun-OS and Sun Workstation are trademarks of Sun Microsystems, Inc. XDS is