SPRU513Z August   2001  – October 2023 SM320F28335-EP

 

  1.   1
  2.   Read This First
    1.     About This Manual
    2.     How to Use This Manual
    3.     Notational Conventions
    4.     Related Documentation From Texas Instruments
    5.     Trademarks
  3. 1 Introduction to the Software Development Tools
    1. 1.1 Software Development Tools Overview
    2. 1.2 Tools Descriptions
  4. 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
      1. 2.7.1 Expressions With Multiple Relocatable Symbols (COFF Only)
    8. 2.8 Loading a Program
  5. 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
  6. 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 C2000_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
      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. 4.8.3.2 Local Labels of the Form name?
        4.       87
      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 Legal Expressions
    10. 4.10 Built-in Functions and Operators
      1. 4.10.1 Built-In Math and Trigonometric Functions
    11. 4.11 TMS320C28x Assembler Extensions
      1. 4.11.1 C28x Support
      2. 4.11.2 C28x FPU32 and FPU64 Extensions
      3. 4.11.3 C28x CLA Extensions
    12. 4.12 Source Listings
    13. 4.13 Debugging Assembly Source
    14. 4.14 Cross-Reference Listings
    15. 4.15 Smart Encoding
    16. 4.16 Pipeline Conflict Detection
      1. 4.16.1 Protected and Unprotected Pipeline Instructions
      2. 4.16.2 Pipeline Conflict Prevention and Detection
      3. 4.16.3 Pipeline Conflicts Detected
  7. 5 Assembler Directives
    1. 5.1  Directives Summary
    2. 5.2  Directives that Define Sections
    3. 5.3  Directives that Initialize Values
    4. 5.4  Directives that Perform Alignment and Reserve Space
    5. 5.5  Directives that Format the Output Listings
    6. 5.6  Directives that Reference Other Files
    7. 5.7  Directives that Enable Conditional Assembly
    8. 5.8  Directives that Define Union or Structure Types
    9. 5.9  Directives that Define Enumerated Types
    10. 5.10 Directives that Define Symbols at Assembly Time
    11. 5.11 Miscellaneous Directives
    12. 5.12 Directives Reference
      1.      .align
      2.      .asg/.define/.eval
      3.      .asmfunc/.endasmfunc
      4.      .bits
      5.      .bss
      6.      .byte/.ubyte/.char/.uchar
      7.      .cdecls
      8.      .clink
      9.      .common
      10.      .copy/.include
      11.      .cstruct/.cunion/.endstruct/.endunion/.tag
      12.      .data
      13.      .drlist/.drnolist
      14.      .elfsym
      15.      .emsg/.mmsg/.wmsg
      16.      .end
      17.      .fclist/.fcnolist
      18.      .field
      19.      .float/.xfloat/.xldouble
      20.      .global/.def/.ref
      21.      .group/.gmember/.endgroup
      22.      .if/.elseif/.else/.endif
      23.      .int/.unint/.word/.uword
      24.      .label
      25.      .length/.width
      26.      .list/.nolist
      27.      .long/.ulong/.xlong
      28.      .loop/.endloop/.break
      29.      .macro/.endm
      30.      .mlib
      31.      .mlist/.mnolist
      32.      .newblock
      33.      .option
      34.      .page
      35.      .retain / .retainrefs
      36.      .sblock
      37.      .sect
      38.      .set
      39.      .space/.bes
      40.      .sslist/.ssnolist
      41.      .string/.cstring/.pstring
      42.      .struct/.endstruct/.tag
      43.      .symdepend
      44.      .tab
      45.      .text
      46.      .title
      47.      .unasg/.undefine
      48.      .union/.endunion/.tag
      49.      .usect
      50.      .var
      51.      .weak
  8. 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
  9. 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
  10. 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  Compression (--cinit_compression and --copy_compression Option)
      6. 8.4.6  Compress DWARF Information (--compress_dwarf Option)
      7. 8.4.7  Control Linker Diagnostics
      8. 8.4.8  Automatic Library Selection (--disable_auto_rts Option)
      9. 8.4.9  Disable Conditional Linking (--disable_clink 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 Define Heap Size (--heap_size Option)
      16. 8.4.16 Hiding Symbols
      17. 8.4.17 Alter the Library Search Algorithm (--library, --search_path, and C2000_C_DIR )
        1. 8.4.17.1 Name an Alternate Library Directory (--search_path Option)
        2. 8.4.17.2 Name an Alternate Library Directory ( C2000_C_DIR Environment Variable)
        3. 8.4.17.3 Exhaustively Read and Search Libraries (--reread_libs and --priority Options)
      18. 8.4.18 Change Symbol Localization
        1. 8.4.18.1 Make All Global Symbols Static (--make_static Option)
      19. 8.4.19 Create a Map File (--map_file Option)
      20. 8.4.20 Manage Map File Contents (--mapfile_contents Option)
      21. 8.4.21 Disable Name Demangling (--no_demangle)
      22. 8.4.22 Disable Merging of Symbolic Debugging Information (--no_sym_merge Option)
      23. 8.4.23 Strip Symbolic Information (--no_symtable Option)
      24. 8.4.24 Name an Output Module (--output_file Option)
      25. 8.4.25 Prioritizing Function Placement (--preferred_order Option)
      26. 8.4.26 C Language Options (--ram_model and --rom_model Options)
      27. 8.4.27 Retain Discarded Sections (--retain Option)
      28. 8.4.28 Create an Absolute Listing File (--run_abs Option)
      29. 8.4.29 Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)
      30. 8.4.30 Define Stack Size (--stack_size Option)
      31. 8.4.31 Mapping of Symbols (--symbol_map Option)
      32. 8.4.32 Introduce an Unresolved Symbol (--undef_sym Option)
      33. 8.4.33 Display a Message When an Undefined Output Section Is Created (--warn_sections)
      34. 8.4.34 Generate XML Link Information File (--xml_link_info Option)
      35. 8.4.35 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
      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.         265
            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
          7. 8.5.5.2.7 Using the Page Method
        3. 8.5.5.3 Specifying Input Sections
          1. 8.5.5.3.1 The Most Common Method of Specifying Section Contents
          2.        272
        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.        276
        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.       281
        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  Overlaying Pages
        1. 8.5.8.1 Using the MEMORY Directive to Define Overlay Pages
        2. 8.5.8.2 Example of Overlay Pages
          1. 8.5.8.2.1 MEMORY Directive With Overlay Pages
          2.        294
        3. 8.5.8.3 Using Overlay Pages With the SECTIONS Directive
          1. 8.5.8.3.1 SECTIONS Directive Definition for Overlays
          2.        297
        4. 8.5.8.4 Memory Allocation for Overlaid Pages
      9. 8.5.9  Special Section Types (DSECT, COPY, NOLOAD, and NOINIT)
      10. 8.5.10 Configuring Error Correcting Code (ECC) with the Linker
        1. 8.5.10.1 Using the ECC Specifier in the Memory Map
        2. 8.5.10.2 Using the ECC Directive
        3. 8.5.10.3 Using the VFILL Specifier in the Memory Map
      11. 8.5.11 Assigning Symbols at Link Time
        1. 8.5.11.1 Syntax of Assignment Statements
        2. 8.5.11.2 Assigning the SPC to a Symbol
        3. 8.5.11.3 Assignment Expressions
        4. 8.5.11.4 Symbols Automatically Defined by the Linker
        5. 8.5.11.5 Assigning Exact Start, End, and Size Values of a Section to a Symbol
        6. 8.5.11.6 Why the Dot Operator Does Not Always Work
        7. 8.5.11.7 Address and Dimension Operators
          1. 8.5.11.7.1 Input Items
          2. 8.5.11.7.2 Output Section
          3. 8.5.11.7.3 GROUPs
          4. 8.5.11.7.4 UNIONs
        8. 8.5.11.8 LAST Operator
      12. 8.5.12 Creating and Filling Holes
        1. 8.5.12.1 Initialized and Uninitialized Sections
        2. 8.5.12.2 Creating Holes
        3. 8.5.12.3 Filling Holes
        4. 8.5.12.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.       350
      6. 8.8.6 Copy Table Contents
      7. 8.8.7 General Purpose Copy Routine
    9. 8.9  Linker-Generated CRC Tables and CRC Over Memory Ranges
      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.        358
          3. 8.9.1.2.2 Specifying an Algorithm in the crc_table() Operator
          4.        360
          5. 8.9.1.2.3 Using a Single Table for Multiple Sections
          6.        362
          7. 8.9.1.2.4 Applying the crc_table() Operator to a GROUP or UNION
          8.        364
        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.2 Using the crc() Operator in the MEMORY Directive
        1. 8.9.2.1 Restrictions when Using the crc() Operator
        2. 8.9.2.2 Using the VFILL Specifier within a GROUP
        3. 8.9.2.3 Generate CRC for Most or All of Flash Memory
        4. 8.9.2.4 Computing CRCs for Both Memory Ranges and Sections
        5. 8.9.2.5 Example Specifying Memory Range CRCs
        6. 8.9.2.6 Interface When Using the crc() Operator
      3. 8.9.3 A Special Note Regarding 16-Bit char
    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
    12. 8.12 Linker Example
  11. 9 Absolute Lister Description
    1. 9.1 Producing an Absolute Listing
    2. 9.2 Invoking the Absolute Lister
    3. 9.3 Absolute Lister Example
  12. 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
  13. 11Object File Utilities
    1. 11.1 Invoking the Object File Display Utility
    2. 11.2 Invoking the Disassembler
    3. 11.3 Invoking the Name Utility
    4. 11.4 Invoking the Strip Utility
  14. 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.3.4 Specifying Word Order for Output Words
    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 C28x Boot Loader
        1. 12.11.6.1 Sample Command File for Booting From 8-Bit SPI Boot
        2.       429
        3. 12.11.6.2 Sample Command File for C28x 16-Bit Parallel Boot GP I/O
        4.       431
        5. 12.11.6.3 Sample Command File for Booting From 8-Bit SCI Boot
        6.       433
    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
    16. 12.16 Hex Conversion Utility Error Messages
  15. 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
  16.   A Symbolic Debugging Directives
    1.     A.1 DWARF Debugging Format
    2.     A.2 Debug Directive Syntax
  17.   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 Symbol Table
  18.   C CRC Reference Implementation
    1.     C.1 Compilation Instructions
    2.     C.2 Reference CRC Calculation Routine
      1.      C.2.1 Reference Implementation of a CRC Calculation Function: ref_crc.c
    3.     C.3 Linker-Generated Copy Tables and CRC Tables
      1.      C.3.1 Main Routine for Example Application: main.c
      2.      C.3.2 Checking CRC Values: check_crc.c
      3.      C.3.3 Task1 Routine: task1.c
      4.      C.3.4 Task2 Routine: task2.c
      5.      C.3.5 Task3 Routine: task3.c
      6.      C.3.6 Example 1 Command File: ex1.cmd (for COFF)
  19.   D Glossary
    1.     D.1 Terminology
  20.   E Revision History

