SPRUIG8J January   2018  – March 2024

 

  1.   1
  2.   Read This First
    1.     About This Manual
    2.     Notational Conventions
    3.     Related Documentation
    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 Compiler Interface
    3. 1.3 ANSI/ISO Standard
    4. 1.4 Output Files
  4. 2 Getting Started with the Code Generation Tools
    1. 2.1 How Code Composer Studio Projects Use the Compiler
    2. 2.2 Compiling from the Command Line
  5. 3 Using the C/C++ Compiler
    1. 3.1  About the Compiler
    2. 3.2  Invoking the C/C++ Compiler
    3. 3.3  Changing the Compiler's Behavior with Options
      1. 3.3.1  Linker Options
      2. 3.3.2  Frequently Used Options
      3. 3.3.3  Miscellaneous Useful Options
      4. 3.3.4  Run-Time Model Options
      5. 3.3.5  Selecting Target CPU Version (--silicon_version Option)
      6. 3.3.6  Symbolic Debugging and Profiling Options
      7. 3.3.7  Specifying Filenames
      8. 3.3.8  Changing How the Compiler Interprets Filenames
      9. 3.3.9  Changing How the Compiler Processes C Files
      10. 3.3.10 Changing How the Compiler Interprets and Names Extensions
      11. 3.3.11 Specifying Directories
    4. 3.4  Controlling the Compiler Through Environment Variables
      1. 3.4.1 Setting Default Compiler Options (C7X_C_OPTION)
      2. 3.4.2 Naming One or More Alternate Directories (C7X_C_DIR)
    5. 3.5  Controlling the Preprocessor
      1. 3.5.1  Predefined Macro Names
      2. 3.5.2  The Search Path for #include Files
        1. 3.5.2.1 Adding a Directory to the #include File Search Path (--include_path Option)
      3. 3.5.3  Support for the #warning and #warn Directives
      4. 3.5.4  Generating a Preprocessed Listing File (--preproc_only Option)
      5. 3.5.5  Continuing Compilation After Preprocessing (--preproc_with_compile Option)
      6. 3.5.6  Generating a Preprocessed Listing File with Comments (--preproc_with_comment Option)
      7. 3.5.7  Generating Preprocessed Listing with Line-Control Details (--preproc_with_line Option)
      8. 3.5.8  Generating Preprocessed Output for a Make Utility (--preproc_dependency Option)
      9. 3.5.9  Generating a List of Files Included with #include (--preproc_includes Option)
      10. 3.5.10 Generating a List of Macros in a File (--preproc_macros Option)
    6. 3.6  Passing Arguments to main()
    7. 3.7  Understanding Diagnostic Messages
      1. 3.7.1 Controlling Diagnostic Messages
      2. 3.7.2 How You Can Use Diagnostic Suppression Options
    8. 3.8  Other Messages
    9. 3.9  Generating a Raw Listing File (--gen_preprocessor_listing Option)
    10. 3.10 Using Inline Function Expansion
      1. 3.10.1 Inlining Intrinsic Operators
      2. 3.10.2 Inlining Restrictions
      3. 3.10.3 Unguarded Definition-Controlled Inlining
        1. 3.10.3.1 Using the Inline Keyword
      4. 3.10.4 Guarded Inlining and the _INLINE Preprocessor Symbol
        1. 3.10.4.1 Header File string.h
        2. 3.10.4.2 Library Definition File
    11. 3.11 Using Interlist
    12. 3.12 About the Application Binary Interface
    13. 3.13 Enabling Entry Hook and Exit Hook Functions
  6. 4 Optimizing Your Code
    1. 4.1  Invoking Optimization
    2. 4.2  Controlling Code Size Versus Speed
    3. 4.3  Performing File-Level Optimization (--opt_level=3 option)
      1. 4.3.1 Creating an Optimization Information File (--gen_opt_info Option)
    4. 4.4  Program-Level Optimization (--program_level_compile and --opt_level=3 options)
      1. 4.4.1 Controlling Program-Level Optimization (--call_assumptions Option)
    5. 4.5  Automatic Inline Expansion (--auto_inline Option)
    6. 4.6  Link-Time Optimization (--opt_level=4 Option)
      1. 4.6.1 Option Handling
      2. 4.6.2 Incompatible Types
    7. 4.7  Optimizing Software Pipelining
      1. 4.7.1 Turn Off Software Pipelining (--disable_software_pipeline Option)
      2. 4.7.2 Software Pipelining Information
        1. 4.7.2.1 Software Pipelining Information
        2. 4.7.2.2 Software Pipelining Information Terms
        3. 4.7.2.3 Loop Disqualified for Software Pipelining Messages
        4. 4.7.2.4 Pipeline Failure Messages
        5. 4.7.2.5 Register Usage Table Generated by the --debug_software_pipeline Option
      3. 4.7.3 Collapsing Prologs and Epilogs for Improved Performance and Code Size
        1. 4.7.3.1 Speculative Execution
    8. 4.8  Redundant Loops
    9. 4.9  Indicating Whether Certain Aliasing Techniques Are Used
      1. 4.9.1 Use the --aliased_variables Option When Certain Aliases are Used
    10. 4.10 Prevent Reordering of Associative Floating-Point Operations
    11. 4.11 Using Performance Advice to Optimize Code
      1. 4.11.1 Advice #35000: Use restrict to improve loop performance
    12. 4.12 Using the Interlist Feature With Optimization
    13. 4.13 Debugging and Profiling Optimized Code
      1. 4.13.1 Profiling Optimized Code
    14. 4.14 What Kind of Optimization Is Being Performed?
      1. 4.14.1  Cost-Based Register Allocation
      2. 4.14.2  Alias Disambiguation
      3. 4.14.3  Branch Optimizations and Control-Flow Simplification
      4. 4.14.4  Data Flow Optimizations
      5. 4.14.5  Expression Simplification
      6. 4.14.6  Inline Expansion of Functions
      7. 4.14.7  Function Symbol Aliasing
      8. 4.14.8  Induction Variables and Strength Reduction
      9. 4.14.9  Loop-Invariant Code Motion
      10. 4.14.10 Loop Rotation
      11. 4.14.11 Loop Collapsing and Loop Coalescing
      12. 4.14.12 Unroll-and-jam
      13. 4.14.13 Vectorization (SIMD)
      14. 4.14.14 Instruction Scheduling
      15. 4.14.15 Register Variables
      16. 4.14.16 Register Tracking/Targeting
      17. 4.14.17 Software Pipelining
    15. 4.15 Streaming Engine and Streaming Address Generator
      1. 4.15.1 Streaming Engine Overview
      2. 4.15.2 Theory of Operation for Streaming Engines and Streaming Address Generators
      3. 4.15.3 Streaming Address Generator Overview
      4. 4.15.4 Advantages of Using Streaming Engines and Streaming Address Generators
      5. 4.15.5 Interface for Streaming Engine and Streaming Address Generator
      6. 4.15.6 Parameter Template Configuration
      7. 4.15.7 Using the Streaming Engine
        1. 4.15.7.1 Hard-Coded Intrinsic Operands with the Streaming Engine
      8. 4.15.8 Using the Streaming Address Generator
        1. 4.15.8.1 Vector Predication for Streaming Address Generators
        2. 4.15.8.2 Predicated vs. Unpredicated Streaming Address Stores and Loads
      9. 4.15.9 Automatic Use of Streaming Engine and Streaming Address Generator (--auto_stream Option)
        1. 4.15.9.1 Correctness of Automatic Use of SE and SA
        2. 4.15.9.2 Tuning Automatic Use of SE and SA
    16. 4.16 Nested Loop Controller (NLC)
      1. 4.16.1 Obstacles That May Inhibit Use of NLC
  7. 5 C/C++ Language Implementation
    1. 5.1  Characteristics of C7000 C
      1. 5.1.1 Implementation-Defined Behavior
    2. 5.2  Characteristics of C7000 C++
    3. 5.3  Data Types
      1. 5.3.1 Size of Enum Types
      2. 5.3.2 Vector Data Types
    4. 5.4  File Encodings and Character Sets
    5. 5.5  Keywords
      1. 5.5.1 The complex Keyword
      2. 5.5.2 The const Keyword
      3. 5.5.3 The __cregister Keyword
        1. 5.5.3.1 Define and Use Control Registers
        2. 5.5.3.2 Evaluating Flags in the Flag Status Register (FSR) After Floating Point Operations
      4. 5.5.4 The restrict Keyword
      5. 5.5.5 The volatile Keyword
    6. 5.6  C++ Exception Handling
    7. 5.7  Register Variables and Parameters
    8. 5.8  Pragma Directives
      1. 5.8.1  The CALLS Pragma
      2. 5.8.2  The CLINK Pragma
      3. 5.8.3  The COALESCE_LOOP Pragma
      4. 5.8.4  The CODE_ALIGN Pragma
      5. 5.8.5  The CODE_SECTION Pragma
      6. 5.8.6  The DATA_ALIGN Pragma
      7. 5.8.7  The DATA_MEM_BANK Pragma
        1. 5.8.7.1 Using the DATA_MEM_BANK Pragma
      8. 5.8.8  The DATA_SECTION Pragma
        1. 5.8.8.1 Using the DATA_SECTION Pragma C Source File
        2. 5.8.8.2 Using the DATA_SECTION Pragma C++ Source File
      9. 5.8.9  The Diagnostic Message Pragmas
      10. 5.8.10 The FORCEINLINE Pragma
      11. 5.8.11 The FORCEINLINE_RECURSIVE Pragma
      12. 5.8.12 The FUNC_ALWAYS_INLINE Pragma
      13. 5.8.13 The FUNC_CANNOT_INLINE Pragma
      14. 5.8.14 The FUNC_EXT_CALLED Pragma
      15. 5.8.15 The FUNC_IS_PURE Pragma
      16. 5.8.16 The FUNC_IS_SYSTEM Pragma
      17. 5.8.17 The FUNC_NEVER_RETURNS Pragma
      18. 5.8.18 The FUNC_NO_GLOBAL_ASG Pragma
      19. 5.8.19 The FUNC_NO_IND_ASG Pragma
      20. 5.8.20 The FUNCTION_OPTIONS Pragma
      21. 5.8.21 The INTERRUPT Pragma
      22. 5.8.22 The LOCATION Pragma
      23. 5.8.23 The MUST_ITERATE Pragma
        1. 5.8.23.1 The MUST_ITERATE Pragma Syntax
        2. 5.8.23.2 Using MUST_ITERATE to Expand Compiler Knowledge of Loops
      24. 5.8.24 The NOINIT and PERSISTENT Pragmas
      25. 5.8.25 The NOINLINE Pragma
      26. 5.8.26 The NO_COALESCE_LOOP Pragma
      27. 5.8.27 The NO_HOOKS Pragma
      28. 5.8.28 The once Pragma
      29. 5.8.29 The pack Pragma
      30. 5.8.30 The PROB_ITERATE Pragma
      31. 5.8.31 The RETAIN Pragma
      32. 5.8.32 The SET_CODE_SECTION and SET_DATA_SECTION Pragmas
      33. 5.8.33 The STRUCT_ALIGN Pragma
      34. 5.8.34 The UNROLL Pragma
      35. 5.8.35 The WEAK Pragma
    9. 5.9  The _Pragma Operator
    10. 5.10 Application Binary Interface
    11. 5.11 Object File Symbol Naming Conventions (Linknames)
    12. 5.12 Changing the ANSI/ISO C/C++ Language Mode
      1. 5.12.1 C99 Support (--c99)
      2. 5.12.2 C11 Support (--c11)
      3. 5.12.3 Strict ANSI Mode and Relaxed ANSI Mode (--strict_ansi and --relaxed_ansi)
    13. 5.13 GNU and Clang Language Extensions
      1. 5.13.1 Extensions
      2. 5.13.2 Function Attributes
      3. 5.13.3 For Loop Attributes
      4. 5.13.4 Variable Attributes
      5. 5.13.5 Type Attributes
      6. 5.13.6 Built-In Functions
    14. 5.14 Operations and Functions for Vector Data Types
      1. 5.14.1 Vector Literals and Concatenation
      2. 5.14.2 Unary and Binary Operators for Vectors
      3. 5.14.3 Ternary Operators for Vectors (?:)
      4. 5.14.4 Swizzle Operators for Vectors
      5. 5.14.5 Unsupported Vector Comparison Operators
      6. 5.14.6 Conversion Functions for Vectors
      7. 5.14.7 Re-Interpretation Functions for Vectors
      8. 5.14.8 Vector Predicate Type
        1. 5.14.8.1 Constructing a Vector Predicate Type
        2. 5.14.8.2 Using a Vector Predicate Type
        3. 5.14.8.3 Boolean Vector Types
    15. 5.15 C7000 Intrinsics
      1. 5.15.1 High-Level Overloaded Intrinsics
      2. 5.15.2 Intrinsics Defined for Special Load and Store Instructions
      3. 5.15.3 Direct-Mapped Intrinsics
      4. 5.15.4 Lookup Table and Histogram Intrinsics
      5. 5.15.5 Matrix-Multiply Accelerator (MMA) Intrinsics
      6. 5.15.6 Legacy Intrinsics
    16. 5.16 C7000 Scalable Vector Programming
  8. 6 Run-Time Environment
    1. 6.1 Memory
      1. 6.1.1 Sections
      2. 6.1.2 C/C++ System Stack
      3. 6.1.3 Dynamic Memory Allocation
    2. 6.2 Object Representation
      1. 6.2.1 Data Type Storage
        1. 6.2.1.1 char and short Data Types (signed and unsigned)
        2. 6.2.1.2 enum, int, and long Data Types (signed and unsigned)
        3. 6.2.1.3 long Data Types (signed and unsigned)
        4. 6.2.1.4 float Data Type
        5. 6.2.1.5 double and long double Data Types
        6. 6.2.1.6 Pointer to Data Member Types
        7. 6.2.1.7 Pointer to Member Function Types
        8. 6.2.1.8 Structures and Arrays
      2. 6.2.2 Bit Fields
      3. 6.2.3 Character String Constants
    3. 6.3 Register Conventions
    4. 6.4 Function Structure and Calling Conventions
      1. 6.4.1 How a Function Makes a Call
      2. 6.4.2 How a Called Function Responds
      3. 6.4.3 Accessing Arguments and Local Variables
    5. 6.5 Accessing Linker Symbols in C and C++
    6. 6.6 Run-Time-Support Arithmetic Routines
    7. 6.7 System Initialization
      1. 6.7.1 Boot Hook Functions for System Pre-Initialization
      2. 6.7.2 Automatic Initialization of Variables
        1. 6.7.2.1 Zero Initializing Variables
        2. 6.7.2.2 Direct Initialization
        3. 6.7.2.3 Autoinitialization of Variables at Run Time
        4. 6.7.2.4 Autoinitialization Tables
          1. 6.7.2.4.1 Length Followed by Data Format
          2. 6.7.2.4.2 Zero Initialization Format
          3. 6.7.2.4.3 Run Length Encoded (RLE) Format
          4. 6.7.2.4.4 Lempel-Ziv-Storer-Szymanski Compression (LZSS) Format
        5. 6.7.2.5 Initialization of Variables at Load Time
        6. 6.7.2.6 Global Constructors
  9. 7 Using Run-Time-Support Functions and Building Libraries
    1. 7.1 C and C++ Run-Time Support Libraries
      1. 7.1.1 Linking Code With the Object Library
      2. 7.1.2 Header Files
      3. 7.1.3 Modifying a Library Function
      4. 7.1.4 Support for String Handling
      5. 7.1.5 Minimal Support for Internationalization
      6. 7.1.6 Support for Time and Clock Functions
      7. 7.1.7 Allowable Number of Open Files
      8. 7.1.8 Library Naming Conventions
    2. 7.2 The C I/O Functions
      1. 7.2.1 High-Level I/O Functions
        1. 7.2.1.1 Formatting and the Format Conversion Buffer
      2. 7.2.2 Overview of Low-Level I/O Implementation
        1.       open
        2.       close
        3.       read
        4.       write
        5.       lseek
        6.       unlink
        7.       rename
      3. 7.2.3 Device-Driver Level I/O Functions
        1.       DEV_open
        2.       DEV_close
        3.       DEV_read
        4.       DEV_write
        5.       DEV_lseek
        6.       DEV_unlink
        7.       DEV_rename
      4. 7.2.4 Adding a User-Defined Device Driver for C I/O
        1. 7.2.4.1 Mapping Default Streams to Device
      5. 7.2.5 The device Prefix
        1.       add_device
        2.       291
        3. 7.2.5.1 Program for C I/O Device
    3. 7.3 Handling Reentrancy (_register_lock() and _register_unlock() Functions)
    4. 7.4 Library-Build Process
      1. 7.4.1 Required Non-Texas Instruments Software
      2. 7.4.2 Using the Library-Build Process
        1. 7.4.2.1 Automatic Standard Library Rebuilding by the Linker
        2. 7.4.2.2 Invoking mklib Manually
          1. 7.4.2.2.1 Building Standard Libraries
          2. 7.4.2.2.2 Shared or Read-Only Library Directory
          3. 7.4.2.2.3 Building Libraries With Custom Options
          4. 7.4.2.2.4 The mklib Program Option Summary
      3. 7.4.3 Extending mklib
        1. 7.4.3.1 Underlying Mechanism
        2. 7.4.3.2 Libraries From Other Vendors
  10. 8 Introduction to Object Modules
    1. 8.1 Object File Format Specifications
    2. 8.2 Executable Object Files
    3. 8.3 Introduction to Sections
      1. 8.3.1 Special Section Names
    4. 8.4 How the Linker Handles Sections
      1. 8.4.1 Combining Input Sections
      2. 8.4.2 Placing Sections
    5. 8.5 Symbols
      1. 8.5.1 Local Symbols
      2. 8.5.2 Weak Symbols
    6. 8.6 Loading a Program
  11. 9 Program Loading and Running
    1. 9.1 Loading
    2. 9.2 Entry Point
    3. 9.3 Run-Time Initialization
      1. 9.3.1 The _c_int00 Function
      2. 9.3.2 RAM Model vs. ROM Model
        1. 9.3.2.1 Autoinitializing Variables at Run Time (--rom_model)
        2. 9.3.2.2 Initializing Variables at Load Time (--ram_model)
        3. 9.3.2.3 The --rom_model and --ram_model Linker Options
      3. 9.3.3 About Linker-Generated Copy Tables
        1. 9.3.3.1 BINIT
        2. 9.3.3.2 CINIT
    4. 9.4 Arguments to main
    5. 9.5 Run-Time Relocation
    6. 9.6 Additional Information
  12. 10Archiver Description
    1. 10.1 Archiver Overview
    2. 10.2 The Archiver's Role in the Software Development Flow
    3. 10.3 Invoking the Archiver
    4. 10.4 Archiver Examples
    5. 10.5 Library Information Archiver Description
      1. 10.5.1 Invoking the Library Information Archiver
      2. 10.5.2 Library Information Archiver Example
      3. 10.5.3 Listing the Contents of an Index Library
      4. 10.5.4 Requirements
  13. 11Linking C/C++ Code
    1. 11.1 Invoking the Linker Through the Compiler (-z Option)
      1. 11.1.1 Invoking the Linker Separately
      2. 11.1.2 Invoking the Linker as Part of the Compile Step
      3. 11.1.3 Disabling the Linker (--compile_only Compiler Option)
    2. 11.2 Linker Code Optimizations
      1. 11.2.1 Conditional Linking
      2. 11.2.2 Generating Function Subsections (--gen_func_subsections Compiler Option)
      3. 11.2.3 Generating Aggregate Data Subsections (--gen_data_subsections Compiler Option)
    3. 11.3 Controlling the Linking Process
      1. 11.3.1 Including the Run-Time-Support Library
        1. 11.3.1.1 Automatic Run-Time-Support Library Selection
          1. 11.3.1.1.1 Using the --issue_remarks Option
        2. 11.3.1.2 Manual Run-Time-Support Library Selection
        3. 11.3.1.3 Library Order for Searching for Symbols
      2. 11.3.2 Run-Time Initialization
      3. 11.3.3 Global Object Constructors
      4. 11.3.4 Specifying the Type of Global Variable Initialization
      5. 11.3.5 Specifying Where to Allocate Sections in Memory
      6. 11.3.6 A Sample Linker Command File
  14. 12Linker Description
    1. 12.1  Linker Overview
    2. 12.2  The Linker's Role in the Software Development Flow
    3. 12.3  Invoking the Linker
    4. 12.4  Linker Options
      1. 12.4.1  Wildcards in File, Section, and Symbol Patterns
      2. 12.4.2  Specifying C/C++ Symbols with Linker Options
      3. 12.4.3  Relocation Capabilities (--absolute_exe and --relocatable Options)
        1. 12.4.3.1 Producing an Absolute Output Module (--absolute_exe option)
        2. 12.4.3.2 Producing a Relocatable Output Module (--relocatable option)
      4. 12.4.4  Allocate Memory for Use by the Loader to Pass Arguments (--arg_size Option)
      5. 12.4.5  Compression (--cinit_compression and --copy_compression Option)
      6. 12.4.6  Compress DWARF Information (--compress_dwarf Option)
      7. 12.4.7  Control Linker Diagnostics
      8. 12.4.8  Automatic Library Selection (--disable_auto_rts Option)
      9. 12.4.9  Do Not Remove Unused Sections (--unused_section_elimination Option)
      10. 12.4.10 Linker Command File Preprocessing (--disable_pp, --define and --undefine Options)
      11. 12.4.11 Define an Entry Point (--entry_point Option)
      12. 12.4.12 Set Default Fill Value (--fill_value Option)
      13. 12.4.13 Define Heap Size (--heap_size Option)
      14. 12.4.14 Hiding Symbols
      15. 12.4.15 Alter the Library Search Algorithm (--library, --search_path, and C7X_C_DIR )
        1. 12.4.15.1 Name an Alternate Library Directory (--search_path Option)
        2. 12.4.15.2 Name an Alternate Library Directory ( C7X_C_DIR Environment Variable)
        3. 12.4.15.3 Exhaustively Read and Search Libraries (--reread_libs and --priority Options)
      16. 12.4.16 Change Symbol Localization
        1. 12.4.16.1 Make All Global Symbols Static (--make_static Option)
      17. 12.4.17 Create a Map File (--map_file Option)
      18. 12.4.18 Manage Map File Contents (--mapfile_contents Option)
      19. 12.4.19 Disable Name Demangling (--no_demangle)
      20. 12.4.20 Merging of Symbolic Debugging Information
      21. 12.4.21 Strip Symbolic Information (--no_symtable Option)
      22. 12.4.22 Name an Output Module (--output_file Option)
      23. 12.4.23 Prioritizing Function Placement (--preferred_order Option)
      24. 12.4.24 C Language Options (--ram_model and --rom_model Options)
      25. 12.4.25 Retain Discarded Sections (--retain Option)
      26. 12.4.26 Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)
      27. 12.4.27 Define Stack Size (--stack_size Option)
      28. 12.4.28 Mapping of Symbols (--symbol_map Option)
      29. 12.4.29 Generate Far Call Trampolines (--trampolines Option)
        1. 12.4.29.1 Advantages and Disadvantages of Using Trampolines
        2. 12.4.29.2 Minimizing the Number of Trampolines Required (--minimize_trampolines Option)
        3. 12.4.29.3 Carrying Trampolines From Load Space to Run Space
      30. 12.4.30 Introduce an Unresolved Symbol (--undef_sym Option)
      31. 12.4.31 Display a Message When an Undefined Output Section Is Created (--warn_sections)
      32. 12.4.32 Generate XML Link Information File (--xml_link_info Option)
      33. 12.4.33 Zero Initialization (--zero_init Option)
    5. 12.5  Linker Command Files
      1. 12.5.1  Reserved Names in Linker Command Files
      2. 12.5.2  Constants in Linker Command Files
      3. 12.5.3  Accessing Files and Libraries from a Linker Command File
      4. 12.5.4  The MEMORY Directive
        1. 12.5.4.1 Default Memory Model
        2. 12.5.4.2 MEMORY Directive Syntax
        3. 12.5.4.3 Expressions and Address Operators
      5. 12.5.5  The SECTIONS Directive
        1. 12.5.5.1 SECTIONS Directive Syntax
        2. 12.5.5.2 Section Allocation and Placement
          1. 12.5.5.2.1 Binding
          2. 12.5.5.2.2 Named Memory
          3. 12.5.5.2.3 Controlling Placement Using The HIGH Location Specifier
            1. 12.5.5.2.3.1 Linker Placement With the HIGH Specifier
            2.         425
            3. 12.5.5.2.3.2 Linker Placement Without HIGH Specifier
          4. 12.5.5.2.4 Alignment and Blocking
          5. 12.5.5.2.5 Alignment With Padding
        3. 12.5.5.3 Specifying Input Sections
          1. 12.5.5.3.1 The Most Common Method of Specifying Section Contents
          2.        431
        4. 12.5.5.4 Using Multi-Level Subsections
        5. 12.5.5.5 Specifying Library or Archive Members as Input to Output Sections
          1. 12.5.5.5.1 Archive Members to Output Sections
          2.        435
        6. 12.5.5.6 Allocation Using Multiple Memory Ranges
        7. 12.5.5.7 Automatic Splitting of Output Sections Among Non-Contiguous Memory Ranges
      6. 12.5.6  Placing a Section at Different Load and Run Addresses
        1. 12.5.6.1 Specifying Load and Run Addresses
        2.       440
      7. 12.5.7  Using GROUP and UNION Statements
        1. 12.5.7.1 Grouping Output Sections Together
        2. 12.5.7.2 Overlaying Sections With the UNION Statement
        3. 12.5.7.3 Using Memory for Multiple Purposes
        4. 12.5.7.4 Nesting UNIONs and GROUPs
        5. 12.5.7.5 Checking the Consistency of Allocators
        6. 12.5.7.6 Naming UNIONs and GROUPs
      8. 12.5.8  Special Section Types (DSECT, COPY, NOLOAD, and NOINIT)
      9. 12.5.9  Assigning Symbols at Link Time
        1. 12.5.9.1 Syntax of Assignment Statements
        2. 12.5.9.2 Assigning the SPC to a Symbol
        3. 12.5.9.3 Assignment Expressions
        4. 12.5.9.4 Symbols Automatically Defined by the Linker
        5. 12.5.9.5 Assigning Exact Start, End, and Size Values of a Section to a Symbol
        6. 12.5.9.6 Why the Dot Operator Does Not Always Work
        7. 12.5.9.7 Address and Dimension Operators
          1. 12.5.9.7.1 Input Items
          2. 12.5.9.7.2 Output Section
          3. 12.5.9.7.3 GROUPs
          4. 12.5.9.7.4 UNIONs
        8. 12.5.9.8 LAST Operator
      10. 12.5.10 Creating and Filling Holes
        1. 12.5.10.1 Initialized and Uninitialized Sections
        2. 12.5.10.2 Creating Holes
        3. 12.5.10.3 Filling Holes
        4. 12.5.10.4 Explicit Initialization of Uninitialized Sections
    6. 12.6  Linker Symbols
      1. 12.6.1 Linker-Defined Functions and Arrays
      2. 12.6.2 Linker-Defined Integer Values
      3. 12.6.3 Linker-Defined Addresses
      4. 12.6.4 More About the _symval Operator
      5. 12.6.5 Using _symval, PC-Relative Addressing, and Far Data
      6. 12.6.6 Weak Symbols
        1. 12.6.6.1 Weak Symbol References
        2. 12.6.6.2 Weak Symbol Definitions
      7. 12.6.7 Resolving Symbols with Object Libraries
    7. 12.7  Default Placement Algorithm
      1. 12.7.1 How the Allocation Algorithm Creates Output Sections
      2. 12.7.2 Reducing Memory Fragmentation
    8. 12.8  Using Linker-Generated Copy Tables
      1. 12.8.1 Using Copy Tables for Boot Loading
      2. 12.8.2 Using Built-in Link Operators in Copy Tables
      3. 12.8.3 Overlay Management Example
      4. 12.8.4 Generating Copy Tables With the table() Operator
        1. 12.8.4.1 The table() Operator
        2. 12.8.4.2 Boot-Time Copy Tables
        3. 12.8.4.3 Using the table() Operator to Manage Object Components
        4. 12.8.4.4 Linker-Generated Copy Table Sections and Symbols
        5. 12.8.4.5 Splitting Object Components and Overlay Management
      5. 12.8.5 Compression
        1. 12.8.5.1 Compressed Copy Table Format
        2. 12.8.5.2 Compressed Section Representation in the Object File
        3. 12.8.5.3 Compressed Data Layout
        4. 12.8.5.4 Run-Time Decompression
        5. 12.8.5.5 Compression Algorithms
        6.       496
      6. 12.8.6 Copy Table Contents
      7. 12.8.7 General Purpose Copy Routine
    9. 12.9  Partial (Incremental) Linking
    10. 12.10 Linking C/C++ Code
      1. 12.10.1 Run-Time Initialization
      2. 12.10.2 Object Libraries and Run-Time Support
      3. 12.10.3 Setting the Size of the Stack and Heap Sections
      4. 12.10.4 Initializing and AutoInitialzing Variables at Run Time
      5. 12.10.5 Constraints Due to CMMU Configuration
    11. 12.11 Linker Example
  15. 13Object File Utilities
    1. 13.1 Invoking the Object File Display Utility
    2. 13.2 Invoking the Disassembler
    3. 13.3 Invoking the Name Utility
    4. 13.4 Invoking the Strip Utility
  16. 14C++ Name Demangler
    1. 14.1 Invoking the C++ Name Demangler
    2. 14.2 Sample Usage of the C++ Name Demangler
  17.   A XML Link Information File Description
    1.     A.1 XML Information File Element Types
    2.     A.2 Document Elements
      1.      A.2.1 Header Elements
      2.      A.2.2 Input File List
      3.      A.2.3 Object Component List
      4.      A.2.4 Logical Group List
      5.      A.2.5 Placement Map
      6.      A.2.6 Far Call Trampoline List
      7.      A.2.7 Symbol Table
  18.   B Unsupported Tools and Features
    1.     B.1 List of Unsupported Tools and Features
  19.   C Glossary
    1.     528
  20.   D Revision History

