SPNU118Z September   1995  – March 2023 66AK2E05 , 66AK2H06 , 66AK2H12 , 66AK2H14 , AM1705 , AM1707 , AM1802 , AM1806 , AM1808 , AM1810 , AM5K2E04 , OMAP-L132 , OMAP-L137 , OMAP-L138 , SM470R1B1M-HT , TMS470R1A288 , TMS470R1A384 , TMS470R1A64 , TMS470R1B1M , TMS470R1B512 , TMS470R1B768

 

  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. 1 Introduction to the Software Development Tools
    1. 1.1 Software Development Tools Overview
    2. 1.2 Tools Descriptions
  3. 2 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
    8. 2.8 Loading a Program
  4. 3 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. 3.1.2.5.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. 4 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. 4.8.3.1 Local Labels of the Form $n
        2.       85
        3.       86
      4. 4.8.4 Symbolic Constants
      5. 4.8.5 Defining Symbolic Constants (--asm_define Option)
      6. 4.8.6 Predefined Symbolic Constants
      7. 4.8.7 Registers
      8. 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
    14. 4.14 Cross-Reference Listings
  6. 5 Assembler Directives
    1. 5.1  Directives Summary
    2. 5.2  Directives that Define Sections
    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
      1.      .align
      2.      .asg/.define/.eval
      3.      .asmfunc/.endasmfunc
      4.      .bits
      5.      .bss
      6.      .byte/.ubyte/.char/.uchar
      7.      .cdecls
      8.      .common
      9.      .copy/.include
      10.      .cstruct/.cunion/.endstruct/.endunion/.tag
      11.      .data
      12.      .double
      13.      .drlist/.drnolist
      14.      .elfsym
      15.      .emsg/.mmsg/.wmsg
      16.      .end
      17.      .fclist/.fcnolist
      18.      .field
      19.      .float
      20.      .global/.def/.ref
      21.      .group/.gmember/.endgroup
      22.      .half/.short/.uhalf/.ushort
      23.      .if/.elseif/.else/.endif
      24.      .int/.unint/.long/.ulong/.word/.uword
      25.      .label
      26.      .length/.width
      27.      .list/.nolist
      28.      .loop/.endloop/.break
      29.      .macro/.endm
      30.      .mlib
      31.      .mlist/.mnolist
      32.      .newblock
      33.      .option
      34.      .page
      35.      .retain / .retainrefs
      36.      .sect
      37.      .set/.equ
      38.      .space/.bes
      39.      .sslist/.ssnolist
      40.      .state16
      41.      .state32/.arm
      42.      .string/.cstring
      43.      .struct/.endstruct/.tag
      44.      .symdepend
      45.      .tab
      46.      .text
      47.      .thumb
      48.      .title
      49.      .unasg/.undefine
      50.      .union/.endunion/.tag
      51.      .usect
      52.      .var
      53.      .weak
  7. 6 Macro Language Description
    1. 6.1  Using Macros
    2. 6.2  Defining Macros
    3. 6.3  Macro Parameters/Substitution Symbols
      1. 6.3.1 Directives That Define Substitution Symbols
      2. 6.3.2 Built-In Substitution Symbol Functions
      3. 6.3.3 Recursive Substitution Symbols
      4. 6.3.4 Forced Substitution
      5. 6.3.5 Accessing Individual Characters of Subscripted Substitution Symbols
      6. 6.3.6 Substitution Symbols as Local Variables in Macros
    4. 6.4  Macro Libraries
    5. 6.5  Using Conditional Assembly in Macros
    6. 6.6  Using Labels in Macros
    7. 6.7  Producing Messages in Macros
    8. 6.8  Using Directives to Format the Output Listing
    9. 6.9  Using Recursive and Nested Macros
    10. 6.10 Macro Directives Summary
  8. 7 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
    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. 8 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)
      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 Mapping of Symbols (--symbol_map Option)
      33. 8.4.33 Generate Far Call Trampolines (--trampolines Option)
        1. 8.4.33.1 Advantages and Disadvantages of Using Trampolines
        2. 8.4.33.2 Minimizing the Number of Trampolines Required (--minimize_trampolines Option)
        3. 8.4.33.3 Making Trampoline Reservations Adjacent (--trampoline_min_spacing Option)
        4. 8.4.33.4 Carrying Trampolines From Load Space to Run Space
      34. 8.4.34 Introduce an Unresolved Symbol (--undef_sym Option)
      35. 8.4.35 Display a Message When an Undefined Output Section Is Created (--warn_sections)
      36. 8.4.36 Generate XML Link Information File (--xml_link_info Option)
      37. 8.4.37 Zero Initialization (--zero_init Option)
    5. 8.5  Linker Command Files
      1. 8.5.1  Reserved Names in Linker Command Files
      2. 8.5.2  Constants in Linker Command Files
      3. 8.5.3  Accessing Files and Libraries from a Linker Command File
      4. 8.5.4  The MEMORY Directive
        1. 8.5.4.1 Default Memory Model
        2. 8.5.4.2 MEMORY Directive Syntax
        3. 8.5.4.3 Expressions and Address Operators
        4. 8.5.4.4 The ALIAS Statement
      5. 8.5.5  The SECTIONS Directive
        1. 8.5.5.1 SECTIONS Directive Syntax
        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. 8.5.5.2.4.1 Linker Placement With the HIGH Specifier
            2.         267
            3. 8.5.5.2.4.2 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. 8.5.5.3.1 The Most Common Method of Specifying Section Contents
          2.        273
        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. 8.5.5.5.1 Archive Members to Output Sections
          2.        277
        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
      6. 8.5.6  Placing a Section at Different Load and Run Addresses
        1. 8.5.6.1 Specifying Load and Run Addresses
        2.       282
        3. 8.5.6.2 Referring to the Load Address by Using the .label Directive
      7. 8.5.7  Using GROUP and UNION Statements
        1. 8.5.7.1 Grouping Output Sections Together
        2. 8.5.7.2 Overlaying Sections With the UNION Statement
        3. 8.5.7.3 Using Memory for Multiple Purposes
        4. 8.5.7.4 Nesting UNIONs and GROUPs
        5. 8.5.7.5 Checking the Consistency of Allocators
        6. 8.5.7.6 Naming UNIONs and GROUPs
      8. 8.5.8  Special Section Types (DSECT, COPY, NOLOAD, and NOINIT)
      9. 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
      10. 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
      11. 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 Linker-Defined Functions and Arrays
      2. 8.6.2 Linker-Defined Integer Values
      3. 8.6.3 Linker-Defined Addresses
      4. 8.6.4 More About the _symval Operator
      5. 8.6.5 Weak Symbols
        1. 8.6.5.1 Weak Symbol References
        2. 8.6.5.2 Weak Symbol Definitions
      6. 8.6.6 Resolving Symbols with Object Libraries
    7. 8.7  Default Placement Algorithm
      1. 8.7.1 How the Allocation Algorithm Creates Output Sections
      2. 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
      4. 8.8.4 Generating Copy Tables With the table() Operator
        1. 8.8.4.1 The table() Operator
        2. 8.8.4.2 Boot-Time Copy Tables
        3. 8.8.4.3 Using the table() Operator to Manage Object Components
        4. 8.8.4.4 Linker-Generated Copy Table Sections and Symbols
        5. 8.8.4.5 Splitting Object Components and Overlay Management
      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.       342
      6. 8.8.6 Copy Table Contents
      7. 8.8.7 General Purpose Copy Routine
    9. 8.9  Linker-Generated CRC Tables
      1. 8.9.1 Using the crc_table() Operator in the SECTIONS Directive
        1. 8.9.1.1 Restrictions when using the crc_table() Operator
        2. 8.9.1.2 Examples
          1. 8.9.1.2.1 Using crc_table() Operator to Compute the CRC Value for .text Data
          2.        350
          3. 8.9.1.2.2 Specifying an Algorithm in the crc_table() Operator
          4.        352
          5. 8.9.1.2.3 Using a Single Table for Multiple Sections
          6.        354
          7. 8.9.1.2.4 Applying the crc_table() Operator to a GROUP or UNION
          8.        356
        3. 8.9.1.3 Interface When Using the crc_table() Operator
          1. 8.9.1.3.1 The CRC Table Header, crc_tbl.h
          2. 8.9.1.3.2 General Purpose CRC Check Routine
      2. 8.9.2 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
  10. 9 Absolute Lister Description
    1. 9.1 Producing an Absolute Listing
    2. 9.2 Invoking the Absolute Lister
    3. 9.3 Absolute Lister Example
  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
  12. 11Object File Utilities
    1. 11.1 Invoking the Object File Display Utility
    2. 11.2 Invoking the Disassembler
      1. 11.2.1 Object File memcpy32.asm
      2.      381
      3. 11.2.2 Disassembly From memcpy32.asm
      4.      383
      5. 11.2.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
    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. 12.11.6.1 Sample Command File for Booting From 8-Bit SPI Boot
        2.       420
        3. 12.11.6.2 Sample Command File for ARM 16-Bit Parallel Boot GP I/O
        4.       422
    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. 12.15.6.1 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
      2.      B.2.2 Input File List
      3.      B.2.3 Object Component List
      4.      B.2.4 Logical Group List
      5.      B.2.5 Placement Map
      6.      B.2.6 Far Call Trampoline List
      7.      B.2.7 Symbol Table
  17.   C Hex Conversion Utility Examples
    1.     C.1 Scenario 1 -- Building a Hex Conversion Command File for a Single 8-Bit EPROM
      1.      C.1.1 Linker Command File and Link Map for Scenario 1
      2.      482
      3.      C.1.2 Hex Conversion Command File for Scenario 1
      4.      484
      5.      C.1.3 Contents of Hex Map File example1.mxp
    2.     C.2 Scenario 2 -- Building a Hex Conversion Command File for 16-BIS Code
      1.      C.2.1 Linker Command File for Scenario 2
      2.      488
      3.      C.2.2 Hex Conversion Command File for Scenario 2
      4.      490
      5.      C.2.3 Contents of Hex Map File example2.mxp
    3.     C.3 Scenario 3 -- Building a Hex Conversion Command File for Two 8-Bit EPROMs
      1.      C.3.1 Linker Command File for Scenario 3
      2.      494
      3.      C.3.2 Hex Conversion Command File for Scenario 3
      4.      496
      5.      C.3.3 Contents of Hex Map File example3.mxp
      6.      498
  18.   D Glossary
    1.     D.1 Terminology
  19.   E Revision History
  20.   E Earlier Revisions

