TMS320C28x Assembly Language Tools User s Guide

Transcription

1 TMS320C28x Assembly Language Tools User s Guide Literature Number: SPRU513A December 2003 Printed on Recycled Paper

2 IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All products are sold subject to TI s terms and conditions of sale supplied at the time of order acknowledgment. TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI s standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily performed. TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards. TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information published by TI regarding third-party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI. Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation. Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements. Following are URLs where you can obtain information on other Texas Instruments products and application solutions: Products Applications Amplifiers amplifier.ti.com Audio Data Converters dataconverter.ti.com Automotive DSP dsp.ti.com Broadband Interface interface.ti.com Digital Control Logic logic.ti.com Military Power Mgmt power.ti.com Optical Networking Microcontrollers microcontroller.ti.com Security Telephony Video & Imaging Wireless Mailing Address: Texas Instruments Post Office Box Dallas, Texas Copyright 2004, Texas Instruments Incorporated

3 Preface About This Manual The TMS320C28x Assemby Language Tools User s Guide tells you how to use these assembly language tools: Assembler Archiver Linker Absolute lister Cross-reference lister Object file display utility Name utility Strip utility Hex-conversion utility How to Use This Manual This book helps you learn to use the Texas Instruments assembly language tools specifically designed for the TMS320C28x devices. You can think of this book as four parts: Introductory information, consisting of Chapters 1 and 2, gives you an overview of the assembly language development tools. It also discusses common object file format (COFF), which helps you to use the TMS320C28x tools more efficiently. Read Chapter 2, Introduction to Common Object File Format, before using the assembler and linker. Assembler description, consisting of Chapters 3 through 5, contains detailed information about using the assembler. This part of the book explains how to invoke the assembler and discusses source statement format, valid constants and expressions, assembler output, and assembler directives. It also describes the macro language. Read This First iii

4 Notational Conventions Additional assembly language tools description, consisting of Chapters 6 through 11, describes in detail each of the tools provided with the assembler to help you create executable object files. For example, Chapter 7 explains how to invoke the linker, how the linker operates, and how to use linker directives. Reference material, consisting of Appendixes A through D, provides supplementary information. This part contains technical data about the internal format and structure of COFF object files. It discusses symbolic debugging directives that the TMS320C28x C/C++ compiler uses. Finally, it includes hex-conversion utility examples, assembler and linker error messages, and a glossary. Notational Conventions This document uses the following conventions: The TMS320C28x core is also referred to as TMS320C28x or C28x. Program listings, program examples, and interactive displays are shown in a special typeface. 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: data F.byte byte D903 ADDB XAR1, #3 In syntax descriptions, the instruction, command, or directive is in a bold typeface 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. Syntax that is entered on a command line is centered. Syntax that is used in a text file is left-justified. Here is an example of command-line syntax: cl2000 v28 z [options] filename 1,...[ filename n] The cl2000 v28 z command invokes the linker and has two parameters. The first parameter, options, is optional (see the next list item for details). The second parameter, filename 1, is required, and you can optionally enter more than one filename parameter. iv

5 Notational Conventions Square brackets ( [ and ] ) identify an optional parameter. If you use an optional parameter, you specify the information within the brackets. Unless the square brackets are in a bold typeface, do not enter the brackets themselves. This is an example of a command that has an optional parameter: hex2000 [options] filename The hex2000 command has two parameters. The second parameter, filename, is required. The first parameter, options, is optional. Since options is plural, you can select several options. In assembler syntax statements, column 1 is reserved for the first character of a label or symbol. If the label or symbol is optional, it is usually not shown. If it is a required parameter, it is shown starting in the left margin of the shaded box, as in the example below. No instruction, command, directive, or parameter, other than a symbol or label, can begin in column1. symbol.usect section name, size in bytes [, alignment] The symbol is required for the.usect directive and must begin in column 1. The section name must be enclosed in quotes and the parameter size in bytes must be separated from the section name by a comma. The alignment is optional and, if used, must be separated by a comma. Some directives can have a varying number of parameters. For example, the.byte directive can have up to 100 parameters. The syntax for this directive is: Note that.byte does not begin in column 1..byte value 1 [,..., value n ] This syntax shows that.byte must have at least one value parameter, but you have the option of supplying additional value parameters, each separated from the previous one by a comma. Read This First v