3.3 Changing the Compiler's Behavior with Options

Options control the operation of the compiler. This section provides a description of option conventions and an option summary table. It also provides detailed descriptions of the most frequently used options, including options used for type-checking.

For a help screen summary of the options, enter cl7x with no parameters on the command line.

The following apply to the compiler options:

  • There are typically two ways of specifying a given option. The "long form" uses a two hyphen prefix and is usually a more descriptive name. The "short form" uses a single hyphen prefix and a combination of letters and numbers that are not always intuitive.
  • Options are usually case sensitive.
  • Individual options cannot be combined.
  • An option with a parameter should be specified with an equal sign before the parameter to clearly associate the parameter with the option. For example, the option to undefine a constant can be expressed as --undefine=name. Likewise, the option to specify the maximum amount of optimization can be expressed as -O=3. You can also specify a parameter directly after certain options, for example -O3 is the same as -O=3. No space is allowed between the option and the optional parameter, so -O 3 is not accepted.
  • Files and options except the --run_linker option can occur in any order. The --run_linker option must follow all compiler options and precede any linker options.

You can define default options for the compiler by using the C7X_C_OPTION environment variable. For a detailed description of the environment variable, see Section 3.4.1.

Table 3-1 through Table 3-27 summarize all options (including link options). Use the references in the tables for more complete descriptions of the options.