E Revision History

Changes from June 3, 2022 to October 31, 2023 (from Revision Y (June 2022) to Revision Z (October 2023))

  • Copy tables are now 32-bit aligned. They were previously 64-bit aligned.Go
  • CINIT tables are now 32-bit aligned. They were previously 64-bit aligned.Go
  • Removed documentation of the .preserve directive. Preserved variables are supported in C code, but not in hand-coded assembly.Go
  • Removed quotes from example for the --symbol_map option.Go
  • Clarified use of linker-defined symbols, including when and how to use the _symval() operator.Go
  • Copy tables are now 32-bit aligned. They were previously 64-bit aligned.Go
  • CRC tables are now 32-bit aligned. They were previously 64-bit aligned.Go
  • Corrected ASCII-hex output format address size and default width.Go

Changes from December 22, 2021 to June 3, 2022 (from Revision X (December 2021) to Revision Y (June 2022))

  • Corrected name of the --asm_cross_reference_listing option wherever it appears.Go
  • The --strict_compatibility linker option no longer has any effect and has been removed from the documentation.Go
  • Correct the description of the linker's include file search path.Go
  • Added --boot_align_sect and --boot_block_size options.Go
  • State that sections from multiple input images may not overlap when using the hex conversion utility.Go
  • Added --boot_align_sect and --boot_block_size options.Go