6 Related Documentation From Texas Instruments Following are other symbols and abbreviations used throughout this document: Symbol Definition Symbol Definition B,b Suffix binary integer MSB Most significant bit H,h Suffix hexadecimal integer 0x Prefix hexadecimal integer LSB Least significant bit Q,q Suffix octal integer Related Documentation From Texas Instruments The following books describe the TMS320C28x and related support tools. To obtain any of these TI documents, call the Texas Instruments Literature Response Center at (800) When ordering, identify the book by its title and literature number (located on the title page): TMS320C28x Optimizing C/C++ Compiler User s Guide (literature number SPRU514) describes the TMS320C28x C/C++ compiler. This C/C++ compiler accepts ANSI standard C/C++ source code and produces TMS320 assembly language source code for the TMS320C28x device. Code Composer Studio User s Guide (literature number SPRU328) explains how to use the Code Composer development environment to build and debug embedded real-time DSP applications. TMS320C28x DSP CPU and Instruction Set Reference Guide (literature number SPRU430) describes the central processing unit (CPU) and the assembly language instructions of the TMS320C28x fixed-point digital signal processors (DSPs). It also describes emulation features available on these DSPs. TMS320C2xx User s Guide (literature number SPRU127) discusses the hardware aspects of the TMS320C2xx 16-bit fixed-point digital signal processors. It describes the architecture, the instruction set, and the onchip peripherals. vi

7 Related Documentation Related Documentation You can use the following books to supplement this user s guide: Advanced C: Techniques and Applications, Gerald E. Sobelman and David E. Krekelberg, Que Corporation American National Standard for Information Systems Programming Language C X , American National Standards Institute (ANSI standard for C) Programming in C, Steve G. Kochan, Hayden Book Company Programming Language C++, ISO/IEC , American National Standards Institute (ANSI standard for C++) The Annotated C++ Reference Manual, Margaret A. Ellis and Bjarne Stroustrup, published by Addison-Wesley Publishing Company, Reading, Massachusetts, 1990 The C Programming Language (second edition), Brian W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New Jersey, 1988, describes ANSI C. The C++ Programming Language (third edition), Bjarne Stroustrup, published by Addison-Wesley Publishing Company, Reading, Massachusetts, 1997 Understanding and Using COFF, Gintaras R. Gircys, published by O Reilly and Associates, Inc. Read This First vii

8 Trademarks Windows and Windows NT are trademarks of Microsoft Corporation. The Texas Instruments logo and Texas Instruments are registered trademarks of Texas Instruments Incorporated. Trademarks of Texas Instruments include: TI, XDS, Code Composer, Code Composer Studio, TMS320, TMS320C28x and 320 Hotline On-line. All other brand or product names are trademarks or registered trademarks of their respective companies or organizations. viii

9 Contents 1 Introduction to the Software Development Tools Provides an overview of the software development tools. 1.1 Software Development Tools Overview Tools Descriptions Introduction to Common Object File Format Common object file format, or COFF, is the object file format used by the TMS320C28x tools. This chapter discusses the basic COFF concept of sections and how they can help you use the assembler and linker more efficiently. Read this chapter before using the assembler and linker. 2.1 Sections How the Assembler Handles Sections Uninitialized Sections Initialized Sections Named Sections Subsections Section Program Counters An Example That Uses Sections Directives How the Linker Handles Sections Default Memory Allocation Placing Sections in the Memory Map Relocation Run-Time Relocation Loading a Program Symbols in a COFF File External Symbols The Symbol Table Assembler Description Explains how to invoke the assembler and discusses source statement format, valid constants and expressions, and assembler output. 3.1 Assembler Overview The Assembler s Role in the Software Development Flow Invoking the Assembler Naming Alternate Directories for Assembler Input Using the I Assembler Option Using the C2000_A_DIR and A_DIR Environment Variables ix

