• Menu
  • Product
  • Email
  • PDF
  • Order now
  • ARM Optimizing C/C++ Compiler v20.2.0.LTS

    • SPNU151V January   1998  – February 2020

       

  • CONTENTS
  • SEARCH
  • ARM Optimizing C/C++ Compiler v20.2.0.LTS
  1.   Read This First
    1.     About This Manual
    2.     Notational Conventions
    3.     Related Documentation
    4.     Related Documentation From Texas Instruments
    5.     Trademarks
  2. 1Introduction 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
    5. 1.5 Utilities
  3. 2Using the C/C++ Compiler
    1. 2.1  About the Compiler
    2. 2.2  Invoking the C/C++ Compiler
    3. 2.3  Changing the Compiler's Behavior with Options
      1. 2.3.1  Linker Options
      2. 2.3.2  Frequently Used Options
      3. 2.3.3  Miscellaneous Useful Options
      4. 2.3.4  Run-Time Model Options
      5. 2.3.5  Symbolic Debugging and Profiling Options
      6. 2.3.6  Specifying Filenames
      7. 2.3.7  Changing How the Compiler Interprets Filenames
      8. 2.3.8  Changing How the Compiler Processes C Files
      9. 2.3.9  Changing How the Compiler Interprets and Names Extensions
      10. 2.3.10 Specifying Directories
      11. 2.3.11 Assembler Options
      12. 2.3.12 Deprecated Options
    4. 2.4  Controlling the Compiler Through Environment Variables
      1. 2.4.1 Setting Default Compiler Options (TI_ARM_C_OPTION)
      2. 2.4.2 Naming One or More Alternate Directories (TI_ARM_C_DIR)
    5. 2.5  Controlling the Preprocessor
      1. 2.5.1  Predefined Macro Names
      2. 2.5.2  The Search Path for #include Files
        1. 2.5.2.1 Adding a Directory to the #include File Search Path (--include_path Option)
      3. 2.5.3  Support for the #warning and #warn Directives
      4. 2.5.4  Generating a Preprocessed Listing File (--preproc_only Option)
      5. 2.5.5  Continuing Compilation After Preprocessing (--preproc_with_compile Option)
      6. 2.5.6  Generating a Preprocessed Listing File with Comments (--preproc_with_comment Option)
      7. 2.5.7  Generating Preprocessed Listing with Line-Control Details (--preproc_with_line Option)
      8. 2.5.8  Generating Preprocessed Output for a Make Utility (--preproc_dependency Option)
      9. 2.5.9  Generating a List of Files Included with #include (--preproc_includes Option)
      10. 2.5.10 Generating a List of Macros in a File (--preproc_macros Option)
    6. 2.6  Passing Arguments to main()
    7. 2.7  Understanding Diagnostic Messages
      1. 2.7.1 Controlling Diagnostic Messages
      2. 2.7.2 How You Can Use Diagnostic Suppression Options
    8. 2.8  Other Messages
    9. 2.9  Generating Cross-Reference Listing Information (--gen_cross_reference Option)
    10. 2.10 Generating a Raw Listing File (--gen_preprocessor_listing Option)
    11. 2.11 Using Inline Function Expansion
      1. 2.11.1 Inlining Intrinsic Operators
      2. 2.11.2 Inlining Restrictions
    12. 2.12 Using Interlist
      1.      Example 1. An Interlisted Assembly Language File
    13. 2.13 Controlling Application Binary Interface
    14. 2.14 VFP Support
    15. 2.15 Enabling Entry Hook and Exit Hook Functions
  4. 3Optimizing Your Code
    1. 3.1  Invoking Optimization
    2. 3.2  Controlling Code Size Versus Speed
    3. 3.3  Performing File-Level Optimization (--opt_level=3 option)
      1. 3.3.1 Creating an Optimization Information File (--gen_opt_info Option)
    4. 3.4  Program-Level Optimization (--program_level_compile and --opt_level=3 options)
      1. 3.4.1 Controlling Program-Level Optimization (--call_assumptions Option)
      2. 3.4.2 Optimization Considerations When Mixing C/C++ and Assembly
    5. 3.5  Automatic Inline Expansion (--auto_inline Option)
    6. 3.6  Link-Time Optimization (--opt_level=4 Option)
      1. 3.6.1 Option Handling
      2. 3.6.2 Incompatible Types
    7. 3.7  Using Feedback Directed Optimization
      1. 3.7.1 Feedback Directed Optimization
        1. 3.7.1.1 Phase 1 -- Collect Program Profile Information
        2. 3.7.1.2 Phase 2 -- Use Application Profile Information for Optimization
        3. 3.7.1.3 Generating and Using Profile Information
        4. 3.7.1.4 Example Use of Feedback Directed Optimization
        5. 3.7.1.5 The .ppdata Section
        6. 3.7.1.6 Feedback Directed Optimization and Code Size Tune
        7. 3.7.1.7 Instrumented Program Execution Overhead
        8. 3.7.1.8 Invalid Profile Data
      2. 3.7.2 Profile Data Decoder
      3. 3.7.3 Feedback Directed Optimization API
      4. 3.7.4 Feedback Directed Optimization Summary
    8. 3.8  Using Profile Information to Analyze Code Coverage
      1. 3.8.1 Code Coverage
        1. 3.8.1.1 Phase1 -- Collect Program Profile Information
        2. 3.8.1.2 Phase 2 -- Generate Code Coverage Reports
      2. 3.8.2 Related Features and Capabilities
        1. 3.8.2.1 Path Profiler
        2. 3.8.2.2 Analysis Options
        3. 3.8.2.3 Environment Variables
    9. 3.9  Accessing Aliased Variables in Optimized Code
    10. 3.10 Use Caution With asm Statements in Optimized Code
    11. 3.11 Using the Interlist Feature With Optimization
      1.      Example 1. The Function From Compiled With the -O2 and --optimizer_interlist Options
      2.      Example 2. The Function From Compiled with the --opt_level=2, --optimizer_interlist, and --c_src_interlist Options
    12. 3.12 Debugging and Profiling Optimized Code
      1. 3.12.1 Profiling Optimized Code
    13. 3.13 What Kind of Optimization Is Being Performed?
      1. 3.13.1  Cost-Based Register Allocation
      2. 3.13.2  Alias Disambiguation
      3. 3.13.3  Branch Optimizations and Control-Flow Simplification
      4. 3.13.4  Data Flow Optimizations
      5. 3.13.5  Expression Simplification
      6. 3.13.6  Inline Expansion of Functions
      7. 3.13.7  Function Symbol Aliasing
      8. 3.13.8  Induction Variables and Strength Reduction
      9. 3.13.9  Loop-Invariant Code Motion
      10. 3.13.10 Loop Rotation
      11. 3.13.11 Instruction Scheduling
      12. 3.13.12 Tail Merging
      13. 3.13.13 Autoincrement Addressing
      14. 3.13.14 Block Conditionalizing
        1.       Example 3. Block Conditionalizing C Source
        2.       Example 4. C/C++ Compiler Output for
      15. 3.13.15 Epilog Inlining
      16. 3.13.16 Removing Comparisons to Zero
      17. 3.13.17 Integer Division With Constant Divisor
      18. 3.13.18 Branch Chaining
  5. 4Linking C/C++ Code
    1. 4.1 Invoking the Linker Through the Compiler (-z Option)
      1. 4.1.1 Invoking the Linker Separately
      2. 4.1.2 Invoking the Linker as Part of the Compile Step
      3. 4.1.3 Disabling the Linker (--compile_only Compiler Option)
    2. 4.2 Linker Code Optimizations
      1. 4.2.1 Generate List of Dead Functions (--generate_dead_funcs_list Option)
      2. 4.2.2 Generating Aggregate Data Subsections (--gen_data_subsections Compiler Option)
    3. 4.3 Controlling the Linking Process
      1. 4.3.1 Including the Run-Time-Support Library
        1. 4.3.1.1 Automatic Run-Time-Support Library Selection
          1.        Example 1. Using the --issue_remarks Option
        2. 4.3.1.2 Manual Run-Time-Support Library Selection
        3. 4.3.1.3 Library Order for Searching for Symbols
      2. 4.3.2 Run-Time Initialization
      3. 4.3.3 Initialization of Cinit and Watchdog Timer Hold
      4. 4.3.4 Global Object Constructors
      5. 4.3.5 Specifying the Type of Global Variable Initialization
      6. 4.3.6 Specifying Where to Allocate Sections in Memory
      7. 4.3.7 A Sample Linker Command File
        1.       Example 2. Linker Command File
  6. 5C/C++ Language Implementation
    1. 5.1  Characteristics of ARM C
      1. 5.1.1 Implementation-Defined Behavior
    2. 5.2  Characteristics of ARM C++
    3. 5.3  Using MISRA C 2004
    4. 5.4  Using the ULP Advisor
    5. 5.5  Data Types
      1. 5.5.1 Size of Enum Types
    6. 5.6  File Encodings and Character Sets
    7. 5.7  Keywords
      1. 5.7.1 The const Keyword
      2. 5.7.2 The __interrupt Keyword
      3. 5.7.3 The volatile Keyword
        1.       Example 1. Volatile for Local Variables With setjmp
    8. 5.8  C++ Exception Handling
    9. 5.9  Register Variables and Parameters
      1. 5.9.1 Local Register Variables and Parameters
      2. 5.9.2 Global Register Variables
    10. 5.10 The __asm Statement
    11. 5.11 Pragma Directives
      1. 5.11.1  The CALLS Pragma
      2. 5.11.2  The CHECK_MISRA Pragma
      3. 5.11.3  The CHECK_ULP Pragma
      4. 5.11.4  The CODE_ALIGN Pragma
      5. 5.11.5  The CODE_SECTION Pragma
        1.       Example 2. Using the CODE_SECTION Pragma C Source File
        2.       Example 3. Generated Assembly Code From
      6. 5.11.6  The CODE_STATE Pragma
      7. 5.11.7  The DATA_ALIGN Pragma
      8. 5.11.8  The DATA_SECTION Pragma
        1.       Example 4. Using the DATA_SECTION Pragma C Source File
        2.       Example 5. Using the DATA_SECTION Pragma C++ Source File
        3.       Example 6. Using the DATA_SECTION Pragma Assembly Source File
      9. 5.11.9  The Diagnostic Message Pragmas
      10. 5.11.10 The DUAL_STATE Pragma
      11. 5.11.11 The FORCEINLINE Pragma
      12. 5.11.12 The FORCEINLINE_RECURSIVE Pragma
      13. 5.11.13 The FUNC_ALWAYS_INLINE Pragma
      14. 5.11.14 The FUNC_CANNOT_INLINE Pragma
      15. 5.11.15 The FUNC_EXT_CALLED Pragma
      16. 5.11.16 The FUNCTION_OPTIONS Pragma
      17. 5.11.17 The INTERRUPT Pragma
      18. 5.11.18 The LOCATION Pragma
      19. 5.11.19 The MUST_ITERATE Pragma
        1. 5.11.19.1 The MUST_ITERATE Pragma Syntax
        2. 5.11.19.2 Using MUST_ITERATE to Expand Compiler Knowledge of Loops
      20. 5.11.20 The NOINIT and PERSISTENT Pragmas
      21. 5.11.21 The NOINLINE Pragma
      22. 5.11.22 The NO_HOOKS Pragma
      23. 5.11.23 The once Pragma
      24. 5.11.24 The pack Pragma
      25. 5.11.25 The RESET_MISRA Pragma
      26. 5.11.26 The RESET_ULP Pragma
      27. 5.11.27 The RETAIN Pragma
      28. 5.11.28 The SET_CODE_SECTION and SET_DATA_SECTION Pragmas
        1.       Example 7. Setting Section With SET_DATA_SECTION Pragma
        2.       Example 8. Setting a Section With SET_CODE_SECTION Pragma
        3.       Example 9. Overriding SET_DATA_SECTION Setting
      29. 5.11.29 The SWI_ALIAS Pragma
        1.       Example 10. Using the SWI_ALIAS Pragma C Source File
        2.       Example 11. Generated Assembly File
      30. 5.11.30 The TASK Pragma
      31. 5.11.31 The UNROLL Pragma
      32. 5.11.32 The WEAK Pragma
    12. 5.12 The _Pragma Operator
    13. 5.13 Application Binary Interface
    14. 5.14 ARM Instruction Intrinsics
    15. 5.15 Object File Symbol Naming Conventions (Linknames)
    16. 5.16 Changing the ANSI/ISO C/C++ Language Mode
      1. 5.16.1 C99 Support (--c99)
      2. 5.16.2 C11 Support (--c11)
      3. 5.16.3 Strict ANSI Mode and Relaxed ANSI Mode (--strict_ansi and --relaxed_ansi)
    17. 5.17 GNU, Clang, and ACLE Language Extensions
      1. 5.17.1 Extensions
      2. 5.17.2 Function Attributes
      3. 5.17.3 Variable Attributes
      4. 5.17.4 Type Attributes
      5. 5.17.5 Built-In Functions
    18. 5.18 AUTOSAR
    19. 5.19 Compiler Limits
  7. 6Run-Time Environment
    1. 6.1  Memory Model
      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 float, int, and long Data Types (signed and unsigned)
        3. 6.2.1.3 double, long double, and long long Data Types (signed and unsigned)
        4. 6.2.1.4 Pointer to Data Member Types
        5. 6.2.1.5 Pointer to Member Function Types
        6. 6.2.1.6 Structure and Array Alignment
      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 C Exception Handler Calling Convention
      4. 6.4.4 Accessing Arguments and Local Variables
    5. 6.5  Accessing Linker Symbols in C and C++
    6. 6.6  Interfacing C and C++ With Assembly Language
      1. 6.6.1 Using Assembly Language Modules With C/C++ Code
      2. 6.6.2 Accessing Assembly Language Functions From C/C++
        1.       Example 1. Calling an Assembly Language Function From a C/C++ Program
        2.       Example 2. Assembly Language Program Called by
      3. 6.6.3 Accessing Assembly Language Variables From C/C++
        1. 6.6.3.1 Accessing Assembly Language Global Variables
          1.        Example 3. Assembly Language Variable Program
          2.        Example 4. C Program to Access Assembly Language From
        2. 6.6.3.2 Accessing Assembly Language Constants
          1.        Example 5. Accessing an Assembly Language Constant From C
          2.        Example 6. Assembly Language Program for
      4. 6.6.4 Sharing C/C++ Header Files With Assembly Source
      5. 6.6.5 Using Inline Assembly Language
      6. 6.6.6 Modifying Compiler Output
    7. 6.7  Interrupt Handling
      1. 6.7.1 Saving Registers During Interrupts
      2. 6.7.2 Using C/C++ Interrupt Routines
      3. 6.7.3 Using Assembly Language Interrupt Routines
      4. 6.7.4 How to Map Interrupt Routines to Interrupt Vectors
        1.       Example 7. Sample intvecs.asm File
      5. 6.7.5 Using Software Interrupts
      6. 6.7.6 Other Interrupt Information
    8. 6.8  Intrinsic Run-Time-Support Arithmetic and Conversion Routines
      1. 6.8.1 CPSR Register and Interrupt Intrinsics
    9. 6.9  Built-In Functions
    10. 6.10 System Initialization
      1. 6.10.1 Boot Hook Functions for System Pre-Initialization
      2. 6.10.2 Run-Time Stack
      3. 6.10.3 Automatic Initialization of Variables
        1. 6.10.3.1 Zero Initializing Variables
        2. 6.10.3.2 Direct Initialization
        3. 6.10.3.3 Autoinitialization of Variables at Run Time
        4. 6.10.3.4 Autoinitialization Tables
          1. 6.10.3.4.1 Length Followed by Data Format
          2. 6.10.3.4.2 Zero Initialization Format
          3. 6.10.3.4.3 Run Length Encoded (RLE) Format
          4. 6.10.3.4.4 Lempel-Ziv-Storer-Szymanski Compression (LZSS) Format
          5. 6.10.3.4.5 Sample C Code to Process the C Autoinitialization Table
            1.         Example 8. Processing the C Autoinitialization Table
        5. 6.10.3.5 Initialization of Variables at Load Time
        6. 6.10.3.6 Global Constructors
      4. 6.10.4 Initialization Tables
        1.       Example 9. Initialized Variables Defined in C
        2.       Example 10. Initialized Information for Variables Defined in
    11. 6.11 Dual-State Interworking Under TIABI (Deprecated)
      1. 6.11.1 Level of Dual-State Support
      2. 6.11.2 Implementation
        1. 6.11.2.1 Naming Conventions for Entry Points
        2. 6.11.2.2 Indirect Calls
          1.        Example 11. C Code Compiled for 16-BIS State: sum( )
          2.        Example 12. 16-Bit Assembly Program for
          3.        Example 13. C Code Compiled for 32-BIS State: sum( )
          4.        Example 14. 32-Bit Assembly Program for
  8. 7Using 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 Allowable Number of Open Files
      7. 7.1.7 Nonstandard Header Files in the Source Tree
      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
      3. 7.2.3 Device-Driver Level I/O Functions
      4. 7.2.4 Adding a User-Defined Device Driver for C I/O
        1.       Example 1. Mapping Default Streams to Device
      5. 7.2.5 The device Prefix
        1.       Example 2. 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
  9. 8C++ Name Demangler
    1. 8.1 Invoking the C++ Name Demangler
    2. 8.2 Sample Usage of the C++ Name Demangler
      1.      Example 1. C++ Code for calories_in_a_banana
      2.      Example 2. Resulting Assembly for calories_in_a_banana
      3.      Example 3. Result After Running the C++ Name Demangler
  10.   A Glossary
    1.     A.1 Terminology
  11.   B Revision History
    1.     B.1 Recent Revisions
  12. IMPORTANT NOTICE
