TMS320C3x/C4x Optimizing C Compiler User’s Guide Literature Number: SPRU034H June1998 Printed on Recycled Paper IMPORTANT NOTICE Texas Instruments (TI) reserves the right to make changes to its products or to discontinue any semiconductor product or service without notice, and advises its customers to obtain the latest version of relevant information to verify, before placing orders, that the information being relied on is current. TI warrants performance of its semiconductor products and related software 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, INTENDED, AUTHORIZED, OR WARRANTED TO BE SUITABLE FOR USE IN LIFE-SUPPORT APPLICATIONS, DEVICES OR SYSTEMS OR OTHER CRITICAL APPLICATIONS. Inclusion of TI products in such applications is understood to be fully at the risk of the customer. Use of TI products in such applications requires the written approval of an appropriate TI officer. Questions concerning potential risk applications should be directed to TI through a local SC sales office. In order to minimize risks associated with the customer’s applications, adequate design and operating safeguards should be provided by the customer to minimize inherent or procedural hazards. TI assumes no liability for applications assistance, customer product design, software performance, or infringement of patents or services described herein. Nor does TI 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. Copyright 1998, Texas Instruments Incorporated Preface Read This First About This Manual The TMS320C3x/C4x Optimizing C Compiler User’s Guide tells you how to use these compiler tools: - Compiler - Source interlist utility - Optimizer - Preprocessor - Library-build utility This compiler accepts American National Standards Institute (ANSI) standard C source code and produces assembly language source code for the TMS320C3x/4x devices. This user’s guide discusses the characteristics of the TMS320C3x/4x opti- mizing 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, describes C based on the ANSI C standard. Use the Kernighan and Ritchie book as a supplement to this manual. Before you can use this book, you should read the TMS320C3x/C4x Code Generation Tools Getting Started Guide to install the C compiler tools. Read This First iii How to to Use This This Manual 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 TMS320C3x/4x devices. This book is divided into three distinct parts: - Introductory information, in chapter one, provides an overview of the TMS320C3x/4x development tools. - Compiler description, in chapter two, 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 tech- nical information on the TMS320C3x/4x 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, in chapters three through six and the glossary, pro- vides supplementary information on TMS320C3x/4x specific optimiza- tions, and definitions of terms used in the book. 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 program listing: 0011 0005 0001 .field 1, 2 0012 0005 0003 .field 3, 4 0013 0005 0006 .field 6, 3 0014 0006 .even Here is an example of a system prompt and a command that you might enter: C: csr –a /user/ti/simuboard/utilities - In syntax descriptions, the instruction, command, or directive is in a bold typeface font and parameters are in an italic typeface. Portions of a syntax that are in bold should 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: iv Notational Conventions .asect ”section name”, address .asect is the directive. This directive has two parameters, indicated by sec- tion name and address. When you use .asect, the first parameter must be an actual section name, enclosed in double quotes; the second parameter must be an address. - Square brackets ( [ and ] ) identify an optional parameter. If you use an optional parameter, you specify the information within the brackets; you don’t enter the brackets themselves. Here’s an example of an instruction that has an optional parameter: LALK 16–bit constant [, shift] The LALK instruction has two parameters. The first parameter, 16-bit con- stant, is required. The second parameter, shift, is optional. As this syntax shows, if you use the optional second parameter, you must precede it with a comma. Square brackets are also used as part of the pathname specification for VMS pathnames; in this case, the brackets are actually part of the path- name (they are not optional). - Braces ( { and } ) indicate a list. The symbol | (read as or) separates items within the list. Here’s an example of a list: { * | *+ | *– } This provides three choices: *, *+, or *–. Unless the list is enclosed in square brackets, you must choose one item from the list. - Some directives can have a varying number of parameters. For example, the .byte directive can have up to 100 parameters. The syntax for this di- rective is: .byte value1 [, ... , valuen] This syntax shows that .byte must have at least one value parameter, but you have the option of supplying additional value parameters, separated by commas. Read This First v Related Documentation From Texas Instruments Related Documentation From Texas Instruments The following books describe the TMS320C3x/C4x and related support tools. To obtain a copy of any of these TI documents, call the Texas Instruments Liter- ature Response Center at (800) 477–8924. When ordering, please identify the book by its title and literature number. TMS320C3x/C4x Code Generation Tools Getting Started Guide (literature number SPRU119) describes how to install the TMS320C3x/C4x assembly language tools and the C compiler. Installation instructions are included for MS-DOS, Windows 3.x, Windows NT, Windows 95, SunOS, Solaris, and HP-UX systems. TMS320C3x/C4x Assembly Language Tools User’s Guide (literature number SPRU035) describes the assembly language tools (assembler, linker, and other tools used to develop assembly language code), assembler directives, macros, common object file format, and symbolic debugging directives for the ’C3x and ’C4x generations of devices. TMS320C3x C Source Debugger User’s Guide (literature number SPRU053) tells you how to invoke the ’C3x emulator, evaluation module, 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. It also includes a tutorial that introduces basic debugger functionality. TMS320C4x C Source Debugger User’s Guide (literature number SPRU054) tells you how to invoke the ’C4x emulator and simulator ver- sions of the C source debugger interface. This book discusses various aspects of the debugger interface, including window management, com- mand entry, code execution, data management, and breakpoints. It also includes a tutorial that introduces basic debugger functionality. TMS320C3x User’s Guide (literature number SPRU031) describes the ’C3x 32-bit floating-point microprocessor (developed for digital signal proces- sing as well as general applications), its architecture, internal register structure, instruction set, pipeline, specifications, and DMA and serial port operation. Software and hardware applications are included. TMS320C32 Addendum to the TMS320C3x User’s Guide (literature num- ber SPRU132) describes the TMS320C32 floating-point microprocessor (developed for digital signal processing as well as general applications). Discusses its architecture, internal register structure, specifications, and DMA and serial port operation. Hardware applications are also included. vi Related Documentation From Texas Instruments TMS320C4x User’s Guide (literature number SPRU063) describes the ’C4x 32-bit floating-point processor, developed for digital signal processing