10 Contents 3.5 Source Statement Format Label Field Mnemonic Field Operand Field Comment Field Constants Binary Integers Octal Integers Decimal Integers Hexadecimal Integers Character Constants Assembly-Time Constants Floating-Point Constants Character Strings Symbols Labels Local Labels Symbolic Constants Defining Symbolic Constants ( d Option) Predefined Symbolic Constants Substitution Symbols Expressions Operators Expression Overflow and Underflow Well-Defined Expressions Conditional Expressions Legal Expressions Built-In Functions Source Listings Debugging Assembly Source Cross-Reference Listings Smart Encoding C-Type Symbolic Debugging for Assembly Variables ( mg option) TMS320C28x Assembler Modes C27x Object Mode C28x Object Mode C28x Object Accept C27x Syntax Mode C28x Object Accept C2xlp Syntax Mode x

11 Contents 4 Assembler Directives Describes the directives according to function and presents the directives in alphabetical order. 4.1 Directives Summary Compatibility With the TMS320C1x/C2x/C2xx/C5x Assembler Directives Directives That Define Sections Directives That Initialize Constants Directive That Aligns the Section Program Counter Directives That Format the Output Listing Directives That Reference Other Files Directives That Enable Conditional Assembly Directives That Define Symbols at Assembly Time Assembler Mode Override Directives Miscellaneous Directives Directives Reference Macro Language Describes macro directives, substitution symbols used as macro parameters, and how to create macros. 5.1 Using Macros Defining Macros Macro Parameters/Substitution Symbols Directives That Define Substitution Symbols Built-In Substitution Symbol Functions Recursive Substitution Symbols Forced Substitutions Accessing Individual Characters of Subscripted Substitution Symbols Substitution Symbols as Local Variables in Macros Macro Libraries Using Conditional Assembly in Macros Using Labels in Macros Producing Messages in Macros Using Directives to Format the Output Listing Using Recursive and Nested Macros Macro Directives Summary Archiver Description Describes instructions for invoking the archiver, creating new archive libraries, and modifying existing libraries. 6.1 Archiver Overview The Archiver s Role in the Software Development Flow Invoking the Archiver Archiver Examples Contents xi

12 Contents 7 Linker Description Explains how to invoke the linker, provides details about linker operation, discusses linker directives, and presents a detailed linking example. 7.1 Linker Overview The Linker s Role in the Software Development Flow Invoking the Linker Linker Options Relocation Capabilities ( a and r Options) Disable Merge of Symbolic Debugging Information ( b Option) C Language Options ( c and cr Options) Define an Entry Point ( e Option) Set Default Fill Value ( f fill_value Option) Make a Symbol Global ( g symbol Option) Make All Global Symbols Static ( h Option) Define Heap Size ( heap size Option) Alter the Library Search Algorithm ( l Option, I Option, and C_DIR Environment Variable) Disable Conditional Linking ( j Option) Ignore Alignment ( k Option) Create a Map File ( m filename Option) Name an Output Module ( o filename Option) Specify a Quiet Run ( q Option) Strip Symbolic Information ( s Option) Define Stack Size ( stack size Option) Introduce an Unresolved Symbol ( u symbol Option) Display a Message When an Undefined Output Section Is Created ( w Option) Exhaustively Read and Search Libraries ( x and priority Options) Generate XML Link Information File ( xml_link_info Option) Linker Command Files Reserved Names in Linker Command Files Constants in Linker Command Files Object Libraries The MEMORY Directive Default Memory Model MEMORY Directive Syntax The SECTIONS Directive SECTIONS Directive Syntax Allocation Specifying Input Sections Specifying a Section s Run-Time Address Specifying Load and Run Addresses Uninitialized Sections Referring to the Load Address by Using the.label Directive xii