Changes from June 15, 2021 to December 22, 2021 (from Revision W (June 2021) to Revision X (December 2021))

  • Removed documentation of the -ar option, which is not supported.Go
  • Documented that combining the --absolute_exe and --relocatable options is supported only if the COFF ABI is used.Go

Changes from December 16, 2020 to June 15, 2021 (from Revision V (December 2020) to Revision W (June 2021))

  • Corrected the name of the C28_CHECKSUM_16 algorithm.Go
  • Corrected the name of the C28_CHECKSUM_16 algorithm.Go

Changes from September 1, 2020 to December 15, 2020 (from Revision U (September 2020) to Revision V (December 2020))

  • Added the --lfu_reference_elf command-line option.Go
  • Added the .preserve directive for use with Live Firmware Update (LFU).Go
  • Added the SYM_PRESERVE and SYM_UPDATE type for the .elfsym directive.Go
  • Removed documentation of the --rom linker option, which is not supportedGo
  • Added support for Cyclic Redundancy Check (CRC) checks over memory ranges.Go
  • Added the C28_CHECKSUM algorithm for CRC checks to match the CCS checksum utility.Go
  • Added support for Cyclic Redundancy Code (CRC) checks over memory ranges.Go
  • The new C28_CHECKSUM algorithm operated on 16-bit units, unlike the CRC algorithms.Go
  • Documented Hex Conversion Utility options related to the boot table for use with parallel XINTF streams.Go
  • Documented Hex Conversion Utility options related to image loading.Go
  • Documented additional Hex Conversion Utility options related to image loading.Go