search No matches found.
  • Full reading width
    • Full reading width
    • Comfortable reading width
    • Expanded reading width
  • Card for each section
  • Card with all content

 

USER'S GUIDE

ARM Optimizing C/C++ Compiler v20.2.0.LTS

Read This First

About This Manual

The ARM Optimizing C/C++ Compiler User's Guide explains how to use the following Texas Instruments Code Generation compiler tools:

  • Compiler
  • Library build utility
  • C++ name demangler

The TI compiler accepts C and C++ code conforming to the International Organization for Standardization (ISO) standards for these languages. The compiler supports the 1989, 1999, and 2011 versions of the C language and the 2014 version of the C++ language.

This user's guide discusses the characteristics of the TI C/C++ compiler. It assumes that you already know how to write C/C++ programs. The C Programming Language (second edition), by Brian W. Kernighan and Dennis M. Ritchie, describes C based on the ISO C standard. You can use the Kernighan and Ritchie (hereafter referred to as K&R) book as a supplement to this manual. References to K&R C (as opposed to ISO C) in this manual refer to the C language as defined in the first edition of Kernighan and Ritchie's The C Programming Language.

Notational Conventions

This document uses the following conventions:

  • Program listings, program examples, and interactive displays are shown in a special typeface. Interactive displays use a bold version of the special typeface to distinguish commands that you enter from items that the system displays (such as prompts, command output, error messages, etc.). Here is a sample of C code:
  • #include <stdio.h> main() { printf("Hello World\n"); }
  • In syntax descriptions, instructions, commands, and directives are in a bold typeface and parameters are in an italic typeface. Portions of a syntax that are in bold should be entered as shown; portions of a syntax that are in italics describe the type of information that should be entered.
  • Square brackets ( [ and ] ) identify an optional parameter. If you use an optional parameter, you specify the information within the brackets. Unless the square brackets are in the bold typeface, do not enter the brackets themselves. The following is an example of a command that has an optional parameter:
  • armcl [options] [filenames] [--run_linker [link_options] [object files]]
  • Braces ( { and } ) indicate that you must choose one of the parameters within the braces; you do not enter the braces themselves. This is an example of a command with braces that are not included in the actual syntax but indicate that you must specify either the --rom_model or --ram_model option:
  • armcl --run_linker  {--rom_model | --ram_model} filenames [--output_file=name.out]
    --library=libraryname
  • In assembler syntax statements, the leftmost column is reserved for the first character of a label or symbol. If the label or symbol is optional, it is usually not shown. If a label or symbol is a required parameter, it is shown starting against the left margin of the box, as in the example below. No instruction, command, directive, or parameter, other than a symbol or label, can begin in the leftmost column.
  • symbol .usect "section name", size in bytes[, alignment]
  • Some directives can have a varying number of parameters. For example, the .byte directive. This syntax is shown as [, ..., parameter].
  • The ARM® 16-bit instruction set is referred to as 16-BIS.
  • The ARM 32-bit instruction set is referred to as 32-BIS.