13 Contents 7.10 Using UNION and GROUP Statements Overlaying Sections With the UNION Statement Grouping Output Sections Together Overlaying Pages Using the MEMORY Directive to Define Overlay Pages Example of Overlay Pages Using Overlay Pages With the SECTIONS Directive Memory Allocation for Overlaid Pages Special Section Types (DSECT, COPY, and NOLOAD) Default Allocation Output Section Formation Default Allocation Algorithm Assigning Symbols at Link Time Syntax of Assignment Statements Assigning the SPC to a Symbol Assignment Expressions Symbols Defined by the Linker Assigning Exact Start, End, and Size Values of a Section to a Symbol Why the Dot Operator Does Not Always Work Address and Dimension Operators Creating and Filling Holes Initialized and Uninitialized Sections Creating Holes Filling Holes Explicit Initialization of Uninitialized Sections Linker-Generated Copy Tables A Current Boot-Loaded Application Development Process An Alternative Approach Overlay Management Example Generating Copy Tables Automatically with the Linker The table() Operator Boot-Time Copy Tables Using the table() Operator to Manage Object Components Copy Table Contents General Purpose Copy Routine Linker Generated Copy Table Sections and Symbols Splitting Object Components and Overlay Management Partial (Incremental) Linking Linking C Code Run-Time Initialization Object Libraries and Run-Time Support Setting the Size of the Stack and Heap Sections Autoinitialization of Variables at Run Time Autoinitialization of Variables at Load Time The c and cr Linker Options Linker Examples Contents xiii