5.1 Directives Summary

Table 5-1 through Table 5-17 summarize the assembler directives. In addition to the directives documented here, the ARM device software tools support the following directives:

  • Macro directives are discussed in Chapter 177; they are not discussed in this chapter.
  • The C compiler uses directives for symbolic debugging. Unlike other directives, symbolic debugging directives are not used in most assembly language programs. Appendix A discusses these directives; they are not discussed in this chapter.
Note: Labels and Comments Are Not Shown in Syntaxes: Most source statements that contain a directive can also contain a label and a comment. Labels begin in the first column (only labels and comments can appear in the first column), and comments must be preceded by a semicolon, or an asterisk if the comment is the only element in the line. To improve readability, labels and comments are not shown as part of the directive syntax here. See the detailed description of each directive for using labels with directives.
Table 5-1 Directives that Control Section Use
Mnemonic and Syntax Description See
.bss symbol, size in bytes[, alignment
[, bank offset]] 		Reserves size bytes in the .bss (uninitialized data) section .bss topic
.data Assembles into the .data (initialized data) section .data topic
.sect "section name" Assembles into a named (initialized) section .sect topic
.text Assembles into the .text (executable code) section .text topic
symbol .usect "section name", size in bytes
[, alignment[, bank offset]] 		Reserves size bytes in a named (uninitialized) section .usect topic
Table 5-2 Directives that Gather Sections into Common Groups
Mnemonic and Syntax Description See
.endgroup Ends the group declaration. .endgroup topic
.gmember section name Designates section name as a member of the group. .gmember topic
.group group section name group type : Begins a group declaration. .group topic
Table 5-3 Directives that Affect Unused Section Elimination
Mnemonic and Syntax Description See
.retain "section name" Instructs the linker to include the current or specified section in the linked output file, regardless of whether the section is referenced or not .retain topic
.retainrefs "section name" Instructs the linker to include any data object that references the current or specified section. .retain topic
Table 5-4 Directives that Initialize Values (Data and Memory)
Mnemonic and Syntax Description See
.bits value1[, ... , valuen] Initializes one or more successive bits in the current section .bits topic
.byte value1[, ... , valuen] Initializes one or more successive bytes in the current section .byte topic
.char value1[, ... , valuen] Initializes one or more successive bytes in the current section .char topic
.cstring {expr1|"string1"}[,... , {exprn|"stringn"}] Initializes one or more text strings .string topic
.double value1[, ... , valuen] Initializes one or more 64-bit, IEEE double-precision, floating-point constants .double topic
.field value[, size] Initializes a field of size bits (1-32) with value .field topic
.float value1[, ... , valuen] Initializes one or more 32-bit, IEEE single-precision, floating-point constants .float topic
.half value1[, ... , valuen] Initializes one or more 16-bit integers (halfword) .half topic
.int value1[, ... , valuen] Initializes one or more 32-bit integers .int topic
.long value1[, ... , valuen] Initializes one or more 32-bit integers .long topic
.short value1[, ... , valuen] Initializes one or more 16-bit integers (halfword) .short topic
.string {expr1|"string1"}[,... , {exprn|"stringn"}] Initializes one or more text strings .string topic
.ubyte value1[, ... , valuen] Initializes one or more successive unsigned bytes in current section .ubyte topic
.uchar value1[, ... , valuen] Initializes one or more successive unsigned bytes in current section .uchar topic
.uhalf value1[, ... , valuen] Initializes one or more unsigned 16-bit integers (halfword) .uhalf topic
.uint value1[, ... , valuen] Initializes one or more unsigned 32-bit integers .uint topic
.ulong value1[, ... , valuen] Initializes one or more unsigned 32-bit integers .long topic
.ushort value1[, ... , valuen] Initializes one or more unsigned 16-bit integers (halfword) .short topic
.uword value1[, ... , valuen] Initializes one or more unsigned 32-bit integers .uword topic
.word value1[, ... , valuen] Initializes one or more 32-bit integers .word topic
Table 5-5 Directives that Perform Alignment and Reserve Space
Mnemonic and Syntax Description See
.align [size in bytes ] Aligns the SPC on a boundary specified by size in bytes , which must be a power of 2; defaults to byte boundary .align topic
.bes size Reserves size bytes in the current section; a label points to the end of the reserved space .bes topic
.space size Reserves size bytes in the current section; a label points to the beginning of the reserved space .space topic
Table 5-6 Directives that Change the Instruction Type
Mnemonic and Syntax Description See
.arm Begins assembling ARM UAL instructions. Equivalent to .state32. .arm topic
.state16 Begins assembling non-UAL 16-bit instructions .state16 topic
.state32 Begins assembling 32-bit instructions (default) .state32 topic
.thumb Begins assembling Thumb or Thumb-2 UAL instructions .thumb topic
Table 5-7 Directives that Format the Output Listing
Mnemonic and Syntax Description See
.drlist Enables listing of all directive lines (default) .drlist topic
.drnolist Suppresses listing of certain directive lines .drnolist topic
.fclist Allows false conditional code block listing (default) .fclist topic
.fcnolist Suppresses false conditional code block listing .fcnolist topic
.length [page length] Sets the page length of the source listing .length topic
.list Restarts the source listing .list topic
.mlist Allows macro listings and loop blocks (default) .mlist topic
.mnolist Suppresses macro listings and loop blocks .mnolist topic
.nolist Stops the source listing .nolist topic
.option option1[, option2 , . . .] Selects output listing options; available options are A, B, H, M, N, O, R, T, W, and X .option topic
.page Ejects a page in the source listing .page topic
.sslist Allows expanded substitution symbol listing .sslist topic
.ssnolist Suppresses expanded substitution symbol listing (default) .ssnolist topic
.tab size Sets tab to size characters .tab topic
.title "string" Prints a title in the listing page heading .title topic
.width [page width] Sets the page width of the source listing .width topic
Table 5-8 Directives that Reference Other Files
Mnemonic and Syntax Description See
.copy ["]filename["] Includes source statements from another file .copy topic
.include ["]filename["] Includes source statements from another file .include topic
.mlib ["]filename["] Specifies a macro library from which to retrieve macro definitions .mlib topic
Table 5-9 Directives that Affect Symbol Linkage and Visibility
Mnemonic and Syntax Description See
.common symbol, size in bytes [, alignment]
.common symbol, structure tag [, alignment]		 Defines a common symbol for a variable. .common topic
.def symbol1[, ... , symboln] Identifies one or more symbols that are defined in the current module and that can be used in other modules. .def topic
.global symbol1[, ... , symboln] Identifies one or more global (external) symbols. .global topic
.ref symbol1[, ... , symboln] Identifies one or more symbols used in the current module that are defined in another module. .ref topic
.symdepend dst symbol name[, src symbol name] Creates an artificial reference from a section to a symbol. .symdepend topic
.weak symbol name Identifies a symbol used in the current module that is defined in another module. .weak topic
Table 5-10 Directives that Define Symbols
Mnemonic and Syntax Description See
.asg ["]character string["], substitution symbol Assigns a character string to substitution symbol. Substitution symbols created with .asg can be redefined. .asg topic
.define ["]character string["], substitution symbol Assigns a character string to substitution symbol. Substitution symbols created with .define cannot be redefined. .asg topic
symbol .equ value Equates value with symbol .equ topic
.elfsym name, SYM_SIZE(size) Provides ELF symbol information .elfsym topic
.eval expression,
substitution symbol		 Performs arithmetic on a numeric substitution symbol .eval topic
.label symbol Defines a load-time relocatable label in a section .label topic
.newblock Undefines local labels .newblock topic
symbol .set value Equates value with symbol .set topic
.unasg symbol Turns off assignment of symbol as a substitution symbol .unasg topic
.undefine symbol Turns off assignment of symbol as a substitution symbol .unasg topic
Table 5-11 Directives that Enable Conditional Assembly
Mnemonic and Syntax Description See
.if condition Assembles code block if the condition is true .if topic
.else Assembles code block if the .if condition is false. When using the .if construct, the .else construct is optional. .else topic
.elseif condition Assembles code block if the .if condition is false and the .elseif condition is true. When using the .if construct, the .elseif construct is optional. .elseif topic
.endif Ends .if code block .endif topic
.loop [count] Begins repeatable assembly of a code block; the loop count is determined by the count. .loop topic
.break [end condition] Ends .loop assembly if end condition is true. When using the .loop construct, the .break construct is optional. .break topic
.endloop Ends .loop code block .endloop topic
Table 5-12 Directives that Define Union or Structure Types
Mnemonic and Syntax Description See
.cstruct Acts like .struct, but adds padding and alignment like that which is done to C structures .cstruct topic
.cunion Acts like .union, but adds padding and alignment like that which is done to C unions .cunion topic
.emember Sets up C-like enumerated types in assembly code  Section 5.10
.endenum Sets up C-like enumerated types in assembly code  Section 5.10
.endstruct Ends a structure definition .cstruct topic, .struct topic
.endunion Ends a union definition .cunion topic, .union topic
.enum Sets up C-like enumerated types in assembly code Section 5.10
.union Begins a union definition .union topic
.struct Begins structure definition .struct topic
.tag Assigns structure attributes to a label .cstruct topic, .struct topic.union topic
Table 5-13 Directives that Create or Affect Macros
Mnemonic and Syntax Description See
macname .macro [parameter1][,... , parametern ] Begin definition of macro named macname .macro topic
.endm End macro definition .endm topic
.mexit Go to .endm Section 6.2
.mlib filename Identify library containing macro definitions .mlib topic
.var Adds a local substitution symbol to a macro's parameter list .var topic
Table 5-14 Directives that Control Diagnostics
Mnemonic and Syntax Description See
.emsg string Sends user-defined error messages to the output device; produces no .obj file .emsg topic
.mmsg string Sends user-defined messages to the output device .mmsg topic
.wmsg string Sends user-defined warning messages to the output device .wmsg topic
Table 5-15 Directives that Perform Assembly Source Debug
Mnemonic and Syntax Description See
.asmfunc Identifies the beginning of a block of code that contains a function .asmfunc topic
.endasmfunc Identifies the end of a block of code that contains a function .endasmfunc topic
Table 5-16 Directives that Are Used by the Absolute Lister
Mnemonic and Syntax Description See
.setsect Produced by absolute lister; sets a section Chapter 378
.setsym Produced by the absolute lister; sets a symbol Chapter 378
Table 5-17 Directives that Perform Miscellaneous Functions
Mnemonic and Syntax Description See
.cdecls [options,]"filename"[, "filename2"[, ...] Share C headers between C and assembly code .cdecls topic
.end Ends program .end topic

In addition to the assembly directives that you can use in your code, the C/C++ compiler produces several directives when it creates assembly code. These directives are to be used only by the compiler; do not attempt to use these directives:

  • DWARF directives listed in Section A.1
  • The .battr directive is used to encode build attributes for the object file.
  • The .bound directive is used internally.
  • The .comdat directive is used internally.
  • The .compiler_opts directive indicates that the assembly code was produced by the compiler, and which build model options were used for this file.