Table 3-1 Processor Options
Option Alias Effect Section
--silicon_version=id -mv Selects target version. Defaults to 7100. Section 3.3.5
--silicon_errata_i2117 Generates code to work around the C7100 silicon errata i2117. Section 3.3.4
--silicon_errata_i2376={on|off} Generates code to work around the C7504 silicon errata i2376. Section 3.3.4
--big_endian -me Produces object code in big-endian format. The default format is little-endian. Section 3.3.4
--mma_version={ 1 | 2 | 2_256 | disallow } Specify the version of the Matrix Multiply Accelerator (MMA) to be used on the target device. Section 3.3.4
Table 3-2 Optimization Options(1)
Option Alias Effect Section
--opt_level=off Disables all optimization (default if option not used and --vectypes=off). Section 4.1
--opt_level=n -On Level 0 (-O0) optimizes register usage only (default if option not used and --vectypes=on).
Level 1 (-O1) uses Level 0 optimizations and optimizes locally.
Level 2 (-O2) uses Level 1 optimizations and optimizes globally (default if option used with no setting).
Level 3 (-O3) uses Level 2 optimizations and optimizes the file.
Level 4 (-O4) uses Level 3 optimizations and performs link-time optimization.		 Section 4.1, Section 4.3
--opt_for_speed[=n] -mf Controls the tradeoff between size and speed (0-5 range). If this option is not specified or is specified without n, the default value is 4. Section 4.2
(1) Note: Machine-specific options (see Table 3-12) can also affect optimization.
Table 3-3 Advanced Optimization Options(1)
Option Alias Effect Section
--assume_addresses_ok_for_stream={off|on} If enabled, the automatic streaming pass, which is controlled with the --auto_stream option, assumes that addressing patterns map to a stream legally. Section 4.15.9
Enabling this assumption can result in more use of a Streaming Engine (SE) or Streaming Address Generator (SA). Situations that could require such an assumption include, but are not limited to: 64-bit indexes, unsigned indexes, and array indexing applied to vector pointers.
--auto_inline=[size] -oi Sets automatic inlining size (--opt_level=3 only). If size is not specified, the default is 1. Section 4.5
--auto_stream={off|saving|no_saving} Controls whether the compiler attempts to automatically use the Streaming Engine (SE) and Streaming Address Generator (SA) where possible and profitable. Section 4.15.9
In "off" mode, automatic use of the SE and SA is disabled. In "saving" mode, the SE and/or SA state are saved in case they are already in use. In "no_saving" mode, automatic use of the SE and SA is enabled without context saving. C7100 and C7120 devices support only "off" or "no_saving" modes and "off" is the default. Newer devices, such as C7504, support all three modes and --auto_stream=saving is the default.
--call_assumptions=n -opn Level 0 (-op0) specifies that the module contains functions and variables that are called or modified from outside the source code provided to the compiler.
Level 1 (-op1) specifies that the module contains variables modified from outside the source code provided to the compiler but does not use functions called from outside the source code.
Level 2 (-op2) specifies that the module contains no functions or variables that are called or modified from outside the source code provided to the compiler (default).
Level 3 (-op3) specifies that the module contains functions that are called from outside the source code provided to the compiler but does not use variables modified from outside the source code.		 Section 4.4.1
--disable_inlining Prevents any inlining from occurring. Section 3.10
--fp_mode={relaxed|strict} Enables or disables relaxed floating-point mode. Section 3.3.3
--fp_reassoc={on|off} Enables or disables the reassociation of floating-point arithmetic. Section 3.3.3
--fp_single_precision_constant Causes all unsuffixed floating-point constants to be treated as single precision values instead of as double-precision constants. Section 3.3.3
--gen_opt_info=n -onn Level 0 (-on0) disables the optimization information file.
Level 1 (-on2) produces an optimization information file.
Level 2 (-on2) produces a verbose optimization information file.		 Section 4.3.1
--optimizer_interlist -os Interlists optimizer comments with assembly statements. Section 4.12
--program_level_compile -pm Combines source files to perform program-level optimization. Section 4.4
--src_interlist -s Interlists optimizer comments (if available) and assembly source statements; otherwise interlists C and assembly source statements. Section 3.3.2
--aliased_variables -ma Notifies the compiler that addresses passed to functions may be modified by an alias in the called function. Section 4.9.1
(1) Note: Machine-specific run-time options (see Table 3-12) can also affect optimization.
Table 3-4 Debug Options
Option Alias Effect Section
--symdebug:dwarf -g Default behavior. Enables symbolic debugging. The generation of debug information does not impact optimization. Therefore, generating debug information is enabled by default. Section 3.3.6
Section 4.13
--symdebug:dwarf_version=3|4 Specifies the DWARF format version. The default version is 4. Section 3.3.6
--symdebug:none Disables all symbolic debugging. Section 3.3.6
Section 4.13
Table 3-5 Include Options
Option Alias Effect Section
--include_path=directory -I Adds the specified directory to the #include search path. Section 3.5.2.1
--preinclude=filename Includes filename at the beginning of compilation. Section 3.3.3
Table 3-6 Control Options
Option Alias Effect Section
--compile_only -c Disables linking (negates --run_linker). Section 11.1.3
--help -h Prints (on the standard output device) a description of the options understood by the compiler. Section 3.3.2
--run_linker -z Causes the linker to be invoked from the compiler command line. Section 3.3.2
--skip_assembler -n Compiles C/C++ source file , producing an assembly language output file. The assembler is not run and no object file is produced. Section 3.3.2
--keep_asm -k Keeps the assembly language (.asm) file.
Table 3-7 Language Options
Option Alias Effect Section
--c89 Processes C files according to the ISO C89 standard. Section 5.12
--c99 Processes C files according to the ISO C99 standard. Section 5.12
--c11 Processes C files according to the ISO C11 standard. Section 5.12
--c++14 Processes C++ files according to the ISO C++14 standard. Section 5.12
--cpp_default -fg Processes all source files with a C extension as C++ source files. Section 3.3.8
--exceptions Enables C++ exception handling. Section 5.6
--extern_c_can_throw Allow extern C functions to propagate exceptions. --
--float_operations_allowed
={none|all|32|64}		 Restricts the types of floating point operations allowed. Section 3.3.3
--pending_instantiations=# Specify the number of template instantiations that may be in progress at any given time. Use 0 to specify an unlimited number. Section 3.3.4
--printf_support={nofloat|full|
minimal}		 Enables support for smaller, limited versions of the printf function family (sprintf, fprintf, etc.) and the scanf function family (sscanf, fscanf, etc.) run-time-support functions. Section 3.3.3
--relaxed_ansi -pr Enables relaxed mode; ignores strict ISO violations. This is on by default. To disable this mode, use the --strict_ansi option. Section 5.12.3
--strict_ansi -ps Enables strict ANSI/ISO mode (for C/C++, not for K&R C). In this mode, language extensions that conflict with ANSI/ISO C/C++ are disabled. In strict ANSI/ISO mode, most ANSI/ISO violations are reported as errors. Violations that are considered discretionary may be reported as warnings instead. Section 5.12.3
--vectypes={on|off} Enable support for TI vector data types. On by default. Section 5.3.2
Table 3-8 Parser Preprocessing Options
Option Alias Effect Section
--preproc_dependency[=filename] -ppd Performs preprocessing only, but instead of writing preprocessed output, writes a list of dependency lines suitable for input to a standard make utility. Section 3.5.8
--preproc_includes[=filename] -ppi Performs preprocessing only, but instead of writing preprocessed output, writes a list of files included with the #include directive. Section 3.5.9
--preproc_macros[=filename] -ppm Performs preprocessing only. Writes list of predefined and user-defined macros to a file with the same name as the input but with a .pp extension. Section 3.5.10
--preproc_only -ppo Performs preprocessing only. Writes preprocessed output to a file with the same name as the input but with a .pp extension. Section 3.5.4
--preproc_with_comment -ppc Performs preprocessing only. Writes preprocessed output, keeping the comments, to a file with the same name as the input but with a .pp extension. Section 3.5.6
--preproc_with_compile -ppa Continues compilation after preprocessing with any of the -pp<x> options that normally disable compilation. Section 3.5.5
--preproc_with_line -ppl Performs preprocessing only. Writes preprocessed output with line-control information (#line directives) to a file with the same name as the input but with a .pp extension. Section 3.5.7
Table 3-9 Predefined Macro Options
Option Alias Effect Section
--define=name[=def] -D Predefines name. Section 3.3.2
--undefine=name -U Undefines name. Section 3.3.2
Table 3-10 Diagnostic Message Options
Option Alias Effect Section
--compiler_revision Prints out the compiler release revision and exits. --
--diag_error=num -pdse Categorizes the diagnostic identified by num as an error. Section 3.7.1
--diag_remark=num -pdsr Categorizes the diagnostic identified by num as a remark. Section 3.7.1
--diag_suppress=num -pds Suppresses the diagnostic identified by num. Section 3.7.1
--diag_warning=num -pdsw Categorizes the diagnostic identified by num as a warning. Section 3.7.1
--diag_wrap={on|off} Wrap diagnostic messages (default is on). Note that this command-line option cannot be used within the Code Composer Studio IDE.
--display_error_number -pden Displays a diagnostic's identifiers along with its text. Note that this command-line option cannot be used within the Code Composer Studio IDE. Section 3.7.1
--emit_warnings_as_errors -pdew Treat warnings as errors. Section 3.7.1
--issue_remarks -pdr Issues remarks (non-serious warnings). Section 3.7.1
--no_warnings -pdw Suppresses diagnostic warnings (errors are still issued). Section 3.7.1
--quiet -q Suppresses progress messages (quiet). --
--set_error_limit=num -pdel Sets the error limit to num. The compiler abandons compiling after this number of errors. (The default is 100.) Section 3.7.1
--super_quiet -qq Super quiet mode. --
--tool_version -version Displays version number for each tool. --
--verbose Display banner and function progress information. --
--verbose_diagnostics -pdv Provides verbose diagnostic messages that display the original source with line-wrap. Note that this command-line option cannot be used within the Code Composer Studio IDE. Section 3.7.1
--write_diagnostics_file -pdf Generates a diagnostic message information file. Compiler only option. Note that this command-line option cannot be used within the Code Composer Studio IDE. Section 3.7.1
Table 3-11 Supplemental Information Options
Option Alias Effect Section
--gen_preprocessor_listing -pl Generates a raw listing file (.rl). Section 3.9
--section_sizes={on|off} Generates section size information, including sizes for sections containing executable code and constants, constant or initialized data (global and static variables), and uninitialized data. (Default is off if this option is not included on the command line. Default is on if this option is used with no value specified.) Section 3.7.1
Table 3-12 Run-Time Model Options
Option Alias Effect Section
--common={on|off} On by default. When on, uninitialized file scope variables are emitted as common symbols. When off, common symbols are not created. Section 3.3.4
--debug_software_pipeline -mw Produce verbose software pipelining report. Section 4.7.2
--disable_software_pipeline -mu Turns off software pipelining. Section 4.7.1
--fp_not_associative -mc Prevents reordering of associative floating-point operations. Section 4.10
--gen_data_subsections={on|off} Place all aggregate data (arrays, structs, and unions) into subsections. This gives the linker more control over removing unused data during the final link step. See the link to the right for details about the default setting. Section 11.2.3
--gen_func_subsections={on|off} -mo Puts each function in a separate subsection in the object file. If this option is not used, the default is off. See the link to the right for details about the default setting. Section 11.2.2
--ramfunc={on|off} If set to on, indicates that each function will be run from RAM. Functions will be placed in RAM and optimized for RAM execution. Equivalent to specifying __attribute__((ram_func)) on all functions in the translation unit. Section 3.3.4
Table 3-13 Entry/Exit Hook Options
Option Alias Effect Section
--entry_hook[=name] Enables entry hooks. Section 3.13
--entry_parm={none|name|
address}		 Specifies the parameters to the function to the --entry_hook option. Section 3.13
--exit_hook[=name] Enables exit hooks. Section 3.13
--exit_parm={none|name|address} Specifies the parameters to the function to the --exit_hook option. Section 3.13
--remove_hooks_when_inlining Removes entry/exit hooks for auto-inlined functions. Section 3.13
Table 3-14 Assembly Options
Option Alias Effect Section
--c_src_interlist -ss Interlists C source and assembly statements. Section 3.11
Section 4.12
Table 3-15 File Type Specifier Options
Option Alias Effect Section
--asm_file=filename -fa Identifies filename as an assembly source file regardless of its extension. By default, the compiler and assembler treat .asm files as assembly source files. Section 3.3.8
--c_file=filename -fc Identifies filename as a C source file regardless of its extension. By default, the compiler treats .c files as C source files. Section 3.3.8
--cpp_file=filename -fp Identifies filename as a C++ file, regardless of its extension. By default, the compiler treats .C, .cpp, .cc and .cxx files as a C++ files. Section 3.3.8
--obj_file=filename -fo Identifies filename as an object code file regardless of its extension. By default, the compiler and linker treat .obj files as object code files, including both *.c.obj and *.cpp.obj files. Section 3.3.8
Table 3-16 Directory Specifier Options
Option Alias Effect Section
--asm_directory=directory -fs Specifies an assembly file directory. By default, the compiler uses the current directory. Section 3.3.11
--obj_directory=directory -fr Specifies an object file directory. By default, the compiler uses the current directory. Section 3.3.11
--output_file=filename -fe Specifies a compilation output file name; can override --obj_directory. Section 3.3.11
--pp_directory=dir Specifies a preprocessor file directory. By default, the compiler uses the current directory. Section 3.3.11
--temp_directory=directory -ft Specifies a temporary file directory. By default, the compiler uses the current directory. Section 3.3.11
Table 3-17 Default File Extensions Options
Option Alias Effect Section
--asm_extension=[.]extension -ea Sets a default extension for assembly source files. Section 3.3.10
--c_extension=[.]extension -ec Sets a default extension for C source files. Section 3.3.10
--cpp_extension=[.]extension -ep Sets a default extension for C++ source files. Section 3.3.10
--listing_extension=[.]extension -es Sets a default extension for listing files. Section 3.3.10
--obj_extension=[.]extension -eo Sets a default extension for object files. Section 3.3.10
Table 3-18 Command Files Options
Option Alias Effect Section
--cmd_file=filename -@ Interprets contents of a file as an extension to the command line. Multiple -@ instances can be used. Section 3.3.2
Table 3-19 Performance Advisor Options
Option Alias Effect Section
--advice:performance[={all|none}] Generates compiler optimization advice. Default is all. Section 4.11
--advice:performance_file={stdout|
    stderr|user_specified_filename}		 Specifies that advice be written to stdout, stderr, or a file. Section 4.11
--advice:performance_dir=
    {user_specified_directory_name}		 Specifies that advice file be created in the named directory. Section 4.11