14 Contents 8 Absolute Lister Description Explains how to invoke the absolute lister to obtain a listing of the absolute addresses of an object file. 8.1 Producing an Absolute Listing Invoking the Absolute Lister Absolute Lister Example Cross-Reference Lister Description Explains how to invoke the cross-reference lister to obtain a listing of symbols, their definitions, and their references in the linked source files. 9.1 Producing a Cross-Reference Listing Invoking the Cross-Reference Lister Cross-Reference Listing Example Object File Utilities Descriptions Explains how to invoke the object file display utility, the name utility, and the strip utility Invoking the Object File Display Utility XML Tag Index Example XML Consumer The Main Application xml.h { Declaration of the XMLEntity Object xml.cpp { Definition of the XMLEntity Object Invoking the Name Utility Invoking the Strip Utility Hex-Conversion Utility Description Explains how to invoke the hex utility to convert a COFF object file into one of several standard hexadecimal formats suitable for loading into an EPROM programmer The Hex-Conversion Utility s Role in the Software Development Flow Invoking the Hex-Conversion Utility Invoking the Hex-Conversion Utility From the Command Line Invoking the Hex-Conversion Utility With a Command File Understanding Memory Widths Target Width Specifying the Memory Width Partitioning Data Into Output Files Specifying Word Order for Output Words The ROMS Directive When to Use the ROMS Directive An Example of the ROMS Directive The SECTIONS Directive Excluding a Specified Section Assigning Output Filenames xiv

15 Contents 11.8 Image Mode and the fill Option Generating a Memory Image Specifying a Fill Value Steps to Follow in Image Mode Building a Table for an On-Chip Boot Loader Description of the Boot Table The Boot Table Format Controlling the Boot Loader Booting From a Device Peripheral Setting the Entry Point for the Boot Table Using the C28x Boot Loader Controlling the ROM Device Address Object Formats ASCII-Hex Object Format ( a Option) Intel MCS-86 Object Format ( i Option) Motorola-S Object Format ( m Option) TI-Tagged SDSMAC Object Format ( t Option) Extended Tektronix Object Format ( x Option) Hex-Conversion Utility Error Messages A Common Object File Format A-1 Contains supplemental technical data about the internal format and structure of COFF object files. A.1 COFF File Structure A-2 A.2 File Header Structure A-4 A.3 Optional File Header Format A-5 A.4 Section Header Structure A-6 A.5 Structuring Relocation Information A-9 A.6 Symbol Table Structure and Content A-11 A.6.1 Special Symbols A-12 A.6.2 Symbol Name Format A-13 A.6.3 String Table Structure A-13 A.6.4 Storage Classes A-14 A.6.5 Symbol Values A-14 A.6.6 Section Number A-15 A.6.7 Auxiliary Entries A-15 B Symbolic Debugging Directives B-1 Discusses symbolic debugging directives that the TMS320C28x C/C++ compiler uses. B.1 DWARF Debugging Format B-2 B.2 COFF Debugging Format B-3 B.3 Debug Directive Syntax B-4 Contents xv

16 Contents C XML Link Information File Description C-1 Discusses the xml_link_info file contents including file element types and document elements. C.1 XML Information File Element Types C-2 C.2 Document Elements C-3 C.2.1 Header Elements C-3 C.2.2 Input File List C-4 C.2.3 Object Component List C-5 C.2.4 Logical Group List C-6 C.2.5 Placement Map C-9 C.2.6 Symbol Table C Glossary D Defines terms and acronyms used in this book. xvi

17 Figures 1 1 TMS320C28x Software Development Flow Partitioning Memory Into Logical Blocks Object Code Generated by the File in Example Combining Input Sections to Form an Executable Object Module The Assembler in the TMS320C28x Software Development Flow The.space and.bes Directives The.field Directive Initialization Directives The.align Directive Allocating.bss Blocks Within a Page The.field Directive The.usect Directive The Archiver in the TMS320C28x Software Development Flow The Linker in the TMS320C28x Software Development Flow Memory Map Defined in Example Section Allocation Defined in Example Run-Time Execution of Example Memory Allocation Shown in Example 7 7 and Example Overlay Pages Defined in Example 7 10 and Example Autoinitialization at Run Time Autoinitialization at Load Time Absolute Lister Development Flow module1.lst module2.lst Cross-Reference Lister Development Flow The Hex-Conversion Utility in the TMS320C28x Software Development Flow Hex-Conversion Utility Process Flow COFF Data and Memory Widths Data, Memory, and ROM Widths Varying the Word Order The infile.out File Partitioned Into Four Output Files ASCII-Hex Object Format Intel MCS86 Hexadecimal Object Format Motorola-S Object Format TI-Tagged Object Format Extended Tektronix Object Format Contents xvii

18 Figures A 1 COFF File Structure A-2 A 2 Sample COFF Object File A-3 A 3 Section Header Pointers for the.text Section A-8 A 4 Symbol-Table Contents A-11 A 5 String-Table Entries for Sample Symbol Names A-13 xviii

19 Tables 3 1 Order of Precedence of Operators Used in Expressions Built-In Mathematical Functions Symbol Attributes Smart Encoding for Efficiency Smart Encoding Intuitively Non-TMS320C27x Instructions Supported in the C27x Object Mode Assembler Directives Summary Functions and Return Values Creating Macros Manipulating Substitution Symbols Conditional Assembly Producing Assembly-Time Messages Formatting the Listing Linker Options Summary Groups of Operators Used in Expressions on Order of Precedence Symbol Attributes XML Tag Index Basic Options Boot-Loader Options Boot Table Source Formats Boot Table Format Options for Specifying Hex-Conversion Formats A 1 File Header Contents A-4 A 2 File Header Flags (Bytes 18 and 19) A-4 A 3 Optional File Header Contents A-5 A 4 Section Header Contents A-6 A 5 Section Header Flags (Bytes 40 Through 43) A-7 A 6 Relocation Entry Contents A-9 A 7 Relocation Types (Bytes 8 and 9) A-10 A 8 Symbol-Table Entry Contents A-12 A 9 Special Symbols in the Symbol Table A-12 A 10 Symbol Storage Classes A-14 A 11 Section Numbers A-15 A 12 Section Format for Auxiliary Table Entries A-15 B 1 Symbolic Debugging Directives B-4 Contents xix

20 Examples 2 1 Using Sections Directives An Example of Code That Generates Relocation Entries Relocation Expression Local Labels of the Form $n Local Labels Using Symbolic Constants Defined on Command Line Portion of an Assembler Listing Viewing Assembly Variables as C Types An Assembler Cross-Reference Listing Sections Directives Macro Definition, Call, and Expansion Calling a Macro With Varying Numbers of Arguments The.asg Directive The.eval Directive Using Built-In Substitution Symbol Functions Recursive Substitution Using the Forced Substitution Operator Using Subscripted Substitution Symbols to Redefine an Instruction Using Subscripted Substitution Symbols to Find Substrings The.loop/.break/.endloop Directives Nested Conditional Assembly Directives Built-In Substitution Symbol Functions in a Conditional Assembly Block Unique Labels in a Macro Producing Messages in a Macro Using Nested Macros Using Recursive Macros Linker Command File Command File With Linker Directives The MEMORY Directive The SECTIONS Directive The Most Common Method of Specifying Section Contents Copying a Section From ROM to RAM The UNION Statement Separate Load Addresses for UNION Sections Allocate Sections Together Memory Directive With Overlay Pages xx

21 Examples 7 11 SECTIONS Directive Definition for Overlays in Example Default Allocation for TMS320C28x Devices Using a UNION for Memory Overlay Produce Address for Linker Generated Copy Table Linker Command File to Manage Object Components TMS320C28x cpy_tbl.h File Run-Time-Support cpy_tbl.c File The cpy_utils.asm File Controlling the Placement of the Linker-Generated Copy Table Sections Creating a Copy Table to Access a Split Object Component Split Object Component Driver Linker Command File, demo.cmd Output Map File, demo.map A ROMS Directive Example Map File Output From Example 11 1 Showing Memory Ranges Sample Command File for Booting From 8-Bit SPI Boot Sample Hex Convertor Out File or Booting From 8-Bit SPI Boot Sample Command File for C28x 16-Bit Parallel Boot GP I/O Sample Hex Convertor Out File for C28x 16-Bit Parallel Boot GP I/O Sample Command File for Booting From 8-Bit SCI Boot Sample Hex Convertor Out File for Booting From 8-Bit SCI Boot C 1 Header Element for the hi.out Output File C-3 C 2 Input File List for the hi.out Output File C-4 C 3 Object Component List for the fl 4 Input File C-5 C 4 Logical Group List for the fl 4 Input File C-8 C 5 Placement Map for the fl 4 Input File C-10 C 6 Symbol Table for the fl 4 Input File C-11 Contents xxi

22 Notes Default Section Directive Expression Cannot Be Larger Than Space Reserved Octal Numbers Not Accepted With C2xlp Syntax Mode Differences in Precedence From Other TMS320 Assemblers Labels and Comments in Syntax Directives That Initialize Constants When Used in a.struct/.endstruct Sequence Ending a Macro Creating a Listing File ( l Option) The.struct Directive Does Not Allocate Memory Directives That Can Appear in a.struct/.endstruct Sequence Naming Library Members The a and r Options Filling Memory Ranges Binding Is Incompatible With Alignment and Named Memory You Cannot Specify Addresses for Sections Within a GROUP Overlay Section and Overlay Page Are Not the Same Linker Command File Operator Equivalencies Filling Sections Linking the.stack Section Boot Loader The TI-Tagged Format Is 16 Bits Wide When the order Option Applies Sections Generated by the C/C++ Compiler Defining the Ranges of Target Memory Valid Entry Points xxii