Related Documentation

You can use the following books to supplement this user's guide:

ANSI X3.159-1989, Programming Language - C (Alternate version of the 1989 C Standard), American National Standards Institute

ISO/IEC 9899:1989, International Standard - Programming Languages - C (The 1989 C Standard), International Organization for Standardization

ISO/IEC 9899:1999, International Standard - Programming Languages - C (The 1999 C Standard), International Organization for Standardization

ISO/IEC 9899:2011, International Standard - Programming Languages - C (The 2011 C Standard), International Organization for Standardization

ISO/IEC 14882-2014, International Standard - Programming Languages - C++ (The 2014 C++ Standard), International Organization for Standardization

The C Programming Language (second edition), by Brian W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, Englewood Cliffs, New Jersey, 1988

The Annotated C++ Reference Manual, Margaret A. Ellis and Bjarne Stroustrup, published by Addison-Wesley Publishing Company, Reading, Massachusetts, 1990

C: A Reference Manual (fourth edition), by Samuel P. Harbison, and Guy L. Steele Jr., published by Prentice Hall, Englewood Cliffs, New Jersey

Programming Embedded Systems in C and C++, by Michael Barr, Andy Oram (Editor), published by O'Reilly & Associates; ISBN: 1565923545, February 1999

Programming in C, Steve G. Kochan, Hayden Book Company

