SPNU118Y
September 1995 – February 2020
Read This First
About This Manual
How to Use This Manual
Notational Conventions
Related Documentation From Texas Instruments
Trademarks
1
Introduction to the Software Development Tools
1.1
Software Development Tools Overview
1.2
Tools Descriptions
2
Introduction to Object Modules
2.1
Object File Format Specifications
2.2
Executable Object Files
2.3
Introduction to Sections
2.3.1
Special Section Names
2.4
How the Assembler Handles Sections
2.4.1
Uninitialized Sections
2.4.2
Initialized Sections
2.4.3
User-Named Sections
2.4.4
Current Section
2.4.5
Section Program Counters
2.4.6
Subsections
2.4.7
Using Sections Directives
2.5
How the Linker Handles Sections
2.5.1
Combining Input Sections
2.5.2
Placing Sections
2.6
Symbols
2.6.1
Global (External) Symbols
2.6.2
Local Symbols
2.6.3
Weak Symbols
2.6.4
The Symbol Table
2.7
Symbolic Relocations
Example 1. Code That Generates Relocation Entries
2.8
Loading a Program
3
Program Loading and Running
3.1
Loading
3.1.1
Load and Run Addresses
3.1.2
Bootstrap Loading
3.1.2.1
Boot, Load, and Run Addresses
3.1.2.2
Primary Bootloader
3.1.2.3
Secondary Bootloader
3.1.2.4
Boot Table
3.1.2.5
Bootloader Routine
Example 1. Sample Secondary Bootloader Routine
3.2
Entry Point
3.3
Run-Time Initialization
3.3.1
The _c_int00 Function
3.3.2
RAM Model vs. ROM Model
3.3.2.1
Autoinitializing Variables at Run Time (--rom_model)
3.3.2.2
Initializing Variables at Load Time (--ram_model)
3.3.2.3
The --rom_model and --ram_model Linker Options
3.3.3
About Linker-Generated Copy Tables
3.3.3.1
BINIT
3.3.3.2
CINIT
3.4
Arguments to main
3.5
Run-Time Relocation
3.6
Additional Information
4
Assembler Description
4.1
Assembler Overview
4.2
The Assembler's Role in the Software Development Flow
4.3
Invoking the Assembler
4.4
Controlling Application Binary Interface
4.5
Naming Alternate Directories for Assembler Input
4.5.1
Using the --include_path Assembler Option
4.5.2
Using the TI_ARM_A_DIR Environment Variable
4.6
Source Statement Format
4.6.1
Label Field
4.6.2
Mnemonic Field
4.6.3
Operand Field
4.6.3.1
Operand Syntaxes for Instructions
4.6.3.2
Immediate Values as Operands for Directives
4.6.4
Comment Field
4.7
Literal Constants
4.7.1
Integer Literals
4.7.1.1
Binary Integer Literals
4.7.1.2
Octal Integer Literals
4.7.1.3
Decimal Integer Literals
4.7.1.4
Hexadecimal Integer Literals
4.7.1.5
Character Literals
4.7.2
Character String Literals
4.7.3
Floating-Point Literals
4.8
Assembler Symbols
4.8.1
Identifiers
4.8.2
Labels
4.8.3
Local Labels
Example 1. Local Labels of the Form $n
4.8.4
Symbolic Constants
4.8.5
Defining Symbolic Constants (--asm_define Option)
Example 2. Using Symbolic Constants Defined on Command Line
4.8.6
Predefined Symbolic Constants
4.8.7
Registers
4.8.8
Substitution Symbols
4.9
Expressions
4.9.1
Mathematical and Logical Operators
4.9.2
Relational Operators and Conditional Expressions
4.9.3
Well-Defined Expressions
4.9.4
Relocatable Symbols and Legal Expressions
4.9.5
Expression Examples
4.10
Built-in Functions and Operators
4.10.1
Built-In Math and Trigonometric Functions
4.11
Unified Assembly Language Syntax Support
4.12
Source Listings
4.13
Debugging Assembly Source
Example 3. Viewing Assembly Variables as C Types C Program
Example 4. Assembly Program for
4.14
Cross-Reference Listings
Example 5. An Assembler Cross-Reference Listing
5
Assembler Directives
5.1
Directives Summary
5.2
Directives that Define Sections
Example 1. Sections Directives
5.3
Directives that Change the Instruction Type
5.4
Directives that Initialize Values
5.5
Directives that Perform Alignment and Reserve Space
5.6
Directives that Format the Output Listings
5.7
Directives that Reference Other Files
5.8
Directives that Enable Conditional Assembly
5.9
Directives that Define Union or Structure Types
5.10
Directives that Define Enumerated Types
5.11
Directives that Define Symbols at Assembly Time
5.12
Miscellaneous Directives
5.13
Directives Reference
6
Macro Language Description
6.1
Using Macros
6.2
Defining Macros
Example 1. Macro Definition, Call, and Expansion
6.3
Macro Parameters/Substitution Symbols
Example 2. Calling a Macro With Varying Numbers of Arguments
6.3.1
Directives That Define Substitution Symbols
Example 3. The .asg Directive
Example 4. The .eval Directive
6.3.2
Built-In Substitution Symbol Functions
Example 5. Using Built-In Substitution Symbol Functions
6.3.3
Recursive Substitution Symbols
Example 6. Recursive Substitution
6.3.4
Forced Substitution
Example 7. Using the Forced Substitution Operator
6.3.5
Accessing Individual Characters of Subscripted Substitution Symbols
Example 8. Using Subscripted Substitution Symbols to Redefine an Instruction
Example 9. Using Subscripted Substitution Symbols to Find Substrings
6.3.6
Substitution Symbols as Local Variables in Macros
6.4
Macro Libraries
6.5
Using Conditional Assembly in Macros
Example 10. The .loop/.break/.endloop Directives
Example 11. Nested Conditional Assembly Directives
Example 12. Built-In Substitution Symbol Functions in a Conditional Assembly Code Block
6.6
Using Labels in Macros
Example 13. Unique Labels in a Macro
6.7
Producing Messages in Macros
Example 14. Producing Messages in a Macro
6.8
Using Directives to Format the Output Listing
6.9
Using Recursive and Nested Macros
Example 15. Using Nested Macros
Example 16. Using Recursive Macros
6.10
Macro Directives Summary
7
Archiver Description
7.1
Archiver Overview
7.2
The Archiver's Role in the Software Development Flow
7.3
Invoking the Archiver
7.4
Archiver Examples
Example 1. Archiver Command File
7.5
Library Information Archiver Description
7.5.1
Invoking the Library Information Archiver
7.5.2
Library Information Archiver Example
7.5.3
Listing the Contents of an Index Library
7.5.4
Requirements
8
Linker Description
8.1
Linker Overview
8.2
The Linker's Role in the Software Development Flow
8.3
Invoking the Linker
8.4
Linker Options
8.4.1
Wildcards in File, Section, and Symbol Patterns
8.4.2
Specifying C/C++ Symbols with Linker Options
8.4.3
Relocation Capabilities (--absolute_exe and --relocatable Options)
8.4.3.1
Producing an Absolute Output Module (--absolute_exe option)
8.4.3.2
Producing a Relocatable Output Module (--relocatable option)
8.4.3.3
Producing an Executable, Relocatable Output Module (-ar Option)
8.4.4
Allocate Memory for Use by the Loader to Pass Arguments (--arg_size Option)
8.4.5
Changing Encoding of Big-Endian Instructions
8.4.6
Compression (--cinit_compression and --copy_compression Option)
8.4.7
Compress DWARF Information (--compress_dwarf Option)
8.4.8
Control Linker Diagnostics
8.4.9
Automatic Library Selection (--disable_auto_rts Option)
8.4.10
Do Not Remove Unused Sections (--unused_section_elimination Option)
8.4.11
Linker Command File Preprocessing (--disable_pp, --define and --undefine Options)
8.4.12
Error Correcting Code Testing (--ecc Options)
8.4.13
Define an Entry Point (--entry_point Option)
8.4.14
Set Default Fill Value (--fill_value Option)
8.4.15
Generate List of Dead Functions (--generate_dead_funcs_list Option)
8.4.16
Define Heap Size (--heap_size Option)
8.4.17
Hiding Symbols
8.4.18
Alter the Library Search Algorithm (--library, --search_path, and TI_ARM_C_DIR )
8.4.18.1
Name an Alternate Library Directory (--search_path Option)
8.4.18.2
Name an Alternate Library Directory (TI_ARM_C_DIR Environment Variable)
8.4.18.3
Exhaustively Read and Search Libraries (--reread_libs and --priority Options)
8.4.19
Change Symbol Localization
8.4.19.1
Make All Global Symbols Static (--make_static Option)
8.4.20
Create a Map File (--map_file Option)
8.4.21
Managing Map File Contents (--mapfile_contents Option)
8.4.22
Disable Name Demangling (--no_demangle)
8.4.23
Disable Merging of Symbolic Debugging Information (--no_sym_merge Option)
8.4.24
Strip Symbolic Information (--no_symtable Option)
8.4.25
Name an Output Module (--output_file Option)
8.4.26
Prioritizing Function Placement (--preferred_order Option)
8.4.27
C Language Options (--ram_model and --rom_model Options)
8.4.28
Retain Discarded Sections (--retain Option)
8.4.29
Create an Absolute Listing File (--run_abs Option)
8.4.30
Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)
8.4.31
Define Stack Size (--stack_size Option)
8.4.32
Enforce Strict Compatibility (--strict_compatibility Option)
8.4.33
Mapping of Symbols (--symbol_map Option)
8.4.34
Generate Far Call Trampolines (--trampolines Option)
8.4.34.1
Advantages and Disadvantages of Using Trampolines
8.4.34.2
Minimizing the Number of Trampolines Required (--minimize_trampolines Option)
8.4.34.3
Making Trampoline Reservations Adjacent (--trampoline_min_spacing Option)
8.4.34.4
Carrying Trampolines From Load Space to Run Space
8.4.35
Introduce an Unresolved Symbol (--undef_sym Option)
8.4.36
Display a Message When an Undefined Output Section Is Created (--warn_sections)
8.4.37
Generate XML Link Information File (--xml_link_info Option)
8.4.38
Zero Initialization (--zero_init Option)
8.5
Linker Command Files
Example 1. Linker Command File
Example 2. Command File With Linker Directives
8.5.1
Reserved Names in Linker Command Files
8.5.2
Constants in Linker Command Files
8.5.3
Accessing Files and Libraries from a Linker Command File
8.5.4
The MEMORY Directive
8.5.4.1
Default Memory Model
8.5.4.2
MEMORY Directive Syntax
Example 3. The MEMORY Directive
8.5.4.3
Expressions and Address Operators
Example 4. Origin and Length as Expressions
8.5.4.4
The ALIAS Statement
8.5.5
The SECTIONS Directive
8.5.5.1
SECTIONS Directive Syntax
Example 5. The SECTIONS Directive
8.5.5.2
Section Allocation and Placement
8.5.5.2.1
Example: Placing Functions in RAM
8.5.5.2.2
Binding
8.5.5.2.3
Named Memory
8.5.5.2.4
Controlling Placement Using The HIGH Location Specifier
Example 6. Linker Placement With the HIGH Specifier
Example 7. Linker Placement Without HIGH Specifier
8.5.5.2.5
Alignment and Blocking
8.5.5.2.6
Alignment With Padding
8.5.5.3
Specifying Input Sections
Example 8. The Most Common Method of Specifying Section Contents
8.5.5.4
Using Multi-Level Subsections
8.5.5.5
Specifying Library or Archive Members as Input to Output Sections
Example 9. Archive Members to Output Sections
8.5.5.6
Allocation Using Multiple Memory Ranges
8.5.5.7
Automatic Splitting of Output Sections Among Non-Contiguous Memory Ranges
8.5.6
Placing a Section at Different Load and Run Addresses
8.5.6.1
Specifying Load and Run Addresses
8.5.6.2
Referring to the Load Address by Using the .label Directive
Example 10. Moving a Function from Slow to Fast Memory at Run Time
Example 11. Linker Command File for
8.5.7
Using GROUP and UNION Statements
8.5.7.1
Grouping Output Sections Together
Example 12. Allocate Sections Together
8.5.7.2
Overlaying Sections With the UNION Statement
Example 13. The UNION Statement
Example 14. Separate Load Addresses for UNION Sections
8.5.7.3
Using Memory for Multiple Purposes
8.5.7.4
Nesting UNIONs and GROUPs
Example 15. Nesting GROUP and UNION Statements
8.5.7.5
Checking the Consistency of Allocators
8.5.7.6
Naming UNIONs and GROUPs
8.5.8
Special Section Types (DSECT, COPY, NOLOAD, and NOINIT)
8.5.9
Configuring Error Correcting Code (ECC) with the Linker
8.5.9.1
Using the ECC Specifier in the Memory Map
8.5.9.2
Using the ECC Directive
8.5.9.3
Using the VFILL Specifier in the Memory Map
8.5.10
Assigning Symbols at Link Time
8.5.10.1
Syntax of Assignment Statements
8.5.10.2
Assigning the SPC to a Symbol
8.5.10.3
Assignment Expressions
8.5.10.4
Symbols Automatically Defined by the Linker
8.5.10.5
Assigning Exact Start, End, and Size Values of a Section to a Symbol
8.5.10.6
Why the Dot Operator Does Not Always Work
8.5.10.7
Address and Dimension Operators
8.5.10.7.1
Input Items
8.5.10.7.2
Output Section
8.5.10.7.3
GROUPs
8.5.10.7.4
UNIONs
8.5.10.8
LAST Operator
8.5.11
Creating and Filling Holes
8.5.11.1
Initialized and Uninitialized Sections
8.5.11.2
Creating Holes
8.5.11.3
Filling Holes
8.5.11.4
Explicit Initialization of Uninitialized Sections
8.6
Linker Symbols
8.6.1
Using Linker Symbols in C/C++ Applications
8.6.2
Declaring Weak Symbols
8.6.3
Resolving Symbols with Object Libraries
8.7
Default Placement Algorithm
Example 16. Default Allocation for ARM Devices
8.7.1
How the Allocation Algorithm Creates Output Sections
8.7.2
Reducing Memory Fragmentation
8.8
Using Linker-Generated Copy Tables
8.8.1
Using Copy Tables for Boot Loading
8.8.2
Using Built-in Link Operators in Copy Tables
8.8.3
Overlay Management Example
Example 17. Using a UNION for Memory Overlay
8.8.4
Generating Copy Tables With the table() Operator
Example 18. Produce Address for Linker Generated Copy Table
8.8.4.1
The table() Operator
8.8.4.2
Boot-Time Copy Tables
8.8.4.3
Using the table() Operator to Manage Object Components
Example 19. Linker Command File to Manage Object Components
8.8.4.4
Linker-Generated Copy Table Sections and Symbols
Example 20. Controlling the Placement of the Linker-Generated Copy Table Sections
8.8.4.5
Splitting Object Components and Overlay Management
Example 21. Creating a Copy Table to Access a Split Object Component
Example 22. Split Object Component Driver
8.8.5
Compression
8.8.5.1
Compressed Copy Table Format
8.8.5.2
Compressed Section Representation in the Object File
8.8.5.3
Compressed Data Layout
8.8.5.4
Run-Time Decompression
8.8.5.5
Compression Algorithms
8.8.6
Copy Table Contents
Example 23. ARM cpy_tbl.h File
8.8.7
General Purpose Copy Routine
Example 24. Run-Time-Support cpy_tbl.c File
8.9
Linker-Generated CRC Tables
8.9.1
The crc_table() Operator
8.9.2
Restrictions
8.9.3
Examples
Example 25. Using crc_table() Operator to Compute the CRC Value for .text Data
Example 26. Specifying an Algorithm in the crc_table() Operator
Example 27. Using a Single Table for Multiple Sections
Example 28. Applying the crc_table() Operator to a GROUP or UNION
8.9.4
Interface
Example 29. The CRC Table Header, crc_tbl.h
Example 30. General Purpose CRC Check Routine
8.9.5
A Note on the TMS570_CRC64_ISO Algorithm
8.10
Partial (Incremental) Linking
8.11
Linking C/C++ Code
8.11.1
Run-Time Initialization
8.11.2
Object Libraries and Run-Time Support
8.11.3
Setting the Size of the Stack and Heap Sections
8.11.4
Initializing and AutoInitialzing Variables at Run Time
8.11.5
Initialization of Cinit and Watchdog Timer Hold
8.12
Linker Example
Example 31. Linker Command File, demo.cmd
Example 32. Output Map File, demo.map
9
Absolute Lister Description
9.1
Producing an Absolute Listing
9.2
Invoking the Absolute Lister
9.3
Absolute Lister Example
Example 1. module1.lst
Example 2. module2.lst
10
Cross-Reference Lister Description
10.1
Producing a Cross-Reference Listing
10.2
Invoking the Cross-Reference Lister
10.3
Cross-Reference Listing Example
Example 1. Cross-Reference Listing
11
Object File Utilities
11.1
Invoking the Object File Display Utility
11.2
Invoking the Disassembler
Example 1. Object File memcpy32.asm
Example 2. Disassembly From memcpy32.asm
Example 3. Partial Copy Record Output With Different Load and Run Address
11.3
Invoking the Name Utility
11.4
Invoking the Strip Utility
12
Hex Conversion Utility Description
12.1
The Hex Conversion Utility's Role in the Software Development Flow
12.2
Invoking the Hex Conversion Utility
12.2.1
Invoking the Hex Conversion Utility From the Command Line
12.2.2
Invoking the Hex Conversion Utility With a Command File
12.3
Understanding Memory Widths
12.3.1
Target Width
12.3.2
Specifying the Memory Width
12.3.3
Partitioning Data Into Output Files
12.4
The ROMS Directive
12.4.1
When to Use the ROMS Directive
12.4.2
An Example of the ROMS Directive
Example 1. A ROMS Directive Example
Example 2. Map File Output From Showing Memory Ranges
12.5
The SECTIONS Directive
12.6
The Load Image Format (--load_image Option)
12.6.1
Load Image Section Formation
12.6.2
Load Image Characteristics
12.7
Excluding a Specified Section
12.8
Assigning Output Filenames
12.9
Image Mode and the --fill Option
12.9.1
Generating a Memory Image
12.9.2
Specifying a Fill Value
12.9.3
Steps to Follow in Using Image Mode
12.10
Array Output Format
12.11
Building a Table for an On-Chip Boot Loader
12.11.1
Description of the Boot Table
12.11.2
The Boot Table Format
12.11.3
How to Build the Boot Table
12.11.3.1
Building the Boot Table
12.11.3.2
Leaving Room for the Boot Table
12.11.4
Booting From a Device Peripheral
12.11.5
Setting the Entry Point for the Boot Table
12.11.6
Using the ARM Boot Loader
Example 3. Sample Command File for Booting From 8-Bit SPI Boot
Example 4. Sample Command File for ARM 16-Bit Parallel Boot GP I/O
12.12
Using Secure Flash Boot on TMS320F2838x Devices
12.13
Controlling the ROM Device Address
12.14
Control Hex Conversion Utility Diagnostics
12.15
Description of the Object Formats
12.15.1
ASCII-Hex Object Format (--ascii Option)
12.15.2
Intel MCS-86 Object Format (--intel Option)
12.15.3
Motorola Exorciser Object Format (--motorola Option)
12.15.4
Extended Tektronix Object Format (--tektronix Option)
12.15.5
Texas Instruments SDSMAC (TI-Tagged) Object Format (--ti_tagged Option)
12.15.6
TI-TXT Hex Format (--ti_txt Option)
Example 5. TI-TXT Object Format
13
Sharing C/C++ Header Files With Assembly Source
13.1
Overview of the .cdecls Directive
13.2
Notes on C/C++ Conversions
13.2.1
Comments
13.2.2
Conditional Compilation (#if/#else/#ifdef/etc.)
13.2.3
Pragmas
13.2.4
The #error and #warning Directives
13.2.5
Predefined symbol __ASM_HEADER__
13.2.6
Usage Within C/C++ asm( ) Statements
13.2.7
The #include Directive
13.2.8
Conversion of #define Macros
13.2.9
The #undef Directive
13.2.10
Enumerations
13.2.11
C Strings
13.2.12
C/C++ Built-In Functions
13.2.13
Structures and Unions
13.2.14
Function/Variable Prototypes
13.2.15
C Constant Suffixes
13.2.16
Basic C/C++ Types
13.3
Notes on C++ Specific Conversions
13.3.1
Name Mangling
13.3.2
Derived Classes
13.3.3
Templates
13.3.4
Virtual Functions
13.4
Special Assembler Support
13.4.1
Enumerations (.enum/.emember/.endenum)
13.4.2
The .define Directive
13.4.3
The .undefine/.unasg Directives
13.4.4
The $$defined( ) Built-In Function
13.4.5
The $$sizeof Built-In Function
13.4.6
Structure/Union Alignment and $$alignof( )
13.4.7
The .cstring Directive
A Symbolic Debugging Directives
A.1 DWARF Debugging Format
A.2 Debug Directive Syntax
B XML Link Information File Description
B.1 XML Information File Element Types
B.2 Document Elements
B.2.1 Header Elements
Example 1. Header Element for the hi.out Output File
B.2.2 Input File List
Example 2. Input File List for the hi.out Output File
B.2.3 Object Component List
Example 3. Object Component List for the fl-4 Input File
B.2.4 Logical Group List
Example 4. Logical Group List for the fl-4 Input File
B.2.5 Placement Map
Example 5. Placement Map for the fl-4 Input File
B.2.6 Far Call Trampoline List
Example 6. Fall Call Trampoline List for the fl-4 Input File
B.2.7 Symbol Table
Example 7. Symbol Table for the fl-4 Input File
C Hex Conversion Utility Examples
C.1 Scenario 1 -- Building a Hex Conversion Command File for a Single 8-Bit EPROM
Example 1. Linker Command File and Link Map for Scenario 1
Example 2. Hex Conversion Command File for Scenario 1
Example 3. Contents of Hex Map File example1.mxp
C.2 Scenario 2 -- Building a Hex Conversion Command File for 16-BIS Code
Example 4. Linker Command File for Scenario 2
Example 5. Hex Conversion Command File for Scenario 2
Example 6. Contents of Hex Map File example2.mxp
C.3 Scenario 3 -- Building a Hex Conversion Command File for Two 8-Bit EPROMs
Example 7. Linker Command File for Scenario 3
Example 8. Hex Conversion Command File for Scenario 3
Example 9. Contents of Hex Map File example3.mxp
D Glossary
D.1 Terminology
E Revision History
E.1 Recent Revisions
E
Revision History