SPNU118Y September   1995  – February 2020

 

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

Terminology

    ABI

    Application binary interface.

    absolute address

    An address that is permanently assigned to a ARM memory location.

    absolute constant expression

    An expression that does not refer to any external symbols or any registers or memory reference. The value of the expression must be knowable at assembly time.

    absolute lister

    A debugging tool that allows you to create assembler listings that contain absolute addresses.

    address constant expression

    A symbol with a value that is an address plus an addend that is an absolute constant expression with an integer value.

    alignment

    A process in which the linker places an output section at an address that falls on an n-byte boundary, where n is a power of 2. You can specify alignment with the SECTIONS linker directive.

    allocation

    A process in which the linker calculates the final memory addresses of output sections.

    ANSI

    American National Standards Institute; an organization that establishes standards voluntarily followed by industries.

    archive library

    A collection of individual files grouped into a single file by the archiver.

    archiver

    A software program that collects several individual files into a single file called an archive library. With the archiver, you can add, delete, extract, or replace members of the archive library.

    ASCII

    American Standard Code for Information Interchange; a standard computer code for representing and exchanging alphanumeric information.

    assembler

    A software program that creates a machine-language program from a source file that contains assembly language instructions, directives, and macro definitions. The assembler substitutes absolute operation codes for symbolic operation codes and absolute or relocatable addresses for symbolic addresses.

    assembly-time constant

    A symbol that is assigned a constant value with the .set directive.

    big endian

    An addressing protocol in which bytes are numbered from left to right within a word. More significant bytes in a word have lower numbered addresses. Endian ordering is hardware-specific and is determined at reset. See also little endian

    binding

    A process in which you specify a distinct address for an output section or a symbol.

    BIS

    Bit instruction set.

    block

    A set of statements that are grouped together within braces and treated as an entity.

    .bss section

    One of the default object file sections. You use the assembler .bss directive to reserve a specified amount of space in the memory map that you can use later for storing data. The .bss section is uninitialized.

    byte

    Per ANSI/ISO C, the smallest addressable unit that can hold a character.

    C/C++ compiler

    A software program that translates C source statements into assembly language source statements.

    command file

    A file that contains options, filenames, directives, or commands for the linker or hex conversion utility.

    comment

    A source statement (or portion of a source statement) that documents or improves readability of a source file. Comments are not compiled, assembled, or linked; they have no effect on the object file.

    compiler program

    A utility that lets you compile, assemble, and optionally link in one step. The compiler runs one or more source modules through the compiler (including the parser, optimizer, and code generator), the assembler, and the linker.

    conditional processing

    A method of processing one block of source code or an alternate block of source code, according to the evaluation of a specified expression.

    configured memory

    Memory that the linker has specified for allocation.

    constant

    A type whose value cannot change.

    constant expression

    An expression that does not in any way refer to a register or memory reference.

    cross-reference lister

    A utility that produces an output file that lists the symbols that were defined, what file they were defined in, what reference type they are, what line they were defined on, which lines referenced them, and their assembler and linker final values. The cross-reference lister uses linked object files as input.

    cross-reference listing

    An output file created by the assembler that lists the symbols that were defined, what line they were defined on, which lines referenced them, and their final values.

    .data section

    One of the default object file sections. The .data section is an initialized section that contains initialized data. You can use the .data directive to assemble code into the .data section.

    directives

    Special-purpose commands that control the actions and functions of a software tool (as opposed to assembly language instructions, which control the actions of a device).

    DWARF

    A standardized debugging data format that was originally designed along with ELF, although it is independent of the object file format.

    EABI

    An embedded application binary interface (ABI) that provides standards for file formats, data types, and more.

    ELF

    Executable and linking format; a system of object files configured according to the System V Application Binary Interface specification.

    emulator

    A hardware development system that duplicates the ARM operation.

    entry point

    A point in target memory where execution starts.

    environment variable

    A system symbol that you define and assign to a string. Environmental variables are often included in Windows batch files or UNIX shell scripts such as .cshrc or .profile.

    epilog

    The portion of code in a function that restores the stack and returns.

    executable module

    A linked object file that can be executed in a target system.

    expression

    A constant, a symbol, or a series of constants and symbols separated by arithmetic operators.

    external symbol

    A symbol that is used in the current program module but defined or declared in a different program module.

    field

    For the ARM, a software-configurable data type whose length can be programmed to be any value in the range of 1-32 bits.

    global symbol

    A symbol that is either defined in the current module and accessed in another, or accessed in the current module but defined in another.

    GROUP

    An option of the SECTIONS directive that forces specified output sections to be allocated contiguously (as a group).

    hex conversion utility

    A utility that converts object files into one of several standard ASCII hexadecimal formats, suitable for loading into an EPROM programmer.

    high-level language debugging

    The ability of a compiler to retain symbolic and high-level language information (such as type and function definitions) so that a debugging tool can use this information.

    hole

    An area between the input sections that compose an output section that contains no code.

    identifier

    Names used as labels, registers, and symbols.

    immediate operand

    An operand whose value must be a constant expression.

    incremental linking

    Linking files in several passes. Incremental linking is useful for large applications, because you can partition the application, link the parts separately, and then link all of the parts together.

    initialization at load time

    An autoinitialization method used by the linker when linking C/C++ code. The linker uses this method when you invoke it with the --ram_model link option. This method initializes variables at load time instead of run time.

    initialized section

    A section from an object file that will be linked into an executable module.

    input section

    A section from an object file that will be linked into an executable module.

    ISO

    International Organization for Standardization; a worldwide federation of national standards bodies, which establishes international standards voluntarily followed by industries.

    label

    A symbol that begins in column 1 of an assembler source statement and corresponds to the address of that statement. A label is the only assembler statement that can begin in column 1.

    linker

    A software program that combines object files to form an object module that can be allocated into system memory and executed by the device.

    listing file

    An output file, created by the assembler, that lists source statements, their line numbers, and their effects on the section program counter (SPC).

    literal constant

    A value that represents itself. It may also be called a literal or an immediate value.

    little endian

    An addressing protocol in which bytes are numbered from right to left within a word. More significant bytes in a word have higher numbered addresses. Endian ordering is hardware-specific and is determined at reset. See also big endian

    loader

    A device that places an executable module into system memory.

    macro

    A user-defined routine that can be used as an instruction.

    macro call

    The process of invoking a macro.

    macro definition

    A block of source statements that define the name and the code that make up a macro.

    macro expansion

    The process of inserting source statements into your code in place of a macro call.

    macro library

    An archive library composed of macros. Each file in the library must contain one macro; its name must be the same as the macro name it defines, and it must have an extension of .asm.

    map file

    An output file, created by the linker, that shows the memory configuration, section composition, section allocation, symbol definitions and the addresses at which the symbols were defined for your program.

    member

    The elements or variables of a structure, union, archive, or enumeration.

    memory map

    A map of target system memory space that is partitioned into functional blocks.

    memory reference operand

    An operand that refers to a location in memory using a target-specific syntax.

    mnemonic

    An instruction name that the assembler translates into machine code.

    model statement

    Instructions or assembler directives in a macro definition that are assembled each time a macro is invoked.

    named section

    An initialized section that is defined with a .sect directive.

    object file

    An assembled or linked file that contains machine-language object code.

    object library

    An archive library made up of individual object files.

    object module

    A linked, executable object file that can be downloaded and executed on a target system.

    operand

    An argument of an assembly language instruction, assembler directive, or macro directive that supplies information to the operation performed by the instruction or directive.

    optimizer

    A software tool that improves the execution speed and reduces the size of C programs.

    options

    Command-line parameters that allow you to request additional or specific functions when you invoke a software tool.

    output module

    A linked, executable object file that is downloaded and executed on a target system.

    output section

    A final, allocated section in a linked, executable module.

    partial linking

    Linking files in several passes. Incremental linking is useful for large applications because you can partition the application, link the parts separately, and then link all of the parts together.

    quiet run

    An option that suppresses the normal banner and the progress information.

    raw data

    Executable code or initialized data in an output section.

    register operand

    A special pre-defined symbol that represents a CPU register.

    relocatable constant expression

    An expression that refers to at least one external symbol, register, or memory location. The value of the expression is not known until link time.

    relocation

    A process in which the linker adjusts all the references to a symbol when the symbol's address changes.

    ROM width

    The width (in bits) of each output file, or, more specifically, the width of a single data value in the hex conversion utility file. The ROM width determines how the utility partitions the data into output files. After the target words are mapped to memory words, the memory words are broken into one or more output files. The number of output files is determined by the ROM width.

    run address

    The address where a section runs.

    run-time-support library

    A library file, rts.src, that contains the source for the run time-support functions.

    section

    A relocatable block of code or data that ultimately will be contiguous with other sections in the memory map.

    section program counter (SPC)

    An element that keeps track of the current location within a section; each section has its own SPC.

    sign extend

    A process that fills the unused MSBs of a value with the value's sign bit.

    simulator

    A software development system that simulates ARM operation.

    source file

    A file that contains C/C++ code or assembly language code that is compiled or assembled to form an object file.

    static variable

    A variable whose scope is confined to a function or a program. The values of static variables are not discarded when the function or program is exited; their previous value is resumed when the function or program is reentered.

    storage class

    An entry in the symbol table that indicates how to access a symbol.

    string table

    A table that stores symbol names that are longer than eight characters (symbol names of eight characters or longer cannot be stored in the symbol table; instead they are stored in the string table). The name portion of the symbol's entry points to the location of the string in the string table.

    structure

    A collection of one or more variables grouped together under a single name.

    subsection

    A relocatable block of code or data that ultimately will occupy continuous space in the memory map. Subsections are smaller sections within larger sections. Subsections give you tighter control of the memory map.

    symbol

    A name that represents an address or a value.

    symbolic constant

    A symbol with a value that is an absolute constant expression.

    symbolic debugging

    The ability of a software tool to retain symbolic information that can be used by a debugging tool such as an emulator or simulator.

    tag

    An optional type name that can be assigned to a structure, union, or enumeration.

    target memory

    Physical memory in a system into which executable object code is loaded.

    .text section

    One of the default object file sections. The .text section is initialized and contains executable code. You can use the .text directive to assemble code into the .text section.

    unconfigured memory

    Memory that is not defined as part of the memory map and cannot be loaded with code or data.

    uninitialized section

    A object file section that reserves space in the memory map but that has no actual contents. These sections are built with the .bss and .usect directives.

    UNION

    An option of the SECTIONS directive that causes the linker to allocate the same address to multiple sections.

    union

    A variable that can hold objects of different types and sizes.

    unsigned value

    A value that is treated as a nonnegative number, regardless of its actual sign.

    variable

    A symbol representing a quantity that can assume any of a set of values.

    veneer

    A sequence of instructions that serves as an alternate entry point into a routine if a state change is required.

    well-defined expression

    A term or group of terms that contains only symbols or assembly-time constants that have been defined before they appear in the expression.

    word

    A 32-bit addressable location in target memory