SPRUI04F
july 2015 – april 2023
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
Getting Started with the Code Generation Tools
2.1
How Code Composer Studio Projects Use the Compiler
2.2
Compiling from the Command Line
3
Using the C/C++ Compiler
3.1
About the Compiler
3.2
Invoking the C/C++ Compiler
3.3
Changing the Compiler's Behavior with Options
3.3.1
Linker Options
3.3.2
Frequently Used Options
3.3.3
Miscellaneous Useful Options
3.3.4
Run-Time Model Options
3.3.5
Selecting Target CPU Version (--silicon_version Option)
3.3.6
Symbolic Debugging and Profiling Options
3.3.7
Specifying Filenames
3.3.8
Changing How the Compiler Interprets Filenames
3.3.9
Changing How the Compiler Processes C Files
3.3.10
Changing How the Compiler Interprets and Names Extensions
3.3.11
Specifying Directories
3.3.12
Assembler Options
3.4
Controlling the Compiler Through Environment Variables
3.4.1
Setting Default Compiler Options (C6X_C_OPTION)
3.4.2
Naming One or More Alternate Directories (C6X_C_DIR)
3.5
Controlling the Preprocessor
3.5.1
Predefined Macro Names
3.5.2
The Search Path for #include Files
3.5.2.1
Adding a Directory to the #include File Search Path (--include_path Option)
3.5.3
Support for the #warning and #warn Directives
3.5.4
Generating a Preprocessed Listing File (--preproc_only Option)
3.5.5
Continuing Compilation After Preprocessing (--preproc_with_compile Option)
3.5.6
Generating a Preprocessed Listing File with Comments (--preproc_with_comment Option)
3.5.7
Generating Preprocessed Listing with Line-Control Details (--preproc_with_line Option)
3.5.8
Generating Preprocessed Output for a Make Utility (--preproc_dependency Option)
3.5.9
Generating a List of Files Included with #include (--preproc_includes Option)
3.5.10
Generating a List of Macros in a File (--preproc_macros Option)
3.6
Passing Arguments to main()
3.7
Understanding Diagnostic Messages
3.7.1
Controlling Diagnostic Messages
3.7.2
How You Can Use Diagnostic Suppression Options
3.8
Other Messages
3.9
Generating Cross-Reference Listing Information (--gen_cross_reference_listing Option)
3.10
Generating a Raw Listing File (--gen_preprocessor_listing Option)
3.11
Using Inline Function Expansion
3.11.1
Inlining Intrinsic Operators
3.11.2
Inlining Restrictions
3.11.3
Unguarded Definition-Controlled Inlining
3.11.3.1
Using the Inline Keyword
3.11.4
Guarded Inlining and the _INLINE Preprocessor Symbol
3.11.4.1
Header File string.h
3.11.4.2
Library Definition File
3.12
Interrupt Flexibility Options (--interrupt_threshold Option)
3.13
Using Interlist
3.14
Generating and Using Performance Advice
3.15
About the Application Binary Interface
3.16
Enabling Entry Hook and Exit Hook Functions
4
Optimizing Your Code
4.1
Invoking Optimization
4.2
Controlling Code Size Versus Speed
4.3
Performing File-Level Optimization (--opt_level=3 option)
4.3.1
Creating an Optimization Information File (--gen_opt_info Option)
4.4
Program-Level Optimization (--program_level_compile and --opt_level=3 options)
4.4.1
Controlling Program-Level Optimization (--call_assumptions Option)
4.4.2
Optimization Considerations When Mixing C/C++ and Assembly
4.5
Automatic Inline Expansion (--auto_inline Option)
4.6
Optimizing Software Pipelining
4.6.1
Turn Off Software Pipelining (--disable_software_pipeline Option)
4.6.2
Software Pipelining Information
4.6.2.1
Software Pipelining Information
4.6.2.2
Software Pipelining Information Terms
4.6.2.3
Loop Disqualified for Software Pipelining Messages
4.6.2.4
Pipeline Failure Messages
4.6.2.5
Register Usage Table Generated by the --debug_software_pipeline Option
4.6.3
Collapsing Prologs and Epilogs for Improved Performance and Code Size
4.6.3.1
Speculative Execution
4.6.3.2
Selecting the Best Threshold Value
4.7
Redundant Loops
4.8
Utilizing the Loop Buffer Using SPLOOP
4.9
Reducing Code Size (--opt_for_space (or -ms) Option)
4.10
Using Feedback Directed Optimization
4.10.1
Feedback Directed Optimization
4.10.1.1
Phase 1 -- Collect Program Profile Information
4.10.1.2
Phase 2 -- Use Application Profile Information for Optimization
4.10.1.3
Generating and Using Profile Information
4.10.1.4
Example Use of Feedback Directed Optimization
4.10.1.5
The .ppdata Section
4.10.1.6
Feedback Directed Optimization and Code Size Tune
4.10.1.7
Instrumented Program Execution Overhead
4.10.1.8
Invalid Profile Data
4.10.2
Profile Data Decoder
4.10.3
Feedback Directed Optimization API
4.10.4
Feedback Directed Optimization Summary
4.11
Using Profile Information to Get Better Program Cache Layout and Analyze Code Coverage
4.11.1
Background and Motivation
4.11.2
Code Coverage
4.11.2.1
Phase1 -- Collect Program Profile Information
4.11.2.2
Phase 2 -- Generate Code Coverage Reports
4.11.3
What Performance Improvements Can You Expect to See?
4.11.3.1
Evaluating L1P Cache Performance
4.11.4
Program Cache Layout Related Features and Capabilities
4.11.4.1
Path Profiler
4.11.4.2
Analysis Options
4.11.4.3
Environment Variables
4.11.4.4
Program Cache Layout Tool, clt6x
4.11.4.5
Linker
4.11.4.6
Linker Command File Operator unordered()
4.11.5
Program Instruction Cache Layout Development Flow
4.11.5.1
Gather Dynamic Profile Information
4.11.5.2
Generate Preferred Function Order from Dynamic Profile Information
4.11.5.3
Utilize Preferred Function Order in Re-Build of Application
4.11.6
Comma-Separated Values (CSV) Files with Weighted Call Graph (WCG) Information
4.11.7
Linker Command File Operator - unordered()
4.11.7.1
Output Section for unordered() Operator
124
4.11.7.2
Generated Linker Map File for
4.11.7.3
About Dot (.) Expressions in the Presence of unordered()
4.11.7.3.1
Respecting Position of a . Expression
128
4.11.7.4
GROUPs and UNIONs
4.11.7.4.1
Applying unordered() to GROUPs
131
4.11.8
Things to be Aware of
4.12
Indicating Whether Certain Aliasing Techniques Are Used
4.12.1
Use the --aliased_variables Option When Certain Aliases are Used
4.12.2
Use the --no_bad_aliases Option to Indicate That These Techniques Are Not Used
4.12.3
Using the --no_bad_aliases Option With the Assembly Optimizer
4.13
Prevent Reordering of Associative Floating-Point Operations
4.14
Use Caution With asm Statements in Optimized Code
4.15
Using Performance Advice to Optimize Your Code
4.15.1
Advice #27000
4.15.2
Advice #27001 Increase Optimization Level
4.15.3
Advice #27002 Do not turn off software pipelining
4.15.4
Advice #27003 Avoid compiling with debug options
4.15.5
Advice #27004 No Performance Advice generated
4.15.6
Advice #30000 Prevent Loop Disqualification due to call
4.15.7
Advice #30001 Prevent Loop Disqualification due to rts-call
4.15.8
Advice #30002 Prevent Loop Disqualification due to asm statement
4.15.9
Advice #30003 Prevent Loop Disqualification due to complex condition
4.15.10
Advice #30004 Prevent Loop Disqualification due to switch statement
4.15.11
Advice #30005 Prevent Loop Disqualification due to arithmetic operation
4.15.12
Advice #30006 Prevent Loop Disqualification due to call(2)
4.15.13
Advice #30007 Prevent Loop Disqualification due to rts-call(2)
4.15.14
Advice #30008 Improve Loop; Qualify with restrict
4.15.15
Advice #30009 Improve Loop; Add MUST_ITERATE pragma
4.15.16
Advice #30010 Improve Loop; Add MUST_ITERATE pragma(2)
4.15.17
Advice #30011 Improve Loop; Add _nasssert()
4.16
Using the Interlist Feature With Optimization
4.17
Debugging and Profiling Optimized Code
4.17.1
Profiling Optimized Code
4.18
What Kind of Optimization Is Being Performed?
4.18.1
Cost-Based Register Allocation
4.18.2
Alias Disambiguation
4.18.3
Branch Optimizations and Control-Flow Simplification
4.18.4
Data Flow Optimizations
4.18.5
Expression Simplification
4.18.6
Inline Expansion of Functions
4.18.7
Function Symbol Aliasing
4.18.8
Induction Variables and Strength Reduction
4.18.9
Loop-Invariant Code Motion
4.18.10
Loop Rotation
4.18.11
Vectorization (SIMD)
4.18.12
Instruction Scheduling
4.18.13
Register Variables
4.18.14
Register Tracking/Targeting
4.18.15
Software Pipelining
5
Using the Assembly Optimizer
5.1
Code Development Flow to Increase Performance
5.2
About the Assembly Optimizer
5.3
What You Need to Know to Write Linear Assembly
5.3.1
Linear Assembly Source Statement Format
5.3.2
Register Specification for Linear Assembly
5.3.2.1
Linear Assembly Code for Computing a Dot Product
183
5.3.2.2
C Code for Computing a Dot Product
185
5.3.2.3
Specifying a Register Pair
187
5.3.2.4
Specifying a Register Quad (C6600 Only)
189
5.3.3
Functional Unit Specification for Linear Assembly
5.3.4
Using Linear Assembly Source Comments
5.3.4.1
Lmac Function Code Showing Comments
5.3.5
Assembly File Retains Your Symbolic Register Names
5.4
Assembly Optimizer Directives
.call
.circ
.cproc/.endproc
.map
.mdep
.mptr
.no_mdep
.pref
.proc/.endproc
.reg
.rega/.regb
.reserve
.return
.trip
.volatile
5.4.1
Instructions That Are Not Allowed in Procedures
5.5
Avoiding Memory Bank Conflicts With the Assembly Optimizer
5.5.1
Preventing Memory Bank Conflicts
5.5.1.1
Load and Store Instructions That Specify Memory Bank Information
5.5.2
A Dot Product Example That Avoids Memory Bank Conflicts
5.5.2.1
C Code for Dot Product
5.5.2.2
Linear Assembly for Dot Product
5.5.2.3
Dot Product Software-Pipelined Kernel
218
5.5.2.4
Dot Product From Unrolled to Prevent Memory Bank Conflicts
220
5.5.2.5
Unrolled Dot Product Kernel From
222
5.5.3
Memory Bank Conflicts for Indexed Pointers
5.5.3.1
Using .mptr for Indexed Pointers
5.5.4
Memory Bank Conflict Algorithm
5.6
Memory Alias Disambiguation
5.6.1
How the Assembly Optimizer Handles Memory References (Default)
5.6.2
Using the --no_bad_aliases Option to Handle Memory References
5.6.3
Using the .no_mdep Directive
5.6.4
Using the .mdep Directive to Identify Specific Memory Dependencies
5.6.4.1
Annotating a Memory Reference
232
5.6.4.2
Software Pipeline Using .mdep ld1, st1
234
5.6.4.3
Software Pipeline Using .mdep st1, ld1 and .mdep ld1, st1
236
5.6.5
Memory Alias Examples
6
Linking C/C++ Code
6.1
Invoking the Linker Through the Compiler (-z Option)
6.1.1
Invoking the Linker Separately
6.1.2
Invoking the Linker as Part of the Compile Step
6.1.3
Disabling the Linker (--compile_only Compiler Option)
6.2
Linker Code Optimizations
6.2.1
Conditional Linking
6.2.2
Generating Function Subsections (--gen_func_subsections Compiler Option)
6.2.3
Generating Aggregate Data Subsections (--gen_data_subsections Compiler Option)
6.3
Controlling the Linking Process
6.3.1
Including the Run-Time-Support Library
6.3.1.1
Automatic Run-Time-Support Library Selection
6.3.1.1.1
Using the --issue_remarks Option
6.3.1.2
Manual Run-Time-Support Library Selection
6.3.1.3
Library Order for Searching for Symbols
6.3.2
Run-Time Initialization
6.3.3
Global Object Constructors
6.3.4
Specifying the Type of Global Variable Initialization
6.3.5
Specifying Where to Allocate Sections in Memory
6.3.6
A Sample Linker Command File
7
C/C++ Language Implementation
7.1
Characteristics of TMS320C6000 C
7.1.1
Implementation-Defined Behavior
7.2
Characteristics of TMS320C6000 C++
7.3
Data Types
7.3.1
Size of Enum Types
7.3.2
Vector Data Types
7.4
File Encodings and Character Sets
7.5
Keywords
7.5.1
The complex Keyword
7.5.2
The const Keyword
7.5.3
The __cregister Keyword
7.5.3.1
Define and Use Control Registers
7.5.4
The __interrupt Keyword
7.5.5
The __near and __far Keywords
7.5.5.1
Near and Far Data Objects
7.5.5.2
Near and Far Function Calls
7.5.6
The restrict Keyword
7.5.7
The volatile Keyword
7.6
C++ Exception Handling
7.7
Register Variables and Parameters
7.8
The __asm Statement
7.9
Pragma Directives
7.9.1
The CALLS Pragma
7.9.2
The CODE_ALIGN Pragma
7.9.3
The CODE_SECTION Pragma
7.9.4
The DATA_ALIGN Pragma
7.9.5
The DATA_MEM_BANK Pragma
7.9.5.1
Using the DATA_MEM_BANK Pragma
7.9.6
The DATA_SECTION Pragma
7.9.6.1
Using the DATA_SECTION Pragma C Source File
7.9.6.2
Using the DATA_SECTION Pragma C++ Source File
7.9.6.3
Using the DATA_SECTION Pragma Assembly Source File
7.9.7
The Diagnostic Message Pragmas
7.9.8
The FORCEINLINE Pragma
7.9.9
The FORCEINLINE_RECURSIVE Pragma
7.9.10
The FUNC_ALWAYS_INLINE Pragma
7.9.11
The FUNC_CANNOT_INLINE Pragma
7.9.12
The FUNC_EXT_CALLED Pragma
7.9.13
The FUNC_INTERRUPT_THRESHOLD Pragma
7.9.14
The FUNC_IS_PURE Pragma
7.9.15
The FUNC_IS_SYSTEM Pragma
7.9.16
The FUNC_NEVER_RETURNS Pragma
7.9.17
The FUNC_NO_GLOBAL_ASG Pragma
7.9.18
The FUNC_NO_IND_ASG Pragma
7.9.19
The FUNCTION_OPTIONS Pragma
7.9.20
The INTERRUPT Pragma
7.9.21
The LOCATION Pragma
7.9.22
The MUST_ITERATE Pragma
7.9.22.1
The MUST_ITERATE Pragma Syntax
7.9.22.2
Using MUST_ITERATE to Expand Compiler Knowledge of Loops
7.9.23
The NMI_INTERRUPT Pragma
7.9.24
The NOINIT and PERSISTENT Pragmas
7.9.25
The NOINLINE Pragma
7.9.26
The NO_HOOKS Pragma
7.9.27
The once Pragma
7.9.28
The pack Pragma
7.9.29
The PROB_ITERATE Pragma
7.9.30
The RETAIN Pragma
7.9.31
The SET_CODE_SECTION and SET_DATA_SECTION Pragmas
7.9.32
The STRUCT_ALIGN Pragma
7.9.33
The UNROLL Pragma
7.10
The _Pragma Operator
7.11
Application Binary Interface
7.12
Object File Symbol Naming Conventions (Linknames)
7.13
Changing the ANSI/ISO C/C++ Language Mode
7.13.1
C99 Support (--c99)
7.13.2
C11 Support (--c11)
7.13.3
Strict ANSI Mode and Relaxed ANSI Mode (--strict_ansi and --relaxed_ansi)
7.14
GNU and Clang Language Extensions
7.14.1
Extensions
7.14.2
Function Attributes
7.14.3
For Loop Attributes
7.14.4
Variable Attributes
7.14.5
Type Attributes
7.14.6
Built-In Functions
7.15
Operations and Functions for Vector Data Types
7.15.1
Vector Literals and Concatenation
7.15.2
Unary and Binary Operators for Vectors
7.15.3
Swizzle Operators for Vectors
7.15.4
Conversion Functions for Vectors
7.15.5
Re-Interpretation Functions for Vectors
7.15.6
Using printf() with Vectors
7.15.7
Built-In Vector Functions
8
Run-Time Environment
8.1
Memory Model
8.1.1
Sections
8.1.2
C/C++ System Stack
8.1.3
Dynamic Memory Allocation
8.1.4
Data Memory Models
8.1.4.1
Determining the Data Address Model
8.1.4.2
DP-Relative Vs. Absolute Addressing
8.1.4.3
Const Objects as Far
8.1.5
Trampoline Generation for Function Calls
8.1.6
Position Independent Data
8.2
Object Representation
8.2.1
Data Type Storage
8.2.1.1
char and short Data Types (signed and unsigned)
8.2.1.2
enum, int, and long Data Types (signed and unsigned)
8.2.1.3
float Data Type
8.2.1.4
The __int40_t Data Type (signed and unsigned)
8.2.1.5
long long Data Types (signed and unsigned)
8.2.1.6
double and long double Data Types
8.2.1.7
Pointer to Data Member Types
8.2.1.8
Pointer to Member Function Types
8.2.1.9
Structures and Arrays
8.2.2
Bit Fields
8.2.3
Character String Constants
366
8.3
Register Conventions
8.4
Function Structure and Calling Conventions
8.4.1
How a Function Makes a Call
8.4.2
How a Called Function Responds
8.4.3
Accessing Arguments and Local Variables
8.5
Accessing Linker Symbols in C and C++
8.6
Interfacing C and C++ With Assembly Language
8.6.1
Using Assembly Language Modules With C/C++ Code
8.6.2
Accessing Assembly Language Functions From C/C++
8.6.2.1
Calling an Assembly Language Function From a C/C++ Program
8.6.2.2
Assembly Language Program Called by
378
8.6.3
Accessing Assembly Language Variables From C/C++
8.6.3.1
Accessing Assembly Language Global Variables
8.6.3.1.1
Assembly Language Variable Program
8.6.3.1.2
C Program to Access Assembly Language From
383
8.6.3.2
Accessing Assembly Language Constants
8.6.3.2.1
Accessing an Assembly Language Constant From C
8.6.3.2.2
Assembly Language Program for
387
8.6.4
Sharing C/C++ Header Files With Assembly Source
8.6.5
Using Inline Assembly Language
8.6.6
Using Intrinsics to Access Assembly Language Statements
8.6.7
The __x128_t Container Type
8.6.7.1
The __x128_t Container Type
393
8.6.8
The __float2_t Container Type
8.6.9
Using Intrinsics for Interrupt Control and Atomic Sections
8.6.10
Using Unaligned Data and 64-Bit Values
8.6.10.1
Using the _mem8 Intrinsic
8.6.11
Using MUST_ITERATE and _nassert to Enable SIMD and Expand Compiler Knowledge of Loops
8.6.12
Methods to Align Data
8.6.12.1
Base Address of an Array
8.6.12.2
Offset from the Base of an Array
8.6.12.3
Dynamic Memory Allocation
8.6.12.4
Member of a Structure or Class
8.6.12.4.1
An Array in a Structure
8.6.12.4.2
An Array in a Class
406
8.6.13
SAT Bit Side Effects
8.6.14
IRP and AMR Conventions
8.6.15
Floating Point and Saturation Control Register Side Effects
8.7
Interrupt Handling
8.7.1
Saving the SGIE Bit
8.7.2
Saving Registers During Interrupts
8.7.3
Using C/C++ Interrupt Routines
8.7.4
Using Assembly Language Interrupt Routines
8.8
Run-Time-Support Arithmetic Routines
8.9
System Initialization
8.9.1
Boot Hook Functions for System Pre-Initialization
8.9.2
Automatic Initialization of Variables
8.9.2.1
Zero Initializing Variables
8.9.2.2
Direct Initialization
8.9.2.3
Autoinitialization of Variables at Run Time
8.9.2.4
Autoinitialization Tables
8.9.2.4.1
Length Followed by Data Format
8.9.2.4.2
Zero Initialization Format
8.9.2.4.3
Run Length Encoded (RLE) Format
8.9.2.4.4
Lempel-Ziv-Storer-Szymanski Compression (LZSS) Format
8.9.2.4.5
Sample C Code to Process the C Autoinitialization Table
8.9.2.5
Initialization of Variables at Load Time
8.9.2.6
Global Constructors
8.10
Support for Multi-Threaded Applications
8.10.1
Compiling with OpenMP
8.10.2
Multi-Threading Runtime Support
8.10.2.1
Runtime Thread Safety
8.10.2.2
Thread Creation, Initialization, and Termination
8.10.2.3
Thread Local Storage (TLS)
8.10.2.4
Accessing Shared Data
9
Using Run-Time-Support Functions and Building Libraries
9.1
C and C++ Run-Time Support Libraries
9.1.1
Linking Code With the Object Library
9.1.2
Header Files
9.1.3
Modifying a Library Function
9.1.4
Support for String Handling
9.1.5
Minimal Support for Internationalization
9.1.6
Support for Time and Clock Functions
9.1.7
Allowable Number of Open Files
9.1.8
Library Naming Conventions
9.2
The C I/O Functions
9.2.1
High-Level I/O Functions
9.2.1.1
Formatting and the Format Conversion Buffer
9.2.2
Overview of Low-Level I/O Implementation
open
close
read
write
lseek
unlink
rename
9.2.3
Device-Driver Level I/O Functions
DEV_open
DEV_close
DEV_read
DEV_write
DEV_lseek
DEV_unlink
DEV_rename
9.2.4
Adding a User-Defined Device Driver for C I/O
9.2.4.1
Mapping Default Streams to Device
9.2.5
The device Prefix
add_device
470
9.2.5.1
Program for C I/O Device
9.3
Handling Reentrancy (_register_lock() and _register_unlock() Functions)
9.4
Library-Build Process
9.4.1
Required Non-Texas Instruments Software
9.4.2
Using the Library-Build Process
9.4.2.1
Automatic Standard Library Rebuilding by the Linker
9.4.2.2
Invoking mklib Manually
9.4.2.2.1
Building Standard Libraries
9.4.2.2.2
Shared or Read-Only Library Directory
9.4.2.2.3
Building Libraries With Custom Options
9.4.2.2.4
The mklib Program Option Summary
9.4.3
Extending mklib
9.4.3.1
Underlying Mechanism
9.4.3.2
Libraries From Other Vendors
10
C++ Name Demangler
10.1
Invoking the C++ Name Demangler
10.2
Sample Usage of the C++ Name Demangler
A Glossary
A.1 Terminology
B Revision History
491
492
B Earlier Revisions
Read This First