Changes from February 28, 2020 to August 31, 2020 (from Revision T (February 2020) to Revision U (August 2020))

  • Updated the numbering format for tables, figures, and cross-references throughout the document.Go
  • Removed references to the Processors wiki throughout the document.Go

The following table lists changes made to this document prior to changes to the document numbering format. The left column identifies the first version of this document in which that particular change appeared.

Version Added Chapter Location Additions / Modifications / Deletions
SPRU513T Program Loading GUID-2ADFA9EA-D117-4046-82B3-A44A83461545.html#GUID-2ADFA9EA-D117-4046-82B3-A44A83461545 Corrected information about RAM and ROM model use of CINIT for initialization.
SPRU513T Linker GUID-CA083EDE-2CFD-4161-A82A-4DAD5AA7C51A.html#GUID-CA083EDE-2CFD-4161-A82A-4DAD5AA7C51A Clarified that either --rom_model or --ram_model is required if only the linker is being run, but --rom_model is the default if the compiler runs on C/C++ files on the same command line.
SPRU513T Linker GUID-88BEF897-2B81-4E60-B2D3-0DFDC3B57C38.html#GUID-88BEF897-2B81-4E60-B2D3-0DFDC3B57C38 Clarified that zero initialization takes place only if the --rom_model linker option is used, not if the --ram_model option is used.
SPRU513T Linker GUID-B65E09DA-4E20-4B45-9353-DF20B9418324.html#GUID-B65E09DA-4E20-4B45-9353-DF20B9418324, GUID-FF28563B-D6AD-4B87-8954-50CAED14DB3B.html#GUID-FF28563B-D6AD-4B87-8954-50CAED14DB3B, and GUID-1369FD42-8A59-4A32-A442-7F8E25B7EFB2.html#GUID-1369FD42-8A59-4A32-A442-7F8E25B7EFB2 Added LAST operator to define a symbol with the run-time address of the last allocated byte in the related memory range.
SPRU513T Hex Conversion Utility GUID-DA3B0CEE-E77D-4709-B228-F1CB0A32AEA7.html#GUID-DA3B0CEE-E77D-4709-B228-F1CB0A32AEA7 Boot tables can now be used with the hex conversion utility's Secure Flash Boot (--cmac) capability.
SPRU513T Hex Conversion Utility GUID-33A0B39D-F299-441F-8420-FCCFEA9EADBC.html#GUID-33A0B39D-F299-441F-8420-FCCFEA9EADBC Provided example showing the effects of 8-bit memory width vs. 16-bit memory width on the ROMS directive syntax.
SPRU513S -- throughout -- The default file extensions for object files created by the compiler have been changed in order to prevent conflicts when C and C++ files have the same names. Object files generated from C source files have the .c.obj extension. Object files generated from C++ source files have the .cpp.obj extension. Object files generated from assembly source files still have the .obj extension.
SPRU513S Hex Conversion Utility GUID-DA3B0CEE-E77D-4709-B228-F1CB0A32AEA7.html#GUID-DA3B0CEE-E77D-4709-B228-F1CB0A32AEA7 Added support for the secure flash boot capability provided by TMS320F2838x devices.
SPRU513R.1 Linker GUID-7909E664-EC9A-4A11-8DBC-380625950B1D.html#GUID-7909E664-EC9A-4A11-8DBC-380625950B1D Added documentation for the NOINIT special section type. (EABI only)
SPRU513R -- throughout -- Added further documentation of EABI support. This includes identifying features that are supported only for COFF or EABI. Identified examples as COFF-specific where necessary.
SPRU513R Object Modules GUID-E8B058A6-EB5B-4F30-ABC1-5E092BC85BDE.html#GUID-E8B058A6-EB5B-4F30-ABC1-5E092BC85BDE Added information about the ELF object file format.
SPRU513R Object Modules GUID-1676484E-7353-4D58-9D54-CF210DFC2053.html#GUID-1676484E-7353-4D58-9D54-CF210DFC2053, GUID-B37D38DC-3E0F-4CAA-AE24-2364FEEF9528.html#GUID-B37D38DC-3E0F-4CAA-AE24-2364FEEF9528 Added information about section names used by EABI.
SPRU513R Object Modules GUID-CF6CBE91-29B9-4050-8D6B-C9AADF1B7FF5.html#GUID-CF6CBE91-29B9-4050-8D6B-C9AADF1B7FF5 Revised information about types of symbols for clarity.
SPRU513R Program Loading GUID-924DD8ED-D843-4EAB-844B-E11E05A38C20.html#GUID-924DD8ED-D843-4EAB-844B-E11E05A38C20 Added information about the RAM model and ROM model for EABI.
SPRU513R Assembler Description GUID-7F8930CE-64B3-49EA-8F9E-2FC3409140D2.html#GUID-7F8930CE-64B3-49EA-8F9E-2FC3409140D2 Added information about controlling the ABI setting.
SPRU513R Assembler Description GUID-F412EB68-5F15-48C1-8C88-4CD468E6B79F.html#GUID-F412EB68-5F15-48C1-8C88-4CD468E6B79F Corrected list of symbolic constants.
SPRU513R Assembler Description GUID-6B2E45D6-02D0-4016-8B9A-F45551EDE696.html#GUID-6B2E45D6-02D0-4016-8B9A-F45551EDE696 Added the documentation for the FPU RB register.
SPRU513R Assembler Directives GUID-40FB6767-A63F-4969-9392-2558E5C14288.html#GUID-40FB6767-A63F-4969-9392-2558E5C14288 Added topics for directives related to EABI: .bss, .common, .elfsym, .group, .gmember, endgroup, .retain, .retainrefs, .weak, .xfloat, and .xldouble.
SPRU513R Assembler Directives .bits topic Modified the description of the .bits directive.
SPRU513R Assembler Directives .usect topic Modified the description of the .usect directive.
SPRU513R Assembler Directives .symdepend topic , .weak topic Split .symdepend and .weak directive topics.
SPRU513R Linker GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3.html#GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3 Added the --emit_references:file linker option.
SPRU513R Linker GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3.html#GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3 Added linker options related to EABI: --cinit_compression, --copy_compression, --retain, --unused_section_elimination, --warn_sections, and --zero_init.
SPRU513R Linker GUID-2B5A3343-5ADB-487E-A11C-3FEED17B51A0.html#GUID-2B5A3343-5ADB-487E-A11C-3FEED17B51A0 Added symbols automatically defined by the linker for EABI.
SPRU513R Linker GUID-80882276-4CEE-43F4-B9F2-BAA544DCEE26.html#GUID-80882276-4CEE-43F4-B9F2-BAA544DCEE26 Added information about weak symbols used by EABI.
SPRU513R Linker GUID-6BEDEFB7-8E12-47D5-B4D2-27E6E2FBD02F.html#GUID-6BEDEFB7-8E12-47D5-B4D2-27E6E2FBD02F Added information about compression available with EABI.
SPRU513Q Added support for EABI. The COFF ABI is the default.
SPRU513Q Assembler,
Linker		 GUID-F412EB68-5F15-48C1-8C88-4CD468E6B79F.html#GUID-F412EB68-5F15-48C1-8C88-4CD468E6B79F, GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA.html#GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA, and GUID-BA59EA1B-5D52-4730-97C9-A48835E5AB20.html#GUID-BA59EA1B-5D52-4730-97C9-A48835E5AB20 Added support for 64-bit floating point operations (--float_support=fpu64).
Added support for fast integer division (--idiv_support=idiv0).
Added support for additional TMU instructions (--tmu_support=tmu1).
Added support for Cyclic Redundancy Check (CRC) with the VCU (--vcu_support=vcrc).
SPRU513Q Linker GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3.html#GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3, GUID-40753F17-63A7-47C4-8AB6-C802BA12A5A6.html#GUID-40753F17-63A7-47C4-8AB6-C802BA12A5A6, and GUID-B9CCD576-4ACA-4E98-A04C-A88641189267.html#GUID-B9CCD576-4ACA-4E98-A04C-A88641189267 Added the --ecc=on linker option, which enables ECC generation. Note that ECC generation is now off by default.
SPRU513Q Linker GUID-DFB8D324-FC2A-40EA-A9E9-04E31EC1DC64.html#GUID-DFB8D324-FC2A-40EA-A9E9-04E31EC1DC64 Added linker syntax to combine initialized section with uninitialized sections.
SPRU513P Hex Conversion Utility GUID-956F28BC-EE18-4F39-B4A4-D838F3310D89.html#GUID-956F28BC-EE18-4F39-B4A4-D838F3310D89 and GUID-D6C99CD4-1246-47FF-B926-6499BC29C58B.html#GUID-D6C99CD4-1246-47FF-B926-6499BC29C58B Added the --array option, which causes the array output format to be generated.
SPRU513M Object Modules,
Assembler Directives		 GUID-B37D38DC-3E0F-4CAA-AE24-2364FEEF9528.html#GUID-B37D38DC-3E0F-4CAA-AE24-2364FEEF9528 and .usect topic Added information about DP load optimization.
SPRU513M Assembler Description GUID-2D9E46D7-5F6F-4013-A38A-7AF0E15B3B3C.html#GUID-2D9E46D7-5F6F-4013-A38A-7AF0E15B3B3C, GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA.html#GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA, and GUID-5BFBCF32-BA9C-4099-911A-3A85C8C9B57B.html#GUID-5BFBCF32-BA9C-4099-911A-3A85C8C9B57B Documented support for CLA version 2 and CLA v2 background tasks.
SPRU513M Assembler Directives .usect topic Explain the effect of the alignment flag for the .usect directive.
SPRU513M Linker Description GUID-EE812211-E132-497B-BB26-288B6C164992.html#GUID-EE812211-E132-497B-BB26-288B6C164992 Provided a link to an E2E blog post that provides examples that perform cyclic redundancy checking using linker-generated CRC tables.
SPRU513L Linker Description GUID-B9CCD576-4ACA-4E98-A04C-A88641189267.html#GUID-B9CCD576-4ACA-4E98-A04C-A88641189267 Documented revised behavior of ECC directives.
SPRU513K Linker Description GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3.html#GUID-26A6E3F3-7F0E-4EB2-8F4E-FFF8A877E2F3 Several linker options have been deprecated, removed, or renamed. The linker continues to accept some of the deprecated options, but they are not recommended for use.
SPRU513J Linker Description GUID-A8826637-0346-4D10-8D8E-A47F5969FEDE.html#GUID-A8826637-0346-4D10-8D8E-A47F5969FEDE Information about accessing files and libraries from a linker command file has been added.
SPRU513J Linker Description GUID-DA0DC720-0693-4BBB-909A-483FE2172CA5.html#GUID-DA0DC720-0693-4BBB-909A-483FE2172CA5 The list of available CRC algorithms has been expanded.
SPRU513J Object File Utilities GUID-0C894731-9E85-4DB0-B450-BEB10E1FCEBE.html#GUID-0C894731-9E85-4DB0-B450-BEB10E1FCEBE A –cg option has been added to the Object File Display utility to display function stack usage and callee information in XML format.
SPRU513I Program Loading, Linker GUID-CA94F19A-55D3-458C-AF20-299842571855.html#GUID-CA94F19A-55D3-458C-AF20-299842571855 and GUID-5DAC9927-33BD-4FF7-81CC-2FAFDE7B4371.html#GUID-5DAC9927-33BD-4FF7-81CC-2FAFDE7B4371 Added the BINIT (boot-time initialization) copy table.
SPRU513I Linker GUID-44F2BC16-D744-4B19-A62F-F29E6C6BDCDB.html#GUID-44F2BC16-D744-4B19-A62F-F29E6C6BDCDB Added modules as a filter for the --mapfile_contents linker option.
SPRU513I Linker GUID-56BA022E-394B-48A6-84D1-C8332DDEAB3E.html#GUID-56BA022E-394B-48A6-84D1-C8332DDEAB3E Added an example for placing functions in RAM.
SPRU513I Linker GUID-C9B54916-31F7-4AF3-B6DD-5B85CDA49B6C.html#GUID-C9B54916-31F7-4AF3-B6DD-5B85CDA49B6C Documented the table() operator.
SPRU513H -- -- The near and far keywords are deprecated, and the small memory model is no longer supported; the only memory model uses 32-bit pointers. The C27x object mode is also no longer supported. The .bss, .const, and .sysmem sections are no longer used; the .ebss, .econst, and .esysmem sections are used instead. As a result, the --farheap linker option, far call trampolines, and several other related features are no longer documented.
SPRU513H Object Modules GUID-1656ACA2-A8EC-43B6-A2D5-841DF5E62343.html#GUID-1656ACA2-A8EC-43B6-A2D5-841DF5E62343 Added information about the current section and how directives interact with it.
SPRU513H Object Modules GUID-CF6CBE91-29B9-4050-8D6B-C9AADF1B7FF5.html#GUID-CF6CBE91-29B9-4050-8D6B-C9AADF1B7FF5 and GUID-BB00316F-8220-4F47-A0ED-1C17FDC79B5B.html#GUID-BB00316F-8220-4F47-A0ED-1C17FDC79B5B Added information about various types of symbols and about symbol tables.
SPRU513G Assembler Description GUID-2D9E46D7-5F6F-4013-A38A-7AF0E15B3B3C.html#GUID-2D9E46D7-5F6F-4013-A38A-7AF0E15B3B3C and GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA.html#GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA Added support for Type 2 VCU via --vcu_support=vcu2.
SPRU513G Assembler Description GUID-2D9E46D7-5F6F-4013-A38A-7AF0E15B3B3C.html#GUID-2D9E46D7-5F6F-4013-A38A-7AF0E15B3B3C and GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA.html#GUID-6218AD22-946B-4383-BBF8-A6B12EEAF8DA Added support for Type 1 CLA via --cla_support=cla1.
SPRU513H Assembler Description GUID-5BFBCF32-BA9C-4099-911A-3A85C8C9B57B.html#GUID-5BFBCF32-BA9C-4099-911A-3A85C8C9B57B The naming of function frames in scratchpad memory for the CLA compiler has changed.
SPRU513H Linker GUID-C27F439A-019A-454A-A309-13D83DDBD258.html#GUID-C27F439A-019A-454A-A309-13D83DDBD258, GUID-FF28563B-D6AD-4B87-8954-50CAED14DB3B.html#GUID-FF28563B-D6AD-4B87-8954-50CAED14DB3B, and GUID-A4A89280-A715-4E24-A66E-E6C0B2976FB2.html#GUID-A4A89280-A715-4E24-A66E-E6C0B2976FB2 Added information about referencing linker symbols.
SPRU513H Linker GUID-BA59EA1B-5D52-4730-97C9-A48835E5AB20.html#GUID-BA59EA1B-5D52-4730-97C9-A48835E5AB20 Added a list of the linker's predefined macros.
SPRU513G Linker GUID-DF2119B0-6645-4D9B-AD96-6003E8505498.html#GUID-DF2119B0-6645-4D9B-AD96-6003E8505498 Removed invalid syntax for load and fill properties.

Changes from Revision () to Revision ()