The C++ Programming Language (second edition), Bjarne Stroustrup, published by Addison-Wesley Publishing Company, Reading, Massachusetts, 1990

Tool Interface Standards (TIS) DWARF Debugging Information Format Specification Version 2.0, TIS Committee, 1995

DWARF Debugging Information Format Version 3, DWARF Debugging Information Format Workgroup, Free Standards Group, 2005 (http://dwarfstd.org)

DWARF Debugging Information Format Version 4, DWARF Debugging Information Format Workgroup, Free Standards Group, 2010 (http://dwarfstd.org)

System V ABI specification (http://www.sco.com/developers/gabi/)

ARM C Language Extensions (ACLE) specification (ACLE Version ACLE Q2 2017)

Related Documentation From Texas Instruments

See the following resources for further information about the TI Code Generation Tools:

  • Texas Instruments Wiki: Compiler topics
  • Texas Instruments E2E Community: Compiler forum

You can use the following documents to supplement this user's guide:

    SPNU118ARM Assembly Language Tools User's Guide. Describes the assembly language tools (assembler, linker, and other tools used to develop assembly language code), assembler directives, macros, common object file format, and symbolic debugging directives for the ARM devices.
    SPRAAB5The Impact of DWARF on TI Object Files. Describes the Texas Instruments extensions to the DWARF specification.
    SPRUEX3TI SYS/BIOS Real-time Operating System User's Guide. SYS/BIOS gives application developers the ability to develop embedded real-time software. SYS/BIOS is a scalable real-time kernel. It is designed to be used by applications that require real-time scheduling and synchronization or real-time instrumentation. SYS/BIOS provides preemptive multithreading, hardware abstraction, real-time analysis, and configuration tools.

Trademarks

Code Composer Studio is a registered trademark of Texas Instruments.

ARM is a registered trademark of ARM Limited.

1 Introduction to the Software Development Tools

The ARM® is supported by a set of software development tools, which includes an optimizing C/C++ compiler, an assembler, a linker, and assorted utilities.

This chapter provides an overview of these tools and introduces the features of the optimizing C/C++ compiler. The assembler and linker are discussed in detail in the ARM Assembly Language Tools User's Guide.

1.1 Software Development Tools Overview

Figure 1-1 illustrates the software development flow. The shaded portion of the figure highlights the most common path of software development for C language programs. The other portions are peripheral functions that enhance the development process.

Figure 1-1 ARM Software Development Flowdevelop_flow_pnu151.gif

The following list describes the tools that are shown in Figure 1-1:

  • The compiler accepts C/C++ source code and produces ARM assembly language source code. See Section 2.
  • The assembler translates assembly language source files into machine language relocatable object files. See the ARM Assembly Language Tools User's Guide.
  • The linker combines relocatable object files into a single absolute executable object file. As it creates the executable file, it performs relocation and resolves external references. The linker accepts relocatable object files and object libraries as input. See Section 4 for an overview of the linker. See the ARM Assembly Language Tools User's Guide for details.
  • The archiver allows you to collect a group of files into a single archive file, called a library. The archiver allows you to modify such libraries by deleting, replacing, extracting, or adding members. One of the most useful applications of the archiver is building a library of object files. See the ARM Assembly Language Tools User's Guide.
  • The run-time-support libraries contain the standard ISO C and C++ library functions, compiler-utility functions, floating-point arithmetic functions, and C I/O functions that are supported by the compiler. See Section 7.
  • The library-build utility automatically builds the run-time-support library if compiler and linker options require a custom version of the library. See Section 7.4. Source code for the standard run-time-support library functions for C and C++ is provided in the lib\src subdirectory of the directory where the compiler is installed.

  • The hex conversion utility converts an object file into other object formats. You can download the converted file to an EPROM programmer. See the ARM Assembly Language Tools User's Guide.
  • The absolute lister accepts linked object files as input and creates .abs files as output. You can assemble these .abs files to produce a listing that contains absolute, rather than relative, addresses. Without the absolute lister, producing such a listing would be tedious and would require many manual operations. See the ARM Assembly Language Tools User's Guide.
  • The cross-reference lister uses object files to produce a cross-reference listing showing symbols, their definitions, and their references in the linked source files. See the ARM Assembly Language Tools User's Guide.
  • The C++ name demangler is a debugging aid that converts names mangled by the compiler back to their original names as declared in the C++ source code. As shown in Figure 1-1, you can use the C++ name demangler on the assembly file that is output by the compiler; you can also use this utility on the assembler listing file and the linker map file. See Section 8.
  • The disassembler decodes object files to show the assembly instructions that they represent. See the ARM Assembly Language Tools User's Guide.
  • The main product of this development process is an executable object file that can be executed on a ARM device.

1.2 Compiler Interface

The compiler is a command-line program named armcl. This program can compile, optimize, assemble, and link programs in a single step. Within Code Composer Studio™, the compiler is run automatically to perform the steps needed to build a project.

For more information about compiling a program, see Section 2.1

The compiler has straightforward calling conventions, so you can write assembly and C functions that call each other. For more information about calling conventions, see Section 6.

1.3 ANSI/ISO Standard

The compiler supports the 1989, 1999, and 2011 versions of the C language and the 2014 version of the C++ language. The C and C++ language features in the compiler are implemented in conformance with the following ISO standards:

  • ISO-standard C
  • The C compiler supports the 1989, 1999, and 2011 versions of the C language.

    • C89. Compiling with the --c89 option causes the compiler to conform to the ISO/IEC 9899:1990 C standard, which was previously ratified as ANSI X3.159-1989. The names "C89" and "C90" refer to the same programming language. "C89" is used in this document.
    • C99. Compiling with the --c99 option causes the compiler to conform to the ISO/IEC 9899:1999 C standard.
    • C11. Compiling with the --c11 option causes the compiler to conform to the ISO/IEC 9899:2011 C standard.
    The C language is also described in the second edition of Kernighan and Ritchie's The C Programming Language (K&R).

  • ISO-standard C++
  • The compiler uses the C++14 version of the C++ standard. Previously, C++03 was used. See the C++ Standard ISO/IEC 14882:2014. For a description of unsupported C++ features, see Section 5.2.

  • ISO-standard run-time support
  • The compiler tools come with an extensive run-time library. Library functions conform to the ISO C/C++ library standard unless otherwise stated. The library includes functions for standard input and output, string manipulation, dynamic memory allocation, data conversion, timekeeping, trigonometry, and exponential and hyperbolic functions. Functions for signal handling are not included, because these are target-system specific. For more information, see Section 7.

See Section 5.16 for command line options to select the C or C++ standard your code uses.

1.4 Output Files

The following types of output files are created by the compiler:

  • ELF object files. Executable and Linking Format (ELF) enables supporting modern language features like early template instantiation and exporting inline functions. The ELF format for ARM is part of the Application Binary Interface (ABI) specification, which is documented in the ARM Infocenter.

COFF object files and the legacy TIABI and TI ARM9 ABI modes are not supported in v15.6.0.STS and later versions of the TI Code Generation Tools. If you would like to produce COFF output files, please use v5.2 of the ARM Code Generation Tools and refer to SPNU151J for documentation.

1.5 Utilities

These features are compiler utilities:

  • Library-build utility
  • The library-build utility lets you custom-build object libraries from source for any combination of run-time models. For more information, see Section 7.4.

  • C++ name demangler
  • The C++ name demangler (armdem) is a debugging aid that translates each mangled name it detects in compiler-generated assembly code, disassembly output, or compiler diagnostic messages to its original name found in the C++ source code. For more information, see Section 8.

  • Hex conversion utility
  • For stand-alone embedded applications, the compiler has the ability to place all code and initialization data into ROM, allowing C/C++ code to run from reset. The ELF files output by the compiler can be converted to EPROM programmer data files by using the hex conversion utility, as described in the ARM Assembly Language Tools User's Guide.

2 Using the C/C++ Compiler

The compiler translates your source program into machine language object code that the ARM can execute. Source code must be compiled, assembled, and linked to create an executable file. All of these steps are executed at once by using the compiler.

2.1 About the Compiler

The compiler lets you compile, optimize, assemble, and optionally link in one step. The compiler performs the following steps on one or more source modules:

  • The compiler accepts C/C++ source code and assembly code. It produces object code.
  • You can compile C, C++, and assembly files in a single command. The compiler uses the filename extensions to distinguish between different file types. See Section 2.3.9 for more information.

  • The linker combines object files to create an executable or relinkablean executable file. The link step is optional, so you can compile and assemble many modules independently and link them later. See Section 4 for information about linking the files.

NOTE

Invoking the Linker

By default, the compiler does not invoke the linker. You can invoke the linker by using the --run_linker (-z) compiler option. See Section 4.1.1 for details.

For a complete description of the assembler and the linker, see the ARM Assembly Language Tools User's Guide.

2.2 Invoking the C/C++ Compiler

To invoke the compiler, enter:

armcl[options] [filenames] [--run_linker [link_options] object files]]
armcl Command that runs the compiler and the assembler.
options Options that affect the way the compiler processes input files. The options are listed in Table 2-7 through Table 2-29.
filenames One or more C/C++ source files and assembly language source files.
--run_linker (-z) Option that invokes the linker. The --run_linker option's short form is -z. See Section 4 for more information.
link_options Options that control the linking process.
object files Names of the object files for the linking process.

The arguments to the compiler are of three types:

  • Compiler options
  • Link options
  • Filenames

The --run_linker option indicates linking is to be performed. If the --run_linker option is used, any compiler options must precede the --run_linker option, and all link options must follow the --run_linker option.

Source code filenames must be placed before the --run_linker option. Additional object file filenames can be placed after the --run_linker option.

For example, if you want to compile two files named symtab.c and file.c, assemble a third file named seek.asm, and link to create an executable program called myprogram.out, you will enter:

armcl symtab.c file.c seek.asm --run_linker --library=lnk.cmd --output_file=myprogram.out

2.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 and assembling.

For a help screen summary of the options, enter armcl 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 TI_ARM_C_OPTION environment variable. For a detailed description of the environment variable, see Section 2.4.1.

Table 2-7 through Table 2-29 summarize all options (including link options). Use the references in the tables for more complete descriptions of the options.

Table 2-1 Processor Options

Option Alias Effect Section
--silicon_version={ 4 | 5e | 6 | 6M0 | 7A8 | 7M3 | 7M4 | 7R4 | 7R5 } -mv Selects processor version: ARM V4 (ARM7), ARM V5e (ARM9E), ARM V6 (ARM11), ARM V6M0 (Cortex-M0), ARM V7A8 (Cortex-A8), ARM V7M3 (Cortex-M3), ARM V7M4 (Cortex-M4), ARM V7R4 (Cortex-R4), or ARM V7R5 (Cortex-R5). The default is ARM V4. Section 2.3.4
--code_state={ 16 | 32 } Designates the ARM compilation mode. Section 2.3.4
--float_support={ vfpv2 | vfpv3 | vfpv3d16 | fpv4spd16 | none ) Generates vector floating-point (VFP) coprocessor instructions. Section 2.14
--little_endian or --endian={ big | little } -me Designates little-endian code. The default is big-endian. Section 2.3.4

Table 2-2 Optimization Options(1)

Option Alias Effect Section
--opt_level=off Disables all optimization. Section 3.1
--opt_level=n -On Level 0 (-O0) optimizes register usage only.
Level 1 (-O1) uses Level 0 optimizations and optimizes locally.
Level 2 (-O2) uses Level 1 optimizations and optimizes globally.
Level 3 (-O3) uses Level 2 optimizations and optimizes the file (default if option not used).
Level 4 (-O4) uses Level 3 optimizations and performs link-time optimization.
Section 3.1, Section 3.3, Section 3.6
--opt_for_speed[=n] -mf Controls the tradeoff between size and speed (0-5 range). If this option is specified without n, the default value is 4. If this option is not specified, the default setting is 1. Section 3.2
(1) Note: Machine-specific options (see Table 2-13) can also affect optimization.

Table 2-3 Advanced Optimization Options(1)

Option Alias Effect Section
--auto_inline=[size] -oi Sets automatic inlining size (--opt_level=3 only). If size is not specified, the default is 1. Section 3.5
--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 3.4.1
--disable_inlining Prevents any inlining from occurring. Section 2.11
--fp_mode={relaxed|strict} Enables or disables relaxed floating-point mode. Section 2.3.3
--fp_reassoc={on|off} Enables or disables the reassociation of floating-point arithmetic. Section 2.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 3.3.1
--optimizer_interlist -os Interlists optimizer comments with assembly statements. Section 3.11
--program_level_compile -pm Combines source files to perform program-level optimization. Section 3.4
--sat_reassoc={on|off} Enables or disables the reassociation of saturating arithmetic. Default is --sat_reassoc=off. Section 2.3.3
--aliased_variables -ma Indicates that a specific aliasing technique is used. Section 3.9
(1) Note: Machine-specific options (see Table 2-13) can also affect optimization.

Table 2-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 2.3.5
Section 3.12
--symdebug:dwarf_version=2|3|4 Specifies the DWARF format version. Section 2.3.5
--symdebug:none Disables all symbolic debugging. Section 2.3.5
Section 3.12
--symdebug:skeletal (Deprecated; has no effect.)

Table 2-5 Include Options

Option Alias Effect Section
--include_path=directory -I Adds the specified directory to the #include search path. Section 2.5.2.1
--preinclude=filename Includes filename at the beginning of compilation. Section 2.3.3

Table 2-6 ULP Advisor Options

Option Alias Effect Section
--advice:power[={all|none|rulespec}] Enables checking the specified ULP Advisor rules. (Default is all.) Section 2.3.3
--advice:power_severity={error|
    warning|remark|suppress}
Sets the diagnostic severity for ULP Advisor rules. Section 2.3.3

Table 2-7 Control Options

Option Alias Effect Section
--compile_only -c Disables linking (negates --run_linker). Section 4.1.3
--help -h Prints (on the standard output device) a description of the options understood by the compiler. Section 2.3.2
--run_linker -z Causes the linker to be invoked from the compiler command line. Section 2.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 2.3.2

Table 2-8 Language Options

Option Alias Effect Section
--c89 Processes C files according to the ISO C89 standard. Section 5.16
--c99 Processes C files according to the ISO C99 standard. Section 5.16
--c11 Processes C files according to the ISO C11 standard. Section 5.16
--c++14 Processes C++ files according to the ISO C++14 standard.
The --c++03 option has been deprecated.
Section 5.16
--cpp_default -fg Processes all source files with a C extension as C++ source files. Section 2.3.7
--enum_type={int|packed} Designates the underlying type of an enumeration type. Section 2.3.4
--exceptions Enables C++ exception handling. Section 5.8
--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 2.3.3
--gen_cross_reference -px Generates a cross-reference listing file (.crl). Section 2.9
--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 2.3.4
--plain_char={signed|unsigned} -mc Specifies how to treat plain chars, default is unsigned. Section 2.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 2.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.16.3
--rtti -rtti Enables C++ run-time type information (RTTI). –-
--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.16.3
--wchar_t={32|16} Sets the size of the C/C++ type wchar_t. Default is 16 bits. Section 2.3.4

Table 2-9 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 2.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 2.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 2.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 2.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 2.5.6
--preproc_with_compile -ppa Continues compilation after preprocessing with any of the -pp<x> options that normally disable compilation. Section 2.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 2.5.7

Table 2-10 Predefined Macro Options

Option Alias Effect Section
--define=name[=def] -D Predefines name. Section 2.3.2
--undefine=name -U Undefines name. Section 2.3.2

Table 2-11 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 2.7.1
--diag_remark=num -pdsr Categorizes the diagnostic identified by num as a remark. Section 2.7.1
--diag_suppress=num -pds Suppresses the diagnostic identified by num. Section 2.7.1
--diag_warning=num -pdsw Categorizes the diagnostic identified by num as a warning. Section 2.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 2.7.1
--emit_warnings_as_errors -pdew Treat warnings as errors. Section 2.7.1
--gen_func_info_listing Generate user information file (.aux). Section 2.3.2
--issue_remarks -pdr Issues remarks (non-serious warnings). Section 2.7.1
--no_warnings -pdw Suppresses diagnostic warnings (errors are still issued). Section 2.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 2.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 2.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 2.7.1

Table 2-12 Supplemental Information Options

Option Alias Effect Section
--gen_preprocessor_listing -pl Generates a raw listing file (.rl). Section 2.10
--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 2.7.1

Table 2-13 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 2.3.4
--embedded_constants={on|off} Controls whether compiler embeds constants in functions. Section 2.3.4
--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. The default is on. Section 4.2.2
--global_register={r5|r6|r9} -rr Disallows use of rx=[5,6,9] by the compiler. Section 2.3.4
-neon Enables support for the Cortex-A8 Neon SIMD instruction set. Section 2.3.4
--ramfunc={on|off} If set to on, specifies that all functions should be placed in the .TI.ramfunc section, which is placed in RAM. Section 2.3.4
--unaligned_access={on|off} Controls generation of unaligned accesses. Section 2.3.4
--use_dead_funcs_list [=fname] Places each function listed in the file in a separate section. Section 2.3.4

Table 2-14 Entry/Exit Hook Options

Option Alias Effect Section
--entry_hook[=name] Enables entry hooks. Section 2.15
--entry_parm={none|name|
    address}
Specifies the parameters to the function to the --entry_hook option. Section 2.15
--exit_hook[=name] Enables exit hooks. Section 2.15
--exit_parm={none|name|address} Specifies the parameters to the function to the --exit_hook option. Section 2.15
--remove_hooks_when_inlining Removes entry/exit hooks for auto-inlined functions. Section 2.15

Table 2-15 Feedback Options

Option Alias Effect Section
--analyze=codecov Generate analysis info from profile data. Section 3.8.2.2
--analyze_only Only generate analysis. Section 3.8.2.2
--gen_profile_info Generates instrumentation code to collect profile information. Section 3.7.1.3
--use_profile_info=file1[, file2,...] Specifies the profile information file(s). Section 3.7.1.3

Table 2-16 Assembler Options

Option Alias Effect Section
--keep_asm -k Keeps the assembly language (.asm) file. Section 2.3.11
--asm_listing -al Generates an assembly listing file. Section 2.3.11
--c_src_interlist -ss Interlists C source and assembly statements. Section 2.12
Section 3.11
--src_interlist -s Interlists optimizer comments (if available) and assembly source statements; otherwise interlists C and assembly source statements. Section 2.3.2
--absolute_listing -aa Enables absolute listing. Section 2.3.11
--asm_define=name[=def] -ad Sets the name symbol. Section 2.3.11
--asm_dependency -apd Performs preprocessing; lists only assembly dependencies. Section 2.3.11
--asm_includes -api Performs preprocessing; lists only included #include files. Section 2.3.11
--asm_undefine=name -au Undefines the predefined constant name. Section 2.3.11
--code_state={16|32} Begins assembling instructions as 16- or 32-bit instructions. Section 2.3.11
--asm_listing_cross_reference -ax Generates the cross-reference file. Section 2.3.11
--include_file=filename -ahi Includes the specified file for the assembly module. Section 2.3.11

Table 2-17 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 2.3.7
--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 2.3.7
--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 2.3.7
--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 2.3.7

Table 2-18 Directory Specifier Options

Option Alias Effect Section
--abs_directory=directory -fb Specifies an absolute listing file directory. By default, the compiler uses the object file directory. Section 2.3.10
--asm_directory=directory -fs Specifies an assembly file directory. By default, the compiler uses the current directory. Section 2.3.10
--list_directory=directory -ff Specifies an assembly listing file and cross-reference listing file directory By default, the compiler uses the object file directory. Section 2.3.10
--obj_directory=directory -fr Specifies an object file directory. By default, the compiler uses the current directory. Section 2.3.10
--output_file=filename -fe Specifies a compilation output file name; can override --obj_directory. Section 2.3.10
--pp_directory=dir Specifies a preprocessor file directory. By default, the compiler uses the current directory. Section 2.3.10
--temp_directory=directory -ft Specifies a temporary file directory. By default, the compiler uses the current directory. Section 2.3.10

Table 2-19 Default File Extensions Options

Option Alias Effect Section
--asm_extension=[.]extension -ea Sets a default extension for assembly source files.

Section 2.3.9
--c_extension=[.]extension -ec Sets a default extension for C source files. Section 2.3.9
--cpp_extension=[.]extension -ep Sets a default extension for C++ source files. Section 2.3.9
--listing_extension=[.]extension -es Sets a default extension for listing files. Section 2.3.9
--obj_extension=[.]extension -eo Sets a default extension for object files. Section 2.3.9

Table 2-20 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 2.3.2

Table 2-21 MISRA-C 2004 Options

Option Alias Effect Section
--check_misra[={all|required|
    advisory|none|rulespec}]
Enables checking of the specified MISRA-C:2004 rules. Default is all. Section 2.3.3
--misra_advisory={error|warning|
    remark|suppress}
Sets the diagnostic severity for advisory MISRA-C:2004 rules. Section 2.3.3
--misra_required={error|warning|
    remark|suppress}
Sets the diagnostic severity for required MISRA-C:2004 rules. Section 2.3.3

2.3.1 Linker Options

The following tables list the linker options. See Section 4 of this document and the ARM Assembly Language Tools User's Guide for details on these options.

Table 2-22 Linker Basic Options

Option Alias Description
--run_linker -z Enables linking.
--output_file=file -o Names the executable output file. The default filename is a .out file.
--map_file=file -m Produces a map or listing of the input and output sections, including holes, and places the listing in file.
--stack_size=size [-]-stack Sets C system stack size to sizebytes and defines a global symbol that specifies the stack size. Default = 2K bytes.
--heap_size=size [-]-heap Sets heap size (for the dynamic memory allocation in C) to sizebytes and defines a global symbol that specifies the heap size. Default = 2K bytes.

Table 2-23 File Search Path Options

Option Alias Description
--library=file -l Names an archive library or link command file as linker input.
--disable_auto_rts Disables the automatic selection of a run-time-support library. See Section 4.3.1.1.
--priority -priority Satisfies unresolved references by the first library that contains a definition for that symbol.
--reread_libs -x Forces rereading of libraries, which resolves back references.
--search_path=pathname -I Alters library-search algorithms to look in a directory named with pathname before looking in the default location. This option must appear before the --library option.

Table 2-24 Command File Preprocessing Options

Option Alias Description
--define=name=value Predefines name as a preprocessor macro.
--undefine=name Removes the preprocessor macro name.
--disable_pp Disables preprocessing for command files.

Table 2-25 Diagnostic Message Options

Option Alias Description
--diag_error=num Categorizes the diagnostic identified by num as an error.
--diag_remark=num Categorizes the diagnostic identified by num as a remark.
--diag_suppress=num Suppresses the diagnostic identified by num.
--diag_warning=num Categorizes the diagnostic identified by num as a warning.
--display_error_number Displays a diagnostic's identifiers along with its text.
--emit_references:file[=file] Emits a file containing section information. The information includes section size, symbols defined, and references to symbols.
--emit_warnings_as_errors -pdew Treat warnings as errors.
--issue_remarks Issues remarks (non-serious warnings).
--no_demangle Disables demangling of symbol names in diagnostic messages.
--no_warnings Suppresses diagnostic warnings (errors are still issued).
--set_error_limit=count Sets the error limit to count. The linker abandons linking after this number of errors. (The default is 100.)
--verbose_diagnostics Provides verbose diagnostic messages that display the original source with line-wrap.
--warn_sections -w Displays a message when an undefined output section is created.

Table 2-26 Linker Output Options

Option Alias Description
--absolute_exe -a Produces an absolute, executable object file. This is the default; if neither --absolute_exe nor --relocatable is specified, the linker acts as if --absolute_exe were specified.
--ecc={ on | off } Enable linker-generated Error Correcting Codes (ECC). The default is off.
--ecc:data_error Inject specified errors into the output file for testing.
--ecc:ecc_error Inject specified errors into the Error Correcting Code (ECC) for testing.
--generate_dead_funcs_list Writes a list of the dead functions that were removed by the linker to file fname.
--mapfile_contents=attribute Controls the information that appears in the map file.
--relocatable -r Produces a nonexecutable, relocatable output object file.
--rom Creates a ROM object.
--run_abs -abs Produces an absolute listing file.
--xml_link_info=file Generates a well-formed XML file containing detailed information about the result of a link.

Table 2-27 Symbol Management Options

Option Alias Description
--entry_point=symbol -e Defines a global symbol that specifies the primary entry point for the executable object file.
--globalize=pattern Changes the symbol linkage to global for symbols that match pattern.
--hide=pattern Hides symbols that match the specified pattern.
--localize=pattern Make the symbols that match the specified pattern local.
--make_global=symbol -g Makes symbol global (overrides -h).
--make_static -h Makes all global symbols static.
--no_symtable -s Strips symbol table information and line number entries from the executable object file.
--retain Retains a list of sections that otherwise would be discarded.
--scan_libraries -scanlibs Scans all libraries for duplicate symbol definitions.
--symbol_map=refname=defname Specifies a symbol mapping; references to the refname symbol are replaced with references to the defname symbol. The --symbol_map option is supported when used with --opt_level=4.

--undef_sym=symbol -u Adds symbol to the symbol table as an unresolved symbol.
--unhide=pattern Excludes symbols that match the specified pattern from being hidden.

Table 2-28 Run-Time Environment Options

Option Alias Description
--arg_size=size --args Reserve size bytes for the argc/argv memory area.
--cinit_hold_wdt={on|off} Link in an RTS auto-initialization routine that either holds (on) or does not hold (off) the watchdog timer during cinit auto-initialization. See Section 4.3.3.
-be32 Forces the linker to generate BE-32 object code.
-be8 Forces the linker to generate BE-8 object code.
--cinit_compression[=type] Specifies the type of compression to apply to the C auto initialization data. The default if this option is specified with no type is lzss for Lempel-Ziv-Storer-Szymanski compression.
--copy_compression[=type] Compresses data copied by linker copy tables. The default if this option is specified with no type is lzss for Lempel-Ziv-Storer-Szymanski compression.
--fill_value=value -f Sets default fill value for holes within output sections
--ram_model -cr Initializes variables at load time. See Section 4.3.5 for details.
--rom_model -c Autoinitializes variables at run time. See Section 4.3.5 for details.
--trampolines[=off|on] Generates far call trampolines (argument is optional, is "on" by default).

Table 2-29 Miscellaneous Options

Option Alias Description
--compress_dwarf[=off|on] Aggressively reduces the size of DWARF information from input object files. Default is on.
--linker_help [-]-help Displays information about syntax and available options.
--minimize_trampolines Places sections to minimize number of far trampolines required.
--preferred_order=function Prioritizes placement of functions.
--strict_compatibility[=off|on] Performs more conservative and rigorous compatibility checking of input object files. Default is on.
--trampoline_min_spacing When trampoline reservations are spaced more closely than the specified limit, tries to make them adjacent.
--unused_section_elimination[=off|on] Eliminates sections that are not needed in the executable module. Default is on.
--zero_init=[off|on] Controls preinitialization of uninitialized variables. Default is on. Always off if --ram_model is used.

2.3.2 Frequently Used Options

Following are detailed descriptions of options that you will probably use frequently:

--c_src_interlist Invokes the interlist feature, which interweaves original C/C++ source with compiler-generated assembly language. The interlisted C statements may appear to be out of sequence. You can use the interlist feature with the optimizer by combining the --optimizer_interlist and --c_src_interlist options. See Section 3.11. The --c_src_interlist option can have a negative performance and/or code size impact.
--cmd_file=filename Appends the contents of a file to the option set. You can use this option to avoid limitations on command line length or C style comments imposed by the host operating system. Use a # or ; at the beginning of a line in the command file to include comments. You can also include comments by delimiting them with /* and */. To specify options, surround hyphens with quotation marks. For example, "--"quiet.

You can use the --cmd_file option multiple times to specify multiple files. For instance, the following indicates that file3 should be compiled as source and file1 and file2 are --cmd_file files:

armcl --cmd_file=file1 --cmd_file=file2 file3
--compile_only Suppresses the linker and overrides the --run_linker option, which specifies linking. The --compile_only option's short form is -c. Use this option when you have --run_linker specified in the TI_ARM_C_OPTION environment variable and you do not want to link. See Section 4.1.3.
--define=name[=def] Predefines the constant name for the preprocessor. This is equivalent to inserting #define name def at the top of each C source file. If the optional[=def] is omitted, the name is set to 1. The --define option's short form is -D.

If you want to define a quoted string and keep the quotation marks, do one of the following:

  • For Windows, use --define=name="\"string def\"". For example, --define=car="\"sedan\""
  • For UNIX, use --define=name='"string def"'. For example, --define=car='"sedan"'
  • For Code Composer Studio, enter the definition in a file and include that file with the --cmd_file option.

--gen_func_info_listing Generates a user information file with a .aux file extension. The file contains linker call graph information on a per-file level.
--help Displays the syntax for invoking the compiler and lists available options. If the --help option is followed by another option or phrase, detailed information about the option or phrase is displayed. For example, to see information about debugging options use --help debug.
--include_path=directory Adds directory to the list of directories that the compiler searches for #include files. The --include_path option's short form is -I. You can use this option several times to define several directories; be sure to separate the --include_path options with spaces. If you do not specify a directory name, the preprocessor ignores the --include_path option. See Section 2.5.2.1.
--keep_asm Retains the assembly language output from the compiler or assembly optimizer. Normally, the compiler deletes the output assembly language file after assembly is complete. The --keep_asm option's short form is -k.
--quiet Suppresses banners and progress information from all the tools. Only source filenames and error messages are output. The --quiet option's short form is -q.
--run_linker Runs the linker on the specified object files. The --run_linker option and its parameters follow all other options on the command line. All arguments that follow --run_linker are passed to the linker. The --run_linker option's short form is -z. See Section 4.1.
--skip_assembler Compiles only. The specified source files are compiled but not assembled or linked. The --skip_assembler option's short form is -n. This option overrides --run_linker. The output is assembly language output from the compiler.
--src_interlist Invokes the interlist feature, which interweaves optimizer comments or C/C++ source with assembly source. If the optimizer is invoked (--opt_level=n option), optimizer comments are interlisted with the assembly language output of the compiler, which may rearrange code significantly. If the optimizer is not invoked, C/C++ source statements are interlisted with the assembly language output of the compiler, which allows you to inspect the code generated for each C/C++ statement. The --src_interlist option implies the --keep_asm option. The --src_interlist option's short form is -s.
--tool_version Prints the version number for each tool in the compiler. No compiling occurs.
--undefine=name Undefines the predefined constant name. This option overrides any --define options for the specified constant. The --undefine option's short form is -U.
--verbose Displays progress information and toolset version while compiling. Resets the --quiet option.

 

Texas Instruments

© Copyright 1995-2025 Texas Instruments Incorporated. All rights reserved.
Submit documentation feedback | IMPORTANT NOTICE | Trademarks | Privacy policy | Cookie policy | Terms of use | Terms of sale