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