Page 1
W5.0
C/C++ Compiler and Library Manual
for TigerSHARC
Revision 4.1, August 2008
®
Processors
Analog Devices, Inc.
One Technology Way
Norwood, Mass. 02062-9106
Part Number
82-000336-03
a
Page 2
Copyright Information
© 2008 Analog Devices, Inc., ALL RIGHTS RESERVED. This document
may not be reproduced in any form without prior, express written consent
from Analog Devices, Inc.
Printed in the USA.
Disclaimer
Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by implication or otherwise under the patent rights of Analog Devices, Inc.
Trademark and Service Mark Notice
The Analog Devices logo, icon bar and logo, the CROSSCORE logo,
VisualDSP++, SHARC, TigerSHARC, and EZ-KIT Lite are registered
trademarks of Analog Devices, Inc.
All other brand and product names are trademarks or service marks of
their respective owners.
Page 3
CONTENTS
PREFACE
Purpose of This Manual ............................................................. xxxix
Intended Audience ..................................................................... xxxix
Manual Contents Description ......................................................... xl
What’s New in This Manual ............................................................ xl
Technical or Customer Support ....................................................... xl
Supported Processors ...................................................................... xli
Product Information ...................................................................... xli
Analog Devices Web Site .......................................................... xli
VisualDSP++ Online Documentation ...................................... xlii
Technical Library CD ............................................................. xliii
Notation Conventions ................................................................... xliv
COMPILER
C/C++ Compiler Overview ........................................................... 1-3
Compiler Command-Line Interface ............................................... 1-5
Running the Compiler ............................................................. 1-6
Compiler Command-Line Switches ........................................ 1-10
VisualDSP++ 5.0 C/C++ Compiler and Library Manual iii
for TigerSHARC Processors
Page 4
CONTENTS
C/C++ Compiler Switch Summaries .................................. 1-10
C/C++ Mode Selection Switch Descriptions ...................... 1-22
C/C++ Compiler Common Switch Descriptions ................ 1-23
-c89 ............................................................................. 1-22
-c++ ............................................................................. 1-22
sourcefile ...................................................................... 1-23
-@ filename .................................................................. 1-23
-A name [(<tokens>)] .................................................... 1-23
-add-debug-libpaths ...................................................... 1-24
-align-branch-lines ........................................................ 1-25
-allow-macs-to-extend-saturation .................................. 1-25
-alttok .......................................................................... 1-25
-always-inline ............................................................... 1-26
-annotate ...................................................................... 1-26
-annotate-loop-instr ...................................................... 1-27
-auto-attrs .................................................................... 1-27
-bss .............................................................................. 1-27
-build-lib ...................................................................... 1-27
-C ................................................................................ 1-27
-c ................................................................................. 1-28
-char-size-any ............................................................... 1-28
-char-size-{8|32} ........................................................... 1-28
-const-read-write .......................................................... 1-29
-const-strings ................................................................ 1-29
iv VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 5
CONTENTS
-Dmacro[=definition] .................................................... 1-29
-debug-types ................................................................. 1-30
-default-branch-{np|p} ................................................... 1-30
-double-size-any ............................................................ 1-30
-double-size-{32 | 64} .................................................... 1-31
-dry .............................................................................. 1-32
-dryrun ......................................................................... 1-32
-E ................................................................................. 1-32
-ED .............................................................................. 1-32
-EE ............................................................................... 1-33
-enum-is-int .................................................................. 1-33
-extra-keywords ............................................................. 1-33
-file-attr name[=value] ................................................... 1-34
-flags-{asm|compiler|lib|link|mem} switch [,switch2 [,...]] 1-34
-force-circbuf ................................................................ 1-34
-fp-associative ............................................................... 1-35
-fp-div-lib ..................................................................... 1-35
-full-version .................................................................. 1-35
-g .................................................................................. 1-35
-glite ............................................................................. 1-36
-H ................................................................................ 1-36
-HH ............................................................................. 1-37
-h[elp] .......................................................................... 1-37
-I- ................................................................................. 1-37
VisualDSP++ 5.0 C/C++ Compiler and Library Manual v
for TigerSHARC Processors
Page 6
CONTENTS
-I directory [{,|;} directory...] ......................................... 1-38
-implicit-pointers .......................................................... 1-38
-include filename .......................................................... 1-39
-ipa .............................................................................. 1-39
-L directory [{,|;} directory...] ........................................ 1-39
-l library ....................................................................... 1-40
-list-workarounds .......................................................... 1-40
-M ............................................................................... 1-41
-MD ............................................................................ 1-41
-MM ............................................................................ 1-41
-Mo filename ................................................................ 1-41
-Mt name ..................................................................... 1-41
-map filename .............................................................. 1-41
-mem ........................................................................... 1-42
-multiline ..................................................................... 1-42
-never-inline ................................................................. 1-42
-no-align-branch-lines ................................................... 1-42
-no-alttok ..................................................................... 1-42
-no-annotate ................................................................. 1-43
-no-annotate-loop-instr ................................................. 1-43
-no-auto-attrs ............................................................... 1-43
-no-bss ......................................................................... 1-43
-no-builtin ................................................................... 1-44
-no-circbuf ................................................................... 1-44
vi VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 7
CONTENTS
-no-const-strings ........................................................... 1-44
-no-defs ........................................................................ 1-44
-no-extra-keywords ........................................................ 1-45
-no-fp-associative .......................................................... 1-45
-no-fp-minmax ............................................................. 1-45
-no-mem ....................................................................... 1-46
-no-multiline ................................................................ 1-46
-no-progress-rep-timeout ............................................... 1-46
-no-saturation ............................................................... 1-46
-no-std-ass .................................................................... 1-47
-no-std-def .................................................................... 1-47
-no-std-inc .................................................................... 1-47
-no-std-lib .................................................................... 1-47
-no-threads ................................................................... 1-47
-no-workaround workaround_id[,workaround_id …] .... 1-48
-O ................................................................................ 1-48
-O[0|1] ......................................................................... 1-48
-Oa ............................................................................... 1-48
-Og ............................................................................... 1-49
-Os ............................................................................... 1-49
-Ov num ....................................................................... 1-49
-o filename .................................................................... 1-51
-overlay ......................................................................... 1-51
-P ................................................................................. 1-52
VisualDSP++ 5.0 C/C++ Compiler and Library Manual vii
for TigerSHARC Processors
Page 8
CONTENTS
-PP ............................................................................... 1-52
-path-{ asm | compiler | lib | link } pathname ................. 1-52
-path-install directory ................................................... 1-52
-path-output directory .................................................. 1-53
-path-temp directory ..................................................... 1-53
-pch ............................................................................. 1-53
-pchdir directory ........................................................... 1-53
-pgo-session session-id .................................................. 1-53
-pguide ......................................................................... 1-54
-pplist filename ............................................................. 1-54
-proc processor ............................................................. 1-55
-progress-rep-func ......................................................... 1-56
-progress-rep-gen-opt .................................................... 1-56
-progress-rep-mc-opt ..................................................... 1-56
-progress-rep-timeout .................................................... 1-56
-progress-rep-timeout-secs secs ...................................... 1-57
-R directory [{:|,}directory …] ....................................... 1-57
-R- ............................................................................... 1-57
-S ................................................................................. 1-57
-s .................................................................................. 1-58
-save-temps ................................................................... 1-58
-section id=section_name[,id=section_name...] .............. 1-58
-show ........................................................................... 1-59
-si-revision version ........................................................ 1-59
viii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 9
CONTENTS
-signed-bitfield .............................................................. 1-60
-signed-char .................................................................. 1-60
-structs-do-not-overlap .................................................. 1-60
-syntax-only .................................................................. 1-61
-sysdefs ......................................................................... 1-61
-T filename ................................................................... 1-62
-threads ........................................................................ 1-62
-time ............................................................................ 1-62
-Umacro ....................................................................... 1-63
-unsigned-bitfield .......................................................... 1-63
-unsigned-char .............................................................. 1-64
-v .................................................................................. 1-64
-verbose ........................................................................ 1-64
-version ......................................................................... 1-64
-W {error|remark|suppress|warn} number ....................... 1-64
-Werror-limit number ................................................... 1-65
-Werror-warnings .......................................................... 1-65
-Wremarks .................................................................... 1-65
-Wterse ......................................................................... 1-65
-w ................................................................................. 1-66
-warn-protos ................................................................. 1-66
-workaround workaround_id[,workaround_id]* ............. 1-66
-write-files .................................................................... 1-67
-write-opts .................................................................... 1-67
VisualDSP++ 5.0 C/C++ Compiler and Library Manual ix
for TigerSHARC Processors
Page 10
CONTENTS
C++ Mode Compiler Switch Descriptions ......................... 1-68
-xref <filename> ............................................................ 1-67
-anach .......................................................................... 1-68
-check-init-order ........................................................... 1-69
-eh ............................................................................... 1-70
-full-dependency-inclusion ............................................ 1-70
-ignore-std .................................................................... 1-71
-no-anach ..................................................................... 1-71
-no-eh .......................................................................... 1-71
-no-implicit-inclusion ................................................... 1-71
-no-rtti ......................................................................... 1-72
-no-std-templates .......................................................... 1-72
-rtti .............................................................................. 1-72
-std-templates ............................................................... 1-72
Data Types and Data Type Sizes ............................................ 1-73
Integer Data Types ........................................................... 1-74
Floating-Point Data Types ................................................ 1-74
Data Type Alignment ............................................................ 1-75
Environment Variables Used by the Compiler ........................ 1-76
Optimization Control ........................................................... 1-77
Optimization Levels ......................................................... 1-78
Interprocedural Analysis ................................................... 1-80
Interaction with Libraries .............................................. 1-81
Controlling Silicon Revision and Anomaly Workarounds within the
Compiler ........................................................................... 1-82
x VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 11
CONTENTS
Using the -si-revision Switch ............................................ 1-83
Using the -workaround Switch .......................................... 1-84
Using the -no-workaround Switch ..................................... 1-87
Interactions Between the Silicon Revision and Workaround Switches
1-87
C/C++ Compiler Language Extensions ........................................ 1-89
Byte-Addressing Mode ........................................................... 1-93
sizeof() Operator Types and Sizes ....................................... 1-93
Pointers ............................................................................ 1-94
Alignment of Objects ........................................................ 1-94
Initializations .................................................................... 1-95
Pragmas Used in Byte-Addressing Mode ............................ 1-95
Performance Issues ............................................................ 1-95
Libraries Used in Byte-Addressing Mode ............................ 1-96
Include Files ..................................................................... 1-97
Function Inlining .................................................................. 1-97
Inlining and Optimization .............................................. 1-100
Inlining and Out-of-Line Copies ..................................... 1-100
Inlining and Global asm Statements ................................ 1-101
Inlining and Sections ...................................................... 1-101
Inline Assembly Language Support Keyword (asm) ............... 1-102
asm() Construct Syntax ................................................... 1-104
asm() Construct Syntax Rules ...................................... 1-106
asm() Construct Template Example ............................. 1-107
Assembly Construct Operand Description ....................... 1-108
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xi
for TigerSHARC Processors
Page 12
CONTENTS
Assembly Constructs With Multiple Instructions ............. 1-115
Assembly Construct Reordering and Optimization .......... 1-116
Assembly Constructs With Input and Output Operands .. 1-116
Assembly Constructs and Flow Control ........................... 1-117
Guidelines on the Use of asm() Statements ...................... 1-118
64-Bit Integer Support (long long) ...................................... 1-118
Quad-Word Support ........................................................... 1-119
Memory Support Keywords (pm dm) .................................. 1-119
Memory Keyword Rules .................................................. 1-120
__regclass Construct ........................................................... 1-122
Bank Type Qualifiers ........................................................... 1-123
Placement Support Keyword (section) ................................. 1-124
Placement of Compiler-Generated Code and Data ............... 1-125
Boolean Type Support Keywords ......................................... 1-126
Pointer Class Support Keyword (restrict) ............................. 1-126
Variable-Length Array Support ............................................ 1-127
Long Identifiers .................................................................. 1-129
Non-Constant Aggregate Initializer Support ........................ 1-129
Indexed Initializer Support .................................................. 1-129
Compiler Built-In Functions ............................................... 1-132
Using the builtins.h Header File ...................................... 1-133
Optimization Guidance Built-in Functions ..................... 1-134
16-Bit Data Types .......................................................... 1-137
Packed 16-bit Integer Support Using C ....................... 1-139
xii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 13
CONTENTS
Constructors (int2x16 values) ...................................... 1-139
Extractors and Expanders (int2x16 values) ................... 1-139
Arithmetic Operators (int2x16 values) ......................... 1-140
Bitwise Operators (int2x16 values) .............................. 1-140
Comparison Operators (int2x16 values) ....................... 1-141
Sideways Sum (int2x16 values) .................................... 1-142
Constructors (int4x16 values) ...................................... 1-143
Extractors (2x16 from a 4x16 value) ............................ 1-143
Arithmetic Operators (int4x16 values) ......................... 1-145
Sideways Sum (int4x16 values) .................................... 1-145
32-Bit Data Types ........................................................... 1-147
Constructors (int2x32 values) ...................................... 1-147
Extractors (int2x32 values) .......................................... 1-147
Circular Buffer Built-In Functions ................................... 1-148
Circular Buffer Increment of an Index ......................... 1-148
Circular Buffer Increment of a Pointer ......................... 1-148
Math Intrinsics ............................................................... 1-149
RECIPS ...................................................................... 1-150
RSQRTS .................................................................... 1-151
Instructions Generated by Built-in Functions ................... 1-151
Addition and Subtraction ............................................ 1-152
Conversion: ................................................................ 1-155
Miscellaneous ALU Instructions .................................. 1-156
Shifter Instructions ..................................................... 1-158
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xiii
for TigerSHARC Processors
Page 14
CONTENTS
Data Alignment Buffer (DAB) Built-in Functions ............ 1-167
Circular Buffer Data Alignment Buffer (DAB) Built-in Functions
1-169
Communications Logic Unit Operations ......................... 1-171
Bit Manipulation Instructions ..................................... 1-159
Multiplier Instructions ................................................ 1-161
Floating-Point Operations ........................................... 1-164
Miscellaneous ............................................................. 1-165
Memory Allocation ..................................................... 1-165
Composition and Decomposition ................................ 1-165
System Register Access ................................................ 1-166
TMAX, TMAX_ADD, TMAX_SUB, MAX_ADD, MAX_SUB
1-171
PERMUTE ................................................................ 1-177
ACS ........................................................................... 1-178
DESPREAD ............................................................... 1-182
XCORRS ................................................................... 1-184
Pragmas .............................................................................. 1-187
Data Alignment Pragmas ................................................ 1-188
#pragma align num ..................................................... 1-189
#pragma alignment_region (alignopt) .......................... 1-191
Interrupt Handler Pragmas ............................................. 1-192
Loop Optimization Pragmas ........................................... 1-195
#pragma all_aligned .................................................... 1-195
#pragma different_banks ............................................. 1-196
xiv VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 15
CONTENTS
#pragma loop_count(min, max, modulo) ..................... 1-196
#pragma loop_unroll N ............................................... 1-196
#pragma no_alias ........................................................ 1-198
#pragma no_vectorization ........................................... 1-199
#pragma vector_for ..................................................... 1-199
Function Side-Effect Pragmas .......................................... 1-200
#pragma alloc .............................................................. 1-200
#pragma const ............................................................. 1-201
#pragma noreturn ....................................................... 1-201
#pragma pgo_ignore .................................................... 1-202
#pragma pure .............................................................. 1-202
#pragma regs_clobbered string ..................................... 1-203
#pragma regs_clobbered_call string .............................. 1-207
#pragma overlay .......................................................... 1-210
#pragma result_alignment (n) ...................................... 1-211
General Optimization Pragmas ........................................ 1-211
Inline Control Pragmas ................................................... 1-212
#pragma always_inline ................................................ 1-212
#pragma never_inline .................................................. 1-213
Linking Control Pragmas ................................................ 1-214
#pragma linkage_name identifier ................................. 1-214
#pragma core ............................................................. 1-214
#pragma section/#pragma default_section .................... 1-219
#pragma file_attr (name[=value] [, name[=value] [...]]) 1-222
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xv
for TigerSHARC Processors
Page 16
CONTENTS
Class Conversion Optimization Pragmas ......................... 1-223
Template Instantiation Pragmas ...................................... 1-226
Header File Control Pragmas .......................................... 1-228
#pragma separate_mem_segments ( var1, var2 ) ........... 1-222
#pragma weak_entry .................................................. 1-223
#pragma param_never_null param_name [ ... ] ............ 1-223
#pragma suppress_null_check ..................................... 1-225
#pragma instantiate instance ....................................... 1-227
#pragma do_not_instantiate instance .......................... 1-227
#pragma can_instantiate instance ................................ 1-228
#pragma hdrstop ........................................................ 1-228
#pragma no_implicit_inclusion ................................... 1-229
#pragma no_pch ......................................................... 1-230
#pragma once ............................................................. 1-230
#pragma system_header .............................................. 1-231
Diagnostic Control Pragmas ........................................... 1-231
Modifying the Severity of Specific Diagnostics ............. 1-231
Modifying the Behavior of an Entire Class of Diagnostics 1-232
Saving or Restoring the Current Behavior of All Diagnostics ..
1-232
Memory Bank Pragmas ................................................... 1-234
#pragma code_bank(bankname) .................................. 1-234
#pragma data_bank(bankname) .................................. 1-235
#pragma stack_bank(bankname) ................................. 1-236
#pragma bank_memory_kind(bankname, kind) ........... 1-237
xvi VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 17
CONTENTS
#pragma bank_read_cycles(bankname, cycles) .............. 1-238
#pragma bank_write_cycles(bankname, cycles) ............. 1-238
#pragma bank_optimal_width(bankname, width) ........ 1-239
Increments and Decrements ................................................. 1-240
C++ Style Comments ........................................................... 1-240
C++ Fractional Type Support ............................................... 1-241
Format of Fractional Literals ........................................... 1-241
Conversions Involving Fractional Values .......................... 1-242
Fractional Arithmetic Operations .................................... 1-242
Mixed-Mode Operations ................................................. 1-243
GCC Compatibility Extensions ........................................... 1-244
Statement Expressions ..................................................... 1-244
Type Reference Support Keyword (typeof) ....................... 1-245
GCC Generalized Lvalues ............................................... 1-246
Conditional Expressions With Missing Operands ............. 1-247
Hexadecimal Floating-Point Numbers ............................. 1-247
Zero-Length Arrays ......................................................... 1-248
Variable Argument Macros .............................................. 1-248
Line Breaks in String Literals ........................................... 1-249
Arithmetic on Pointers to Void and Pointers to Functions 1-249
Cast to Union ................................................................. 1-249
Ranges in Case Labels ..................................................... 1-249
Declarations Mixed With Code ....................................... 1-250
Escape Character Constant .............................................. 1-250
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xvii
for TigerSHARC Processors
Page 18
CONTENTS
Alignment Inquiry Keyword (__alignof__) ...................... 1-250
(asm) Keyword for Specifying Names in Generated Assembler 1-251
Function, Variable and Type Attribute Keyword (__attribute__)
1-251
Unnamed struct/union fields within struct/unions ........... 1-252
Preprocessor-Generated Warnings ........................................ 1-252
Migrating .ldf Files From Previous VisualDSP++ Installations 1-252
C++ Support Tables (ctor, gdt) ........................................ 1-253
Preprocessor Features ................................................................ 1-255
Predefined Preprocessor Macros ........................................... 1-255
Writing Macros ................................................................... 1-258
Compound Macros ......................................................... 1-258
C/C++ Run-Time Model and Environment ............................... 1-261
Stack Frame Overview ......................................................... 1-262
Stack Frame Description ..................................................... 1-264
General System-Wide Specifications ................................ 1-266
At a procedure call, the following must be true: ........... 1-267
Argument Passage ........................................................... 1-268
Passing a C++ Class Instance ........................................... 1-269
Return Values ................................................................. 1-270
Procedure Call and Return .............................................. 1-271
To Call a Procedure: ................................................... 1-271
On Entry: ................................................................... 1-272
To Return from a Procedure: ....................................... 1-273
Code Sequences .............................................................. 1-273
xviii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 19
CONTENTS
Constructors and Destructors of Global Class Instances ........ 1-274
Constructors, Destructors and Memory Placement .......... 1-276
Support for argv/argc ........................................................... 1-277
Allocation of Memory for Stacks and Heaps in LDFs ............ 1-278
Example of Heap/Stack Memory Allocation ..................... 1-278
Using Multiple Heaps .......................................................... 1-280
Heap Identifiers .............................................................. 1-280
Initializing the Heap ....................................................... 1-281
Using Alternate Heaps with the Standard Interface ........... 1-281
Allocating C++ STL Objects to a Non-Default Heap ....... 1-282
Using the Alternate Heap Interface .................................. 1-285
C++ Run-Time Support for the Alternate Heap Interface 1-286
Using the Heap_Install Interface ..................................... 1-287
Miscellaneous Information ................................................... 1-289
Register Classification .......................................................... 1-289
Callee Preserved Registers (“Preserved”) ........................... 1-289
Dedicated Registers ......................................................... 1-290
Caller Save Registers (“Scratch”) ...................................... 1-290
ADSP-TS101 and ADSP-TS20x Processor Registers ........ 1-290
C/C++ and Assembly Language Interface ................................... 1-298
Calling Assembly Subroutines From C/C++ Programs .......... 1-298
Calling C/C++ Functions From Assembly Programs ............. 1-301
Using Mixed C/C++ and Assembly Naming Conventions . 1-302
C++ Programming Examples ................................................ 1-304
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xix
for TigerSHARC Processors
Page 20
CONTENTS
Using Fract Type Support ............................................... 1-305
Using Complex Number Support .................................... 1-306
Compiler C++ Template Support .............................................. 1-308
Template Instantiation ........................................................ 1-308
Identifying Un-instantiated Templates ................................. 1-310
File Attributes .......................................................................... 1-312
Automatically-Applied Attributes ........................................ 1-313
Default LDF Placement ...................................................... 1-313
Sections versus Attributes .................................................... 1-315
Granularity ..................................................................... 1-315
“Hard” versus “Soft” ....................................................... 1-316
Number of Values ........................................................... 1-316
Using Attributes .................................................................. 1-317
Example ......................................................................... 1-317
ACHIEVING OPTIMAL PERFORMANCE FROM C/C++
SOURCE CODE
General Guidelines ....................................................................... 2-3
How the Compiler Can Help .................................................. 2-4
Using the Compiler Optimizer ............................................ 2-4
Using Compiler Diagnostics ............................................... 2-5
Warnings and Remarks ................................................... 2-5
Source and Assembly Annotations ................................... 2-7
Using the Statistical Profiler ............................................... 2-7
Using Profile-Guided Optimization .................................... 2-8
xx VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 21
CONTENTS
Using Profile-Guided Optimization With a Simulator ...... 2-9
Using Profile-Guided Optimization With Non-Simulatable
Applications ............................................................... 2-10
Profile-Guided Optimization and Multiple Source Uses . 2-11
Profile-Guided Optimization and the -Ov Switch .......... 2-12
When to Use Profile-Guided Optimization .................... 2-12
Using Interprocedural Optimization .................................. 2-12
Data Types ............................................................................ 2-13
Avoiding Emulated Arithmetic .......................................... 2-14
Using Sub-Word Types with Caution ................................. 2-16
Getting the Most From IPA ................................................... 2-17
Initialize Constants Statically ............................................. 2-17
Quad-Word-Aligning Your Data ........................................ 2-19
Using __builtin_aligned .................................................... 2-20
Avoiding Aliases ................................................................ 2-21
Indexed Arrays Versus Pointers ............................................... 2-23
Trying Pointer and Indexed Styles ...................................... 2-24
Function Inlining .................................................................. 2-24
Using Inline asm Statements .................................................. 2-25
Memory Usage ...................................................................... 2-26
Putting Arrays into Different Memory Sections .................. 2-26
Using the Bank Qualifier ................................................... 2-29
Improving Conditional Code ...................................................... 2-30
Loop Guidelines ......................................................................... 2-31
Keeping Loops Short ............................................................. 2-32
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxi
for TigerSHARC Processors
Page 22
CONTENTS
Avoiding Unrolling Loops ..................................................... 2-32
Avoiding Loop-Carried Dependencies .................................... 2-33
Avoiding Loop Rotation by Hand .......................................... 2-34
Avoiding Array Writes in Loops ............................................. 2-35
Inner Loops Versus Outer Loops ........................................... 2-35
Avoiding Conditional Code in Loops ..................................... 2-36
Avoiding Placing Function Calls in Loops .............................. 2-37
Avoiding Non-Unit Strides ................................................... 2-37
Loop Control ........................................................................ 2-38
Using the Restrict Qualifier ................................................... 2-39
Avoiding Long Latencies ....................................................... 2-40
Using Built-In Functions in Code Optimization .......................... 2-41
Using Fractional Data ........................................................... 2-41
System Support Built-in Functions ........................................ 2-42
Using Circular Buffers ........................................................... 2-43
Smaller Applications: Optimizing for Code Size .......................... 2-45
Using Pragmas for Optimization ................................................. 2-47
Function Pragmas ................................................................. 2-47
#pragma const .................................................................. 2-47
#pragma pure ................................................................... 2-48
#pragma regs_clobbered .................................................... 2-48
#pragma optimize_{off|for_speed|for_space} ...................... 2-50
Loop Optimization Pragmas .................................................. 2-50
#pragma loop_count ......................................................... 2-50
xxii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 23
CONTENTS
#pragma no_vectorization ................................................. 2-51
#pragma vector_for ........................................................... 2-51
#pragma all_aligned .......................................................... 2-52
#pragma different_banks ................................................... 2-53
#pragma no_alias .............................................................. 2-54
Useful Optimization Switches ...................................................... 2-55
How Loop Optimization Works .................................................. 2-56
Terminology .......................................................................... 2-56
Clobbered Register ............................................................ 2-56
Live Register ..................................................................... 2-57
Spill .................................................................................. 2-57
Scheduling ........................................................................ 2-57
Loop Kernel ...................................................................... 2-58
Loop Prolog ...................................................................... 2-58
Loop Epilog ...................................................................... 2-58
Loop Invariant .................................................................. 2-58
Hoisting ........................................................................... 2-59
Sinking ............................................................................. 2-59
Loop Optimization Concepts ................................................. 2-59
Software Pipelining ........................................................... 2-60
Loop Rotation .................................................................. 2-60
Loop Vectorization ............................................................ 2-63
Modulo Scheduling ........................................................... 2-65
Initiation Interval (II) and the kernel ............................. 2-66
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxiii
for TigerSHARC Processors
Page 24
CONTENTS
Minimum Initiation Interval Due to Resources (Res MII) 2-69
Minimum Initiation Interval Due to Recurrences (Rec MII) 2-70
Stage Count (SC) ......................................................... 2-71
Variable Expansion and MVE unroll ............................. 2-72
Trip Count ................................................................... 2-77
A Worked Example ............................................................... 2-78
Assembly Optimizer Annotations ................................................ 2-81
Global Information ............................................................... 2-82
Procedure Statistics ............................................................... 2-82
Instruction Annotations ........................................................ 2-86
Loop Identification ............................................................... 2-87
Loop Identification Annotations ....................................... 2-87
File Position ..................................................................... 2-91
Vectorization Information ..................................................... 2-93
Unroll and Jam ................................................................. 2-94
Loop Flattening ................................................................ 2-97
Vectorization Annotations ................................................. 2-98
Modulo Scheduling Information ......................................... 2-100
Annotations for Modulo Scheduled Instructions .............. 2-101
Warnings, Failure Messages and Advice ................................ 2-107
C/C++ RUN-TIME LIBRARY
C and C++ Run-Time Libraries Guide .......................................... 3-3
Calling Library Functions ........................................................ 3-4
Using Compiler’s Built-In C Library Functions ........................ 3-4
xxiv VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 25
CONTENTS
Linking Library Functions ....................................................... 3-5
Working With Library Source Code ......................................... 3-8
Working With Library Header Files ......................................... 3-9
adi_types.h ....................................................................... 3-11
assert.h ............................................................................. 3-11
ctype.h ............................................................................. 3-11
cycle_count.h .................................................................... 3-12
cycles.h ............................................................................. 3-12
device.h ............................................................................ 3-12
device_int.h ...................................................................... 3-12
errno.h ............................................................................. 3-13
float.h ............................................................................... 3-13
iso646.h ........................................................................... 3-14
limits.h ............................................................................. 3-14
locale.h ............................................................................. 3-14
math.h .............................................................................. 3-15
setjmp.h ............................................................................ 3-16
signal.h ............................................................................. 3-16
stdarg.h ............................................................................ 3-17
stdbool.h .......................................................................... 3-17
stddef.h ............................................................................ 3-17
stdint.h ............................................................................. 3-17
stdio.h .............................................................................. 3-20
stdlib.h ............................................................................. 3-23
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxv
for TigerSHARC Processors
Page 26
CONTENTS
string.h ............................................................................ 3-24
time.h .............................................................................. 3-24
DSP Header Files .................................................................. 3-26
complex.h – Basic Complex Arithmetic Functions ............. 3-26
filter.h – DSP Filters and Transformations ......................... 3-27
libsim.h – Simulator Services ............................................ 3-28
matrix.h – Matrix Functions ............................................. 3-29
stats.h – Statistical Functions ............................................ 3-31
vector.h – Vector Functions ............................................... 3-31
window.h – Window Generators ....................................... 3-32
Calling Library Functions from an ISR .................................. 3-33
Using the Libraries in a Multi-Threaded Environment ........... 3-34
Abridged C++ Library Support .............................................. 3-35
Embedded C++ Library Header Files ................................. 3-36
complex ........................................................................ 3-36
exception ...................................................................... 3-37
fract ............................................................................. 3-37
fstream ......................................................................... 3-37
iomanip ........................................................................ 3-37
ios ................................................................................ 3-37
iosfwd .......................................................................... 3-37
iostream ....................................................................... 3-37
istream ......................................................................... 3-38
new .............................................................................. 3-38
xxvi VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 27
CONTENTS
ostream ......................................................................... 3-38
sstream ......................................................................... 3-38
stdexcept ....................................................................... 3-38
streambuf ...................................................................... 3-38
string ............................................................................ 3-38
strstream ....................................................................... 3-39
C++ Header Files for C Library Facilities ........................... 3-39
Embedded Standard Template Library Header Files ........... 3-40
algorithm ...................................................................... 3-40
deque ............................................................................ 3-40
functional ..................................................................... 3-40
hash_map ..................................................................... 3-40
hash_set ........................................................................ 3-40
iterator ......................................................................... 3-41
list ................................................................................ 3-41
map .............................................................................. 3-41
memory ........................................................................ 3-41
numeric ........................................................................ 3-41
queue ............................................................................ 3-41
set ................................................................................ 3-41
stack ............................................................................. 3-41
utility ........................................................................... 3-41
vector ........................................................................... 3-41
fstream.h ....................................................................... 3-42
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxvii
for TigerSHARC Processors
Page 28
CONTENTS
iomanip.h ..................................................................... 3-42
iostream.h .................................................................... 3-42
new.h ........................................................................... 3-42
Using the Thread-Safe C/C++ Run-Time Libraries with VDK 3-42
Measuring Cycle Counts ....................................................... 3-42
Basic Cycle Counting Facility ............................................ 3-43
Cycle Counting Facility with Statistics .............................. 3-45
Using time.h to Measure Cycle Counts .............................. 3-48
Determining the Processor Clock Rate .............................. 3-49
Considerations When Measuring Cycle Counts ................. 3-50
File I/O Support ................................................................... 3-52
Extending I/O Support To New Devices ........................... 3-53
DevEntry Structure ....................................................... 3-54
Registering New Devices ............................................... 3-59
Pre-Registering Devices ................................................. 3-59
Default Device ............................................................. 3-61
Remove and Rename Functions ..................................... 3-62
Default Device Driver Interface ........................................ 3-62
Data Packing For Primitive I/O ..................................... 3-63
Data Structure for Primitive I/O ................................... 3-64
Documented Library Functions .................................................. 3-67
Undocumented Library Functions ............................................... 3-71
Run-Time Library Reference ....................................................... 3-73
a_compress ................................................................................. 3-74
xxviii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 29
CONTENTS
a_expand .................................................................................... 3-75
abs .............................................................................................. 3-76
acos ............................................................................................ 3-77
addbitrev .................................................................................... 3-78
alog ............................................................................................ 3-79
alog10 ........................................................................................ 3-80
arg .............................................................................................. 3-81
asctime ....................................................................................... 3-82
asin ............................................................................................. 3-84
atan ............................................................................................ 3-85
atan2 .......................................................................................... 3-86
atof ............................................................................................. 3-87
atoi ............................................................................................. 3-89
atol ............................................................................................. 3-90
atold ........................................................................................... 3-91
atoll ............................................................................................ 3-93
autocoh ...................................................................................... 3-94
autocorr ...................................................................................... 3-95
avg ............................................................................................. 3-96
bsearch ....................................................................................... 3-97
cabs ............................................................................................ 3-99
cadd ......................................................................................... 3-100
cartesian ................................................................................... 3-101
cdiv .......................................................................................... 3-102
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxix
for TigerSHARC Processors
Page 30
CONTENTS
ceil ........................................................................................... 3-103
cexp ......................................................................................... 3-104
cfft ........................................................................................... 3-105
cfft_mag ................................................................................... 3-108
cfft2d ....................................................................................... 3-110
cfftf .......................................................................................... 3-112
clearerr ..................................................................................... 3-114
clip .......................................................................................... 3-115
clock ........................................................................................ 3-116
cmatmadd ................................................................................ 3-117
cmatmmlt ................................................................................ 3-118
cmatmsub ................................................................................ 3-119
cmatsadd .................................................................................. 3-120
cmatsmlt .................................................................................. 3-121
cmatssub .................................................................................. 3-122
cmlt ......................................................................................... 3-123
conj .......................................................................................... 3-124
convolve ................................................................................... 3-125
conv2d ..................................................................................... 3-126
copysign ................................................................................... 3-127
cos ........................................................................................... 3-128
cosh ......................................................................................... 3-129
cot ........................................................................................... 3-130
count_ones ............................................................................... 3-131
xxx VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 31
CONTENTS
crosscoh .................................................................................... 3-132
crosscorr ................................................................................... 3-133
csub .......................................................................................... 3-134
ctime ........................................................................................ 3-135
cvecdot ..................................................................................... 3-136
cvecsadd ................................................................................... 3-137
cvecsmlt .................................................................................... 3-138
cvecssub .................................................................................... 3-139
cvecvadd ................................................................................... 3-140
cvecvmlt ................................................................................... 3-141
cvecvsub ................................................................................... 3-142
difftime .................................................................................... 3-143
div ............................................................................................ 3-144
exp ........................................................................................... 3-145
__emuclk .................................................................................. 3-146
fabs .......................................................................................... 3-147
favg .......................................................................................... 3-148
fclip .......................................................................................... 3-149
fclose ........................................................................................ 3-150
feof ........................................................................................... 3-151
ferror ........................................................................................ 3-152
fflush ........................................................................................ 3-153
fgetc ......................................................................................... 3-154
fgetpos ...................................................................................... 3-155
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxxi
for TigerSHARC Processors
Page 32
CONTENTS
fgets ......................................................................................... 3-157
fir ............................................................................................ 3-158
fir_decima ................................................................................ 3-160
fir_interp .................................................................................. 3-162
floor ......................................................................................... 3-167
fmax ......................................................................................... 3-168
fmin ......................................................................................... 3-169
fmod ........................................................................................ 3-170
fopen ....................................................................................... 3-171
fprintf ...................................................................................... 3-173
fputc ........................................................................................ 3-178
fputs ........................................................................................ 3-179
fread ........................................................................................ 3-180
freopen ..................................................................................... 3-182
frexp ........................................................................................ 3-184
fscanf ....................................................................................... 3-185
fseek ......................................................................................... 3-189
fsetpos ...................................................................................... 3-191
ftell .......................................................................................... 3-192
fwrite ....................................................................................... 3-193
gen_bartlett .............................................................................. 3-195
gen_blackman .......................................................................... 3-197
gen_gaussian ............................................................................ 3-198
gen_hamming .......................................................................... 3-199
xxxii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 33
CONTENTS
gen_hanning ............................................................................. 3-200
gen_harris ................................................................................. 3-201
gen_kaiser ................................................................................. 3-202
gen_rectangular ........................................................................ 3-203
gen_triangle .............................................................................. 3-204
gen_vonhann ............................................................................ 3-206
getc .......................................................................................... 3-207
getchar ...................................................................................... 3-208
gets ........................................................................................... 3-209
gmtime ..................................................................................... 3-210
heap_calloc ............................................................................... 3-211
heap_free .................................................................................. 3-213
heap_init .................................................................................. 3-214
heap_install .............................................................................. 3-215
heap_lookup ............................................................................. 3-217
heap_malloc ............................................................................. 3-219
heap_realloc .............................................................................. 3-221
heap_switch .............................................................................. 3-223
histogramf ................................................................................ 3-225
ifft ............................................................................................ 3-227
ifft2d ........................................................................................ 3-229
iir ............................................................................................. 3-231
interrupt, interruptf, interrupts, interruptnr, interruptfnr,
interruptsnr ........................................................................... 3-235
localtime ................................................................................... 3-240
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxxiii
for TigerSHARC Processors
Page 34
CONTENTS
log ........................................................................................... 3-242
log10 ........................................................................................ 3-243
matinv ..................................................................................... 3-244
matmadd .................................................................................. 3-245
matmmlt .................................................................................. 3-246
matmsub .................................................................................. 3-247
matsadd ................................................................................... 3-248
matsmlt .................................................................................... 3-249
matssub .................................................................................... 3-250
max .......................................................................................... 3-251
mean ........................................................................................ 3-252
min .......................................................................................... 3-253
mktime .................................................................................... 3-254
modf ........................................................................................ 3-256
mu_compress ........................................................................... 3-257
mu_expand .............................................................................. 3-258
norm ........................................................................................ 3-259
perror ....................................................................................... 3-260
polar ........................................................................................ 3-261
pow .......................................................................................... 3-262
printf ....................................................................................... 3-263
putc ......................................................................................... 3-264
putchar .................................................................................... 3-265
puts .......................................................................................... 3-266
xxxiv VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 35
CONTENTS
qsort ......................................................................................... 3-267
raise .......................................................................................... 3-269
rand .......................................................................................... 3-272
remove ...................................................................................... 3-273
rename ..................................................................................... 3-274
rewind ...................................................................................... 3-275
rfft ............................................................................................ 3-276
rfft_mag ................................................................................... 3-279
rfft2d ........................................................................................ 3-281
rfftf .......................................................................................... 3-283
rfftf_mag .................................................................................. 3-285
rms ........................................................................................... 3-287
rsqrt ......................................................................................... 3-288
scanf ......................................................................................... 3-289
setbuf ....................................................................................... 3-291
setvbuf ...................................................................................... 3-292
sign .......................................................................................... 3-294
signal, signalf, signals, signalnr, signalfnr, signalsnr ..................... 3-295
sin ............................................................................................ 3-299
sinh .......................................................................................... 3-300
snprintf .................................................................................... 3-301
sprintf ...................................................................................... 3-303
sqrt ........................................................................................... 3-305
srand ........................................................................................ 3-306
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxxv
for TigerSHARC Processors
Page 36
sscanf ....................................................................................... 3-307
strftime .................................................................................... 3-308
strtod ....................................................................................... 3-312
strtof ........................................................................................ 3-314
strtoi ........................................................................................ 3-316
strtol ........................................................................................ 3-317
strtold ...................................................................................... 3-318
strtoll ....................................................................................... 3-320
strtoul ...................................................................................... 3-321
strtoull ..................................................................................... 3-322
tan ........................................................................................... 3-323
tanh ......................................................................................... 3-324
time ......................................................................................... 3-325
transpm .................................................................................... 3-326
twidfft ...................................................................................... 3-327
twidfftf ..................................................................................... 3-329
ungetc ...................................................................................... 3-331
var ........................................................................................... 3-333
vecdot ...................................................................................... 3-334
vecsadd .................................................................................... 3-335
vecsmlt ..................................................................................... 3-336
vecssub ..................................................................................... 3-337
vecvadd .................................................................................... 3-338
vecvmlt .................................................................................... 3-339
xxxvi VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 37
vecvsub ..................................................................................... 3-340
vfprintf ..................................................................................... 3-341
vprintf ...................................................................................... 3-343
vsnprintf ................................................................................... 3-345
vsprintf ..................................................................................... 3-347
zero_cross ................................................................................. 3-349
INDEX
VisualDSP++ 5.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxxvii
Page 38
xxxviii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 39
PREFACE
Thank you for purchasing Analog Devices, Inc. development software for
digital signal processing (DSP) applications.
Purpose of This Manual
The VisualDSP++ 5.0 C/C++ Compiler and Library Manual for
TigerSHARC Processors contains information about the C/C++ compiler
and run-time library for TigerSHARC® (ADSP-TSxxx) processors. It
includes syntax for command lines, switches, and language extensions. It
leads you through the process of using library routines and writing mixed
C/C++/assembly code.
Intended Audience
The primary audience for this manual is a programmer who is familiar
with Analog Devices processors. This manual assumes that the audience
has a working knowledge of the appropriate processor architecture and
instruction set. Programmers who are unfamiliar with Analog Devices
processors can use this manual, but should supplement it with other texts
(such as the appropriate hardware reference and programming reference
manuals) that describe their target architecture.
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xxxix
for TigerSHARC Processors
Page 40
Manual Contents Description
Manual Contents Description
This manual contains:
• Chapter 1, “Compiler”
Provides information on compiler options, language extensions and
C/C++/assembly interfacing
• Chapter 2, “Achieving Optimal Performance from C/C++ Source
Code”
Provides information on compiler (and assembly) code optimization (techniques and options).
• Chapter 3, “C/C++ Run-Time Library”
Shows how to use library functions and provides a complete C/C++
library function reference (for functions covered in the current
compiler release)
What’s New in This Manual
This edition of the VisualDSP++ 5.0 C/C++Compiler and Library Manual
for TigerSHARC Processors provides changes based on problem reports.
Technical or Customer Support
You can reach Analog Devices, Inc. Customer Support in the following
ways:
• Visit the Embedded Processing and DSP products Web site at
http://www.analog.com/processors/technical_support
• E-mail tools questions to
processor.tools.support@analog.com
xl VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 41
• E-mail processor questions to
processor.support@analog.com (World wide support)
processor.europe@analog.com (Europe support)
processor.china@analog.com (China support)
• Phone questions to 1-800-ANALOGD
• Contact your Analog Devices, Inc. local sales office or authorized
distributor
• Send questions by mail to:
Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
USA
Supported Processors
Preface
The name “TigerSHARC” refers to a family of Analog Devices, Inc.
floating-point and [8-bit, 16-bit, and 32-bit] fixed-point processors. For a
complete list of processors supported by VisualDSP++ 5.0, refer to VisualDSP++ online Help.
Product Information
Product information can be obtained from the Analog Devices Web site,
VisualDSP++ online Help system, and a technical library CD.
Analog Devices Web Site
The Analog Devices Web site, www.analog.com, provides information
about a broad range of products—analog integrated circuits, amplifiers,
converters, and digital signal processors.
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xli
for TigerSHARC Processors
Page 42
Product Information
To access a complete technical library for each processor family, go to
http://www.analog.com/processors/technical_library. The manuals
selection opens a list of current manuals related to the product as well as a
link to the previous revisions of the manuals. When locating your manual
title, note a possible errata check mark next to the title that leads to the
current correction report against the manual.
Also note, MyAnalog.com is a free feature of the Analog Devices Web site
that allows customization of a Web page to display only the latest information about products you are interested in. You can choose to receive
weekly e-mail notifications containing updates to the Web pages that meet
your interests, including documentation errata against all manuals. MyAn-
alog.com
provides access to books, application notes, data sheets, code
examples, and more.
Visit MyAnalog.com to sign up. If you are a registered user, just log on.
Your user name is your e-mail address.
VisualDSP++ Online Documentation
Online documentation comprises the VisualDSP++ Help system, software
tools manuals, hardware tools manuals, processor manuals, Dinkum
Abridged C++ library, and FLEXnet License Tools documentation. You
can search easily across the entire VisualDSP++ documentation set for any
topic of interest.
For easy printing, supplementary Portable Documentation Format (.pdf)
files for all manuals are provided on the VisualDSP++ installation CD.
xlii VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 43
Each documentation file type is described as follows.
File Description
.chm Help system files and manuals in Microsoft help format
Preface
.htm or
.html
.pdf VisualDSP++ and processor manuals in PDF format. Viewing and printing the
Dinkum Abridged C++ library and FLEXnet license tools software
documentation. Viewing and printing the
Internet Explorer 6.0 (or higher).
.pdf files requires a PDF reader, such as Adobe Acrobat Reader (4.0 or higher).
.html files requires a browser, such as
Technical Library CD
The technical library CD contains seminar materials, product highlights,
a selection guide, and documentation files of processor manuals, VisualDSP++ software manuals, and hardware tools manuals for the following
processor families: Blackfin, SHARC, TigerSHARC, ADSP-218x, and
ADSP-219x.
To order the technical library CD, go to http://www.analog.com/proces-
sors/technical_library, navigate to the manuals page for your
processor, click the request CD check mark, and fill out the order form.
Data sheets, which can be downloaded from the Analog Devices Web site,
change rapidly, and therefore are not included on the technical library
CD. Technical manuals change periodically. Check the Web site for the
latest manual revisions and associated documentation errata.
VisualDSP++ 5.0 C/C++ Compiler and Library Manual xliii
for TigerSHARC Processors
Page 44
Notation Conventions
L
a
[
Notation Conventions
Text conventions used in this manual are identified and described as
follows.
Example Description
Close command
(File menu)
{this | that} Alternative required items in syntax descriptions appear within curly
[this | that] Optional items in syntax descriptions appear within brackets and sepa-
[this,…] Optional item lists in syntax descriptions appear within brackets
.SECTION Commands, directives, keywords, and feature names are in text with
filename Non-keyword placeholders appear in text with italic style format.
Titles in reference sections indicate the location of an item within the
VisualDSP++ environment’s menu system (for example, the Close
command appears on the File menu).
brackets and separated by vertical bars; read the example as this or
that. One or the other is required.
rated by vertical bars; read the example as an optional
delimited by commas and terminated with an ellipse; read the example
as an optional comma-separated list of this.
letter gothic font.
Note: For correct operation, ...
A Note provides supplementary information on a related topic. In the
online version of this book, the word Note appears instead of this
symbol.
Caution: Incorrect device operation may result if ...
Caution: Device damage may result if ...
A Caution identifies conditions or inappropriate usage of the product
that could lead to undesirable results or product damage. In the online
version of this book, the word Caution appears instead of this symbol.
this or that.
Warn in g: Injury to device users may result if ...
A Warning identifies conditions or inappropriate usage of the product
that could lead to conditions that are potentially hazardous for devices
users. In the online version of this book, the word Wa rnin g appears
instead of this symbol.
xliv VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for TigerSHARC Processors
Page 45
1 COMPILER
The C/C++ compiler (ccts) is part of Analog Devices development
software for TigerSHARC (ADSP-TSxxx) processors.
L
This chapter contains:
The code examples in this manual have been compiled using
VisualDSP++ 5.0. The examples compiled with other versions of
VisualDSP++ may result in build errors or different output
although the highlighted algorithms stand and should continue to
stand in future releases of VisualDSP++.
• “C/C++ Compiler Overview” on page 1-3
provides an overview of C/C++ compiler for TigerSHARC
processors.
• “Compiler Command-Line Interface” on page 1-5
describes the operation of the compiler as it processes programs,
including input and output files, and command-line switches.
• “C/C++ Compiler Language Extensions” on page 1-89
describes the
for the C and C++ languages.
• “Preprocessor Features” on page 1-255
contains information on the preprocessor and ways to modify
source compilation.
ccts compiler’s extensions to the ISO/ANSI standard
• “C/C++ Run-Time Model and Environment” on page 1-261
contains reference information about implementation of C/C++
programs, data, and function calls in TigerSHARC processors
VisualDSP++ 5.0 C/C++ Compiler Manual 1-1
for TigerSHARC Processors
Page 46
• “C/C++ and Assembly Language Interface” on page 1-298
describes how to call an assembly language subroutine from C/C++
program, and how to call a C/C++ function from within an assembly language program.
• “Compiler C++ Template Support” on page 1-308
describes how templates are instantiated at compile-time.
• “File Attributes” on page 1-312
describes how file attributes help with the placement of run-time
library functions.
1-2 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 47
Compiler
C/C++ Compiler Overview
The C/C++ compiler (ccts) is designed to aid your DSP project development efforts by:
• Processing C and C++ source files, producing machine-level versions of the source code and object files
• Providing relocatable code and debugging information within the
object files
• Providing relocatable data and program memory segments for
placement by the linker in the processors’ memory
Using C/C++, developers can significantly decrease time-to-market since
it gives them the ability to efficiently work with complex signal processing
data types. It also allows them to take advantage of specialized signal processing operations without having to understand the underlying processor
architecture.
The C/C++ compiler (ccts) compiles ISO/ANSI standard C and C++
code for the TigerSHARC processors. Additionally, Analog Devices
includes within the compiler a number of C language extensions designed
to assist in project development. The
alDSP++ environment or from an operating system command line.
The C/C++ compiler processes your C and C++ language source files and
produces TigerSHARC assembler source files. The assembler source files
are assembled by the TigerSHARC assembler (easmts). The assembler creates Executable and Linkable Format (ELF) object files that can either be
linked (using the linker) to create a executable file or included in an
archive library (using elfar). The way in which the compiler controls the
assemble, link, and archive phases of the process depends on the source
input files and the compiler options used.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-3
for TigerSHARC Processors
ccts compiler runs from the Visu-
Page 48
C/C++ Compiler Overview
Source files contain the C/C++ program to be processed by the compiler.
The
ccts compiler supports the ANSI/ISO standard definitions of the C
and C++ languages. For information on the C language standard, see any
of the many reference texts on the C language. Analog Devices recommends the Bjarne Stroustrup text “The C++ Programming Language” from
Addison Wesley Longman Publishing Co (ISBN: 0201889544) (1997) as
a reference text for the C++ programming language.
The ccts compiler supports a set of C/C++ language extensions. These
extensions support hardware features of the TigerSHARC processors. For
more information, see “C/C++ Compiler Language Extensions” on
page 1-89.
Compiler options are set in the VisualDSP++ Integrated Development
and Debug Environment (IDDE) from the Compile page of the Project
Options dialog box. The selections control how the compiler processes
your source files, letting you select features that include the language dialect, error reporting, and debugger output, etc.
By default, the ccts compiler operates in the 32-bit word-addressing
mode. The ccts compiler can also be set for the 8-bit byte-addressing
mode. For more information, refer to “-char-size-any” switch
(on page 1-28), “-char-size-{8|32}” switch (on page 1-28), “Data Types
and Data Type Sizes” on page 1-73, and “Byte-Addressing Mode” on
page 1-93.
For more information on the VisualDSP++ environment, see online Help.
1-4 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 49
Compiler Command-Line Interface
This section describes how the ccts compiler is invoked from the command line, the various types of files used by and generated from the
compiler, and the switches used to tailor the compiler’s operation.
This section contains:
• “Running the Compiler” on page 1-6
• “Compiler Command-Line Switches” on page 1-10
• “Data Types and Data Type Sizes” on page 1-73
• “Data Type Alignment” on page 1-75
• “Environment Variables Used by the Compiler” on page 1-76
• “Optimization Control” on page 1-77
Compiler
• “Controlling Silicon Revision and Anomaly Workarounds within
the Compiler” on page 1-82
By default, the compiler runs with Analog Extensions for C code enabled.
This means that the compiler processes source files written in ANSI/ISO
standard C language supplemented with Analog Devices extensions.
Table 1-2 on page 1-8 lists valid extensions of source files the compiler
operates upon. By default, the compiler processes the input file through
the listed stages to produce a .
page 1-9.) Table 1-4 on page 1-11 lists the switches that select the lan-
guage dialect.
Although many switches are generic between C and C++, some of them
are valid in C++ mode only. A summary of the generic C/C++ compiler
switches appears in Table 1-5 on page 1-11. A summary of the C++ specific compiler switches appears in Table 1-6 on page 1-20. The summaries
are followed by descriptions of each switch.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-5
for TigerSHARC Processors
DXE file. (See file names in Table 1-3 on
Page 50
Compiler Command-Line Interface
L
the compiler’s default options settings. The way the compiler’s
options are set depends on the environment used to run the DSP
development software.
Running the Compiler
Use the following general syntax for the ccts command line:
ccts [-switch [-switch …]] sourcefile [sourcefile …]
runs the assembler with
Table 1-1. TigerSHARC Command Line Syntax
When developing a DSP project, sometimes it is useful to modify
Command
Element
ccts Name of the compiler program for TigerSHARC processors.
-switch Switch (or switches) to process.
Description
The compiler has many switches. These switches select the operations and
modes for the compiler and other tools. Command-line switches are case
sensitive. For example,
-O is not the same as -o.
sourceFile Name of the file to be preprocessed, compiled, assembled, and/or linked
A file name can include the drive, directory, file name, and file extension.
The compiler supports both Win32- and POSIX-style paths, using either
forward or back slashes as the directory delimiter. It also supports UNC
path names (starting with two slashes and a network name).
When file names or other switches for the compiler include spaces
L
or other special characters, you must ensure that these are properly
quoted (usually using double-quote characters), to ensure that they
are not interpreted by the operating system before being passed to
the compiler.
1-6 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 51
Compiler
The
ccts compiler uses the file extension to determine what the file con-
tains and what operations to perform upon it. Table 1-3 on page 1-9 lists
the allowed extensions.
For example, the following command line
ccts -proc ADSP-TS101 -O -Wremarks -o program.dxe source.c
runs ccts with
-proc ADSP-TS101 Specifies the processor
-O Specifies optimization for the compiler
-Wremarks Selects extra diagnostic remarks in addition to
warning and error messages
-o program.dxe Selects a name for the compiled, linked output
source.c Specifies the C language source file to be compiled
The following example command line for the C++ mode
ccts -proc ADSP-TS101 -c++ source.cpp
runs ccts with:
-c++ Specifies that all of the source files to be compiled
in C++
source.cpp Specifies the C++ language source file for your
program
The normal function of
ccts is to invoke the compiler, assembler, and
linker as required to produce an executable object file. The precise operation is determined by the extensions of the input filenames, and by various
switches.
In normal operation the compiler uses the following extension files to perform a specified action:
VisualDSP++ 5.0 C/C++ Compiler Manual 1-7
for TigerSHARC Processors
Page 52
Compiler Command-Line Interface
Table 1-2. File Extensions
Extension Action
.c .cpp .cxx .cc .c++ Source file is compiled, assembled, and linked
.asm, .dsp, or .s Assembly language source file is assembled and linked
.doj Object file (from previous assembly) is linked
If multiple files are specified, each is first processed to produce an object
file; then all object files are presented to the linker.
You can stop this sequence at various points by using appropriate compiler switches, or by selecting options with the VisualDSP++ environment.
These switches are
-E, -P,-M,-H,-S, and -c.
Many of the compiler’s switches take a file name as an optional parameter.
If you do not use the optional output name switch, ccts names the output
for you. Table 1-3 on page 1-9 lists the type of files, names, and extensions ccts appends to output files.
File extensions vary by command-line switch and file type. These extensions are influenced by the program that is processing the file, any search
directories that you select, and any path information that you include in
the file name. Table 1-3 indicates the searches that the preprocessor, compiler, assembler, and linker support. The compiler supports relative and
absolute directory names to define file search paths. For information on
additional search directories, see the -I directory switch (on page 1-38)
-L directory switch (on page 1-39).
and
When providing an input or output file name as an optional parameter,
use the following guidelines:
• Use a file name (include the file extension) with either an unambiguous relative path or an absolute path. A file name with an absolute
path includes the drive, directory, file name, and file extension.
1-8 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 53
Compiler
• Enclose long file names within straight quotes; for example,
file name.c". The ccts compiler uses the file extension conven-
"long
tions listed in Table 1-3 to determine the input file type.
• Verify that the compiler is using the correct file. If you do not provide the complete file path as part of the parameter or add
additional search directories, ccts looks for input in the current
directory.
Using the verbose output switches for the preprocessor, compiler,
L
assembler, and linker causes each of these tools to display command-line information as they process each file.
Table 1-3. Input and Output Files
Input File Extension File Extension Description
.c C/C++ source file
.cc .cpp .cxx C++ source file
.h Header file (referenced by a #include statement)
.hpp .hh .hxx .h++ C++ header file (referenced by a #include statement)
.pch C++ pre-compiled header file
.i Preprocessed C/C++ source, created when preprocess only (-E compiler
switch) is specified
.ipa, .opa Interprocedural analysis files—used internally by the compiler when
performing interprocedural analysis
.pgo Execution profile generated by a simulation run. For more information,
see “Using Profile-Guided Optimization” in Chapter 2, Achieving
Optimal Performance from C/C++ Source Code.
.s, .dsp, .asm Assembler source file
.ii Template instantiation files—used internally by the compiler when
instantiating C++ templates
.is Preprocessed assembly source (retained when -save-temps is specified)
.ldf Linker Description File
.doj Object file to be linked
VisualDSP++ 5.0 C/C++ Compiler Manual 1-9
for TigerSHARC Processors
Page 54
Compiler Command-Line Interface
Table 1-3. Input and Output Files (Cont’d)
Input File Extension File Extension Description
.dlb Library of object files to be linked as needed
.xml Processor system memory map file output
.sym Processor system symbol map file output
The compiler refers to a number of environment variables during its operation, and these environment variables can affect the compiler’s behavior.
Refer to “Environment Variables Used by the Compiler” on page 1-76 for
more information.
Compiler Command-Line Switches
This section describes the command-line switches used when compiling.
It contains a set of tables that provide a brief description of each switch.
These tables are organized by type of a switch. Following these tables are
sections that provide fuller descriptions of each switch.
C/C++ Compiler Switch Summaries
This section contains a set of tables that summarize generic and specific
switches (options), as follows:
• Table 1-4 “C/C++ Mode Selection Switches” on page 1-11
• Table 1-5 “C/C++ Compiler Common Switches” on page 1-11
• Table 1-6 “C++ Mode Compiler Switches” on page 1-20
1-10 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 55
A brief description of each switch follows the tables, beginning
on page 1-22.
Table 1-4. C/C++ Mode Selection Switches
Switch Name Description
Compiler
-c89
(on page 1-22)
-c++
(on page 1-22)
Supports programs that conform to the ISO/IEC
9899:1990 standard
Supports ANSI/ISO standard C++ with Analog Devices
extensions
Table 1-5. C/C++ Compiler Common Switches
Switch Name Description
sourcefile
(on page 1-23)
-@ filename
(on page 1-23)
-A name[tokens]
(on page 1-23)
-add-debug-libpaths
(on page 1-24)
-align-branch-lines
(on page 1-25)
-
allow-macs-to-extend-saturation
(on page 1-25)
-alttok
(on page 1-25)
Specifies file to be compiled
Reads command-line input from the file
Asserts the specified name as a predicate
Link against debug-specific variants of system libraries,
where available.
Quad align predicted branches
Instructs the compiler to try to generate multiply-accumulate instructions using saturating add and subtract
operations.
Allows alternative keywords and sequences in sources
-always-inline
(on page 1-26)
-annotate
inline keyword as a requirement rather than a
Tr e a t s
suggestion.
Enables assembly annotations
(on page 1-26)
-annotate-loop-instr
(on page 1-27)
Provides additional annotation information for the
prolog, kernel and epilog of a loop
VisualDSP++ 5.0 C/C++ Compiler Manual 1-11
for TigerSHARC Processors
Page 56
Compiler Command-Line Interface
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-auto-attrs
(on page 1-34)
-bss
(on page 1-27)
Directs the compiler to emit automatic attributes based
on the files it compiles. Enabled by default.
Causes the compiler to place global zero-initialized
data into a separate BSS-style section
-build-lib
(on page 1-27)
-C
(on page 1-27)
-c
(on page 1-28)
-char-size-any
(on page 1-28
-char-size-{8|32}
(on page 1-28)
-const-read-write
(on page 1-29)
-Dmacro[=definition]
(on page 1-29)
-debug-types
(on page 1-30)
-default-branch-{np|p}
(on page 1-30)
-double-size-any
(on page 1-30)
Directs the librarian to build a library file
Retains preprocessor comments in the output file;
active only with the
-E or -P switch)
Compiles and/or assembles only; does not link
Indicate that the resulting object can link against any
char size object
Selects byte (8-bit) or word (32-bit) addressing mode
Constant pointers may access modifiable memory
Defines a macro
Supports building a
*.h file directly and writing a
complete set of debugging information for the header
file
Sets default branches to be predict or non-predict
Indicate that the resulting object can link against any
double size object
-double-size-{32|64}
(on page 1-31)
-dry
(on page 1-32)
-dryrun
(on page 1-32)
Selects 32- or 64-bit IEEE format for
-double-size-32 is the default mode
Displays, but does not perform, main driver actions
(verbose dry-run)
Displays, but does not perform, top-level driver actions
(terse dry-run)
double; the
1-12 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 57
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-E
(on page 1-32)
-ED
(on page 1-32)
Preprocesses, but does not compile, the source file
Preprocesses and sends all output to a file
Compiler
-EE
(on page 1-33)
-enum-is-int
(on page 1-33)
-extra-keywords
(on page 1-33)
-file-attr name[=value]
(on page 1-34)
-flags-{tools} <arg1>
[,arg2...]
(on page 1-34)
-force-circbuf
(on page 1-34)
-fp-associative
(on page 1-35)
-fp-div-lib
(on page 1-35)
-full-version
(on page 1-35)
-g
(on page 1-35)
-glite
(on page 1-36)
Preprocesses and compiles the source file
By default
option ensures the
enums can have a type larger than int. This
enum type is int.
Recognizes Analog Devices extensions to ISO/ANSI
standards for C and C++ (default mode)
Adds the specified attribute name/value pair to the
file(s) being compiled
Passes command-line switches through the compiler to
other build tools
Treats array references of the form
array[i%n] as cir-
cular buffer operations
Treats floating-point multiply and addition as an associative
Uses library code instead of inline code for floating-point divides. Increases accuracy at expense of performance.
Displays version information for build tools
Generates DWARF-2 debug information
Generates lightweightDWARF-2 debug information
-H
(on page 1-36)
-HH
Outputs a list of header files, but does not compile the
source file
Outputs a list of included header files and compiles
(on page 1-37)
VisualDSP++ 5.0 C/C++ Compiler Manual 1-13
for TigerSHARC Processors
Page 58
Compiler Command-Line Interface
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-h[elp]
(on page 1-37)
-I-
(on page 1-37)
-I directory
(on page 1-38)
Outputs a list of command-line switches with brief
syntax descriptions
Establishes the point in the include directory list at
which the search for header files enclosed in angle
brackets should begin
Appends directory to the standard search path.
-implicit-pointers
(on page 1-38)
-include filename
(on page 1-39)
-ipa
(on page 1-39)
-L directory
(on page 1-39)
-l library
(on page 1-40)
-list-workarounds
(on page 1-40)
-M
(on page 1-41)
-MD
(on page 1-41)
-MM
(on page 1-41)
-Mo filename
(on page 1-41)
-Mt filename
(on page 1-41)
Demotes incompatible-pointer-type errors into discretionary warnings. Not valid when compiling in C++
mode.
Includes named file prior to preprocessing each source
file
Enables interprocedural analysis
Appends the specified directory to the standard library
search path when linking
Searches the specified library for functions when linking
Lists all compiler-supported errata workarounds
Generates make rules only; does not compile
Generates
make rules, compiles, and prints to a file
Generates make rules and compiles
Writes dependency information to
switch is used in conjunction with the
filename. This
-ED or -MD
options.
Makes dependencies, where the target is renamed as
filename
1-14 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 59
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-map filename
(on page 1-41)
-mem
(on page 1-42)
Directs the linker to generate a memory map of all
symbols
Enables memory initialization
Compiler
-multiline
(on page 1-42)
-never-inline
(on page 1-42)
-no-align-branch-lines
(on page 1-42)
-no-alttok
(on page 1-42)
-no-annotate
(on page 1-43)
-no-annotate-loop-instr
(on page 1-43)
-no-auto-attrs
(on page 1-34)
-no-bss
(on page 1-43)
-no-builtin
(on page 1-44)
-no-circbuf
(on page 1-44)
-no-const-strings
(on page 1-44)
Enables string literals over multiple lines (default)
Ignores
inline keyword on function definitions
Do not align predicted branches to a quad word
boundary
Does not allow alternative keywords and sequences in
sources
Disables the annotation of assembly files
Disables the production of additional loop annotation
information by the compiler (default mode)
Directs the compiler not to emit automatic attributes
based on the files it compiles.
Causes the compiler to group global zero-initialized
data into the same section as global data with non-zero
initializers. Set by default.
For certain language extensions, uses generic implementations in preference to intrinsic functions. See
“Math Intrinsics” on page 1-149.
Disables the automatic generation of circular buffer
code by the compiler
Indicates that string literals should not be qualified as
const
-no-defs
(on page 1-44)
Does not define any default preprocessor macros,
include directories, library directories, libraries,
run-time headers, or keyword extensions
VisualDSP++ 5.0 C/C++ Compiler Manual 1-15
for TigerSHARC Processors
Page 60
Compiler Command-Line Interface
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-no-extra-keywords
(on page 1-45)
-no-fp-associative
(on page 1-45)
Does not define language extension keywords that
could be valid C/C++ identifiers
Does not treat floating-point multiply and addition as
an associative
-no-mem
(on page 1-46)
-no-multiline
(on page 1-46)
-no-progress-rep-timeout
(on page 1-46)
-no-saturation
(on page 1-46)
-no-std-ass
(on page 1-47)
-no-std-def
(on page 1-47)
-no-std-inc
(on page 1-47)
-no-std-lib
(on page 1-47)
-no-threads
(on page 1-47)
-no-workaround workaround_id
(on page 1-48)
-O
(on page 1-48)
Disables memory initialization
Disables multiple line string literal support
Prevents the compiler from issuing a diagnostic during
excessively long compilations.
Causes the compiler not to introduce saturation
semantics when optimizing expressions
Disables any predefined assertions and system-specific
macro definitions
Disables normal macro definitions; also disables Analog Devices keyword extensions that do not have leading underscores (__)
Searches for preprocessor header files only in the current directory and in directories specified with the -I
switch
Searches for only those linker libraries specified with
-l switch when linking
the
Specifies that compiled code does not need to be
thread-safe
Disables compiler anomaly workdaround
Enables code optimizations
-O [0|1]
Enables/disables code optimizations
(on page 1-48)
-Oa
Enables automatic function inlining
(on page 1-48)
1-16 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 61
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-Og
(on page 1-49)
-Os
(on page 1-49)
Enables a compiler mode that performs optimizations
while still preserving the debugging information
Optimizes for code size
Compiler
-Ov num
(on page 1-49)
-o filename
(on page 1-51)
-overlay
(on page 1-51)
-P
(on page 1-52)
-PP
(on page 1-52)
-path-{asm|compiler|lib|link}
pathname
(on page 1-52)
-path-install directory
(on page 1-52)
-path-output directory
(on page 1-53)
-path-temp directory
(on page 1-53)
-pch
(on page 1-53)
Controls speed vs. size optimizations
Specifies the output file name
Permits program usage of overlays
Preprocesses, but does not compile, the source file; output does not contain #line directives
Preprocesses and compiles the source file; output does
not contain #line directives.
Uses the specified directory as the location of the specified compilation tool (assembler, compiler, librarian, or
linker, respectively)
Uses the specified directory as the location for all compilation tool
Specifies the location of non-temporary files
Specifies the location of temporary files
Generates and uses precompiled header files (*.pch)
-pchdir directory
Specifies the location of PCHRepository
(on page 1-53)
-pguide
(on page 1-54)
Adds instrumentation for the gathering of a profile as
the first stage of performing profile-guided optimization
-pplist filename
Outputs a raw preprocessed listing to the specified file
(on page 1-54)
VisualDSP++ 5.0 C/C++ Compiler Manual 1-17
for TigerSHARC Processors
Page 62
Compiler Command-Line Interface
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-proc processor
(on page 1-55)
-progress-rep-func
(on page 1-56)
-progress-rep-gen-opt
(on page 1-56)
-progress-rep-mc-opt
(on page 1-56)
-progress-rep-timeout
(on page 1-56)
Specifies that the compiler should produce code suitable for the specified processor
Issues a diagnostic message each time the compiler
starts compiling a new function. Equivalent to
-Wwarn=cc1472.
Issues a diagnostic message each time the compiler
starts a new generic optimization pass on the current
function. Equivalent to
Issues a diagnostic message each time the compiler
starts a new machine-specific optimization pass on the
current function. Equivalent to
Issues a diagnostic message if the compiler exceeds a
time limit during compilation.
-Wwarn=cc1473.
-Wwarn=cc1474.
-progress-rep-timeout-secs secs
(on page 1-57)
-R directory
(on page 1-57)
-R-
(on page 1-57)
-S
(on page 1-57)
-s
(on page 1-58)
-save-temps
(on page 1-58)
-section id=section_name
(on page 1-58)
-show
(on page 1-59)
-si-revision version
(on page 1-59)
Specifies how many seconds must elapse during a compilation before the compiler issues a diagnostic on the
length of compilation.
Appends directory to the standard search path for
source files
Removes all directories from the standard search path
for source files
Stops compilation before running the assembler
Removes debugging information from the output executable file when linking
Saves intermediate compiler temporary files
Orders the compiler to place data/program of type
“id” into the section “section_name”
Displays the driver command-line information
Specifies a silicon revision of the specified processor.
The default setting is the latest silicon revision.
1-18 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 63
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-signed-bitfield
(on page 1-60)
-signed-char
(on page 1-60)
Makes the default type for plain
Makes the default type for char signed
Compiler
int bitfields signed
-structs-do-not-overlap
(on page 1-60)
-syntax-only
(on page 1-61)
-sysdefs
(on page 1-61)
-T filename
(on page 1-62)
-threads
(on page 1-62)
-time
(on page 1-62)
-Umacro
(on page 1-63)
-unsigned-bitfield
(on page 1-63)
-unsigned-char
(on page 1-64)
-v
(on page 1-64)
-verbose
(on page 1-64)
-version
(on page 1-64)
Specifies that struct copies may use “memcpy” semantics, rather than the usual “memmove” behavior
Checks the source code for compiler syntax errors, but
does not write any output
Defines the system definition macros
Uses the specified the Linker Description File as control input for linking
Specifies that the build and link should be thread-safe
Displays the elapsed time as part of the output information on each part of the compilation process
Undefines macro(s)
Makes the default type for plain
Makes the default type for
int bitfields unsigned
char unsigned
Displays version and command-line information for all
compilation tools
Displays command-line information for all compilation tools as they process each file
Displays version information for all compilation tools
as they process each file
-W{error|remark|
suppress|warn} number
Overrides the default severity of the specified diagnosticmessages (errors, remarks, or warnings)
(on page 1-64)
VisualDSP++ 5.0 C/C++ Compiler Manual 1-19
for TigerSHARC Processors
Page 64
Compiler Command-Line Interface
Table 1-5. C/C++ Compiler Common Switches (Cont’d)
Switch Name Description
-Werror-limit number
(on page 1-65)
-Werror-warnings
(on page 1-65)
Stops compiling after reaching the specified number of
errors
Directs the compiler to treat all warnings as errors
-Wremarks
(on page 1-65)
-Wterse
(on page 1-65)
-w
Indicates that the compiler may issue remarks, which
are diagnostic messages even milder than warnings
Issues only the briefest form of compiler warnings,
errors, and remarks
Disables all warnings
(on page 1-66)
-warn-protos
Issues warnings about functions without prototypes
(on page 1-66)
-workaround workaround_id
(on page 1-66)
-write-files
Enables code generator workaround for specific hardware defects
Enables compiler I/O redirection
(on page 1-67)
-write-opts
(on page 1-67)
-xref filename
(on page 1-67)
Passes the user options (but not input filenames) via a
temporary file
Outputs cross-reference information to the specified
file.
Table 1-6. C++ Mode Compiler Switches
Switch Name Description
-anach
(on page 1-68)
Supports some language features (anachronisms) that are
prohibited by the C++ standard but still in common use
-check-init-order
(on page 1-69)
-eh
Adds run-time checking to the generated code highlighting potential uninitialized external objects.
Enables exception handling
(on page 1-70)
-full-dependency-inclusion
(on page 1-70)
Ensures re-inclusion of implictly included files when generating dependency information
1-20 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 65
Table 1-6. C++ Mode Compiler Switches (Cont’d)
Switch Name Description
Compiler
-ignore-std
(on page 1-71)
-no-anach
(on page 1-71)
-no-eh
(on page 1-71)
-no-implicit-inclusion
(on page 1-71)
-no-rtti
(on page 1-72)
-no-std-templates
(on page 1-72)
-rtti
(on page 1-72)
-std-templates
(on page 1-72)
Disables namespace std within the C++ Standard header
files.
Disallows the use of anachronisms that are prohibited by
the C++ standard
Disables exception-handling
Prevents implicit inclusion of source files as a method of
finding definitions of template entities to be instantiated
Disables run-time type information
Disables the lookup of names used in templates.
Enables run-time type information
Enables the lookup of names used in templates
VisualDSP++ 5.0 C/C++ Compiler Manual 1-21
for TigerSHARC Processors
Page 66
Compiler Command-Line Interface
C/C++ Mode Selection Switch Descriptions
The following command-line switches provide C/C++ mode selection.
-c89
The -c89 switch directs the compiler to support programs that conform to
the ISO/IEC 9899:1990 standard. For greater conformance to the standard, the following switches should be used: -alttok, -const-read-write,
and -no-extra-keywords (see Table 1-5 on page 1-11).
-c++
The -c++ (C++ mode) switch directs the compiler to compile the source
file(s) written in ANSI/ISO standard C++ with Analog Devices language
extensions. When using this switch, source files with an extension of .c are
compiled and linked in C++ mode.
All the standard features of C++ are accepted in the default mode except
exception handling and run-time type identification because these impose
a run-time overhead that is not desirable for all embedded programs. Support for these features can be enabled with the -eh and -rtti switches.
(See Table 1-6 on page 1-20.)
Exceptions also require modifications to the Linker Description Files
(LDF); these modifications link against versions of the C++ run-time
library that have been built with exceptions support enabled, and link the
exception-handling library. There are several new data sections that must
be mapped into the .
dxe file as well: .frt, .edt, .cht, and .gdt. See the
default .ldf files included with the release for example modifications.
1-22 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 67
Compiler
C/C++ Compiler Common Switch Descriptions
The following command-line switches apply in C and C++ modes.
sourcefile
The sourcefile parameter (or parameters) switch specifies the name of
the file (or files) to be preprocessed, compiled, assembled, and/or linked.
A file name can include the drive, directory, file name, and file extension.
The ccts compiler uses the file extension to determine the operations to
perform. Table 1-3 on page 1-9 lists the permitted extensions and matching compiler operations.
-@ filename
The -@ filename (command file) switch directs the compiler to read command-line input from filename. The specified filename must contain
driver options but may also contain source filenames and environment
variables. It can be used to store frequently used options as well as to read
from a file list.
-A name [(<tokens>)]
The -A (assert) switch directs the compiler to assert name as a predicate
with the specified tokens. This has the same effect as the #assert preprocessor directive. The following assertions are predefined:
Table 1-7. Predefined Assertions
Assertion Value
system
machine
cpu
compiler
embedded
adspts
adspts101 for ADSP-TS101 processor
adspts201 for ADSP-TS201 processor
adspts202 for ADSP-TS202 processor
adspts203 for ADSP-TS203 processor
ccts
VisualDSP++ 5.0 C/C++ Compiler Manual 1-23
for TigerSHARC Processors
Page 68
Compiler Command-Line Interface
The
-A name(value) switch is equivalent to including
#assert name(value)
in your source file, and both may be tested in a preprocessor condition in
the following manner:
#if #name(value)
// do something
#else
// do something else
#endif
For example, the default assertions may be tested as:
#if #machine(adspts)
// do something
#endif
L
-add-debug-libpaths
switch, to prevent misinterpretation. No quotes are needed for a
#assert directive in a source file.
The -add-debug-libpaths switch prepends the Debug subdirectory to the
search paths passed to the linker. The Debug subdirectory, found in each
of the silicon-revision-specific library directories, contains variants of certain libraries (for example, system services), which provide additional
diagnostic output to assist in debugging problems arising from their use.
Invoke this switch with the Use Debug System Libraries radio but-
The parentheses in the assertion need quotes when using the -A
L
ton located in the VisualDSP++ Project Options dialog box, Link
page, Processor category.
1-24 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 69
Compiler
-align-branch-lines
The -align-branch-lines switch instructs the assembler to align all
instruction lines containing a predicted branch to quad-word boundaries.
This is the default.
-allow-macs-to-extend-saturation
By default, the compiler will not try to generate multiply-accumulate
instructions if the add or subtract is saturating. The
-allow-macs-to-extend-saturation switch overrides that behavior. Note
that using this switch may result in different output as the multiplyaccumulate instruction will saturate to 40 bits for intermediate results and
then saturate to 32 bits on extraction from the accumulator.
-alttok
The -alttok (alternative tokens) switch directs the compiler to allow
alternative operator keywords and digraph sequences in source files. This
is the default mode. The -no-alttok switch (on page 1-42) can be used to
disallow such support.
The ANSI C trigraphs sequences are always expanded (even with the
-no-alttok option), and only digraph sequences are expanded in C source
files.
The following operator keywords are enabled by default.
Table 1-8. Keyword Equivalents
Keyword Equivalent
and &&
and_eq &=
bitand &
bitor |
compl ~
not !
VisualDSP++ 5.0 C/C++ Compiler Manual 1-25
for TigerSHARC Processors
Page 70
Compiler Command-Line Interface
Table 1-8. Keyword Equivalents (Cont’d)
Keyword Equivalent
not_eq !=
or ||
or_eq |=
xor ^
xor_eq ^=
L
To use alternative tokens in C, use #include <iso646.h>.
-always-inline
The -always-inline switch instructs the compiler to always attempt to
inline any call to a function that is defined with the inline qualifier. It is
equivalent to applying #pragma always_inline to all functions in the
module that have the inline qualifier. See also “-never-inline” on
page 1-42.
L
-annotate
The -annotate (enable assembly annotations) switch directs the compiler
to annotate assembly files generated by the compiler. The default behavior
is that whenever optimizations are enabled, all assembly files generated by
the compiler are annotated with information on the performance of the
generated assembly. See “Assembly Optimizer Annotations” on page 2-81
for more details on this feature.
Invoke this switch with the Always radio button located in the
Inlining area of the VisualDSP++ Project Options dialog box,
Compile page, General category.
L
1-26 VisualDSP++ 5.0 C/C++ Compiler Manual
Invoke this switch by checking the Generate assembly code anno-
tations check box located in the VisualDSP++ Project Options
dialog box, Compile page, General category.
for TigerSHARC Processors
Page 71
Compiler
-annotate-loop-instr
The -annotate-loop-instr switch directs the compiler to provide additional annotation information for the prolog, kernel and epilog of a loop.
See “Assembly Optimizer Annotations” on page 2-81 for more details on
this feature.
-auto-attrs
The -auto-attrs (automatic attributes) switch directs the compiler to
emit automatic attributes based on the files it compiles. Emission of automatic attributes is enabled by default. See “File Attributes” on page 1-312
for more information about attributes, and what automatic attributes the
compiler emits. See also the -no-auto-attrs switch (on page 1-43) and
the -file-attr switch (on page 1-34).
-bss
The -bss switch directs the compiler to place global zero-initialized data
into a BSS-style section (called “bsz”), rather than into normal global data
section. See also -no-bss switch (on page 1-43).
-build-lib
The -build-lib (build library) switch directs the compiler to use elfar
(librarian) to produce a library file (.dlb) as the output instead of using
the linker to produce an executable file (.dxe). The -o option must be
used to specify the name of the resulting library.
-C
The -C (comments) switch, which is only active in combination with the
-E or -P switches, directs the C preprocessor to retain comments in its
output file.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-27
for TigerSHARC Processors
Page 72
Compiler Command-Line Interface
-c
The -c (compile only) switch directs the compiler to compile and/or
assemble the source files, but stop before linking. The output is an object
file (.doj) for each source file.
-char-size-any
The -char-size-any switch indicates that the resulting object file should
be marked in such a way that it can link against objects marked with any
char size (8 bit or 32 bit). When linking a project with modules compiled
with 8-bit and 32-bit compilers, use the -char-size-any switch to avoid
any linking error messages.
L
L
-char-size-{8|32}
The -char-size-{8|32} switch specifies that chars are 8-bit data items
(byte addressing mode) or 32-bit data items (which is the default word
addressing mode). Selecting byte addressing mode also sets the macro
__TS_BYTE_ADDRESS to a value of 1. Use the -char-size-any switch to
avoid any linking error messages if both 8-bit and 32-bit modules are used
in building a project.
L
When a project is linked with a mixture of modules compiled in
both word and byte-addressed mode, only one version of the libraries (either word or byte-addressed) can be used. A combination of
both is not allowed.
Invoke this switch with the Allow mixing of sizes radio buttons
located in the VisualDSP++ Project Options dialog box, Compile
category, Processor (1) subcategory.
Invoke this switch with the Char size radio buttons located in the
VisualDSP++ Project Options dialog box, Compile tab,
Compile category, Processor (1) subcategory.
1-28 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 73
Compiler
-const-read-write
The -const-read-write switch directs the compiler to specify that constants may be accessed as read-write data (as in ANSI C). The compiler’s
default behavior assumes that data referenced through const pointers
never changes.
The -const-read-write switch changes the compiler’s behavior to match
the ANSI C assumption, which is that other non-const pointers may be
used to change the data at some point.
L
-const-strings
The -const-strings (const-qualify strings) switch directs the compiler to
mark string literals as const-qualified. This is the default behavior. See
also the -no-const-strings switch (on page 1-44).
L
-Dmacro[=definition]
The -D (define macro) switch directs the compiler to define a macro. If
you do not include the optional definition string, the compiler defines the
macro as the string ‘
constant, it must be surrounded by escaped double quotes. Note that the
compiler processes
fine macro) switches.
Invoke this switch with the Pointers to const may point to
non-const data check box located in the Constants area of the
VisualDSP++ Project Options dialog box, Compile page,
Language Settings category.
Invoke this switch with the Literal strings are const check box
located in the Constants area of the VisualDSP++ Project Options
dialog box, Compile page, Language Settings category.
1’. If definition is required to be a character string
-D switches on the command line before any -U (unde-
VisualDSP++ 5.0 C/C++ Compiler Manual 1-29
for TigerSHARC Processors
Page 74
Compiler Command-Line Interface
L
-debug-types
The -debug-types switch builds a *.h file directly and writes a complete
set of debugging information for the header file. The -g option need not
be specified with the -debug-types switch because it is implied.
For example,
Until the introduction of -debug-types, the compiler would not accept a
*.h file as a valid input file. The implicit -g option writes debugging
information for only those typedefs that are referenced in the program.
The -debug-types option provides complete debugging information for
all typedefs and structs.
-default-branch-{np|p}
The -default-branch-{np|p} switch instructs the assembler and linker to
set the branch behavior to be predictable or non-predictable. The default
is the predicted condition.
This switch can be invoked with the Definitions: dialog field
located in the VisualDSP++ Project Options dialog box, Compile
tab, Preprocessor category.
ccts -debug-types anyHeader.h
-double-size-any
The -double-size-any switch directs the compiler to mark the resulting
object file in such a way that it can link against objects marked with any
double size (32 bits and 64 bits).
L
1-30 VisualDSP++ 5.0 C/C++ Compiler Manual
Invoke this switch with the Allow mixing of sizes check box
located in the VisualDSP++ Project Options dialog box, Compile
page, Processor (1) category.
for TigerSHARC Processors
Page 75
Compiler
-double-size-{32 | 64}
The -double-size-32 (double is 32 bits) and -double-size-64 (double is
64 bits) switches select the storage format that the compiler uses for type
double. The -double-size-32 is the default mode.
The C/C++ type double poses a special problem for the compiler. The C
and C++ languages default to double for floating-point constants and
many floating-point calculations. If double has the customary size of 64
bits, many programs inadvertently use slow-speed 64-bit floating-point
emulated arithmetic, even when variables are declared consistently as
float. To avoid this problem, ccts provides a mode in which double is
the same size as float. This mode is enabled with the -double-size-32
switch and is the default mode.
Representing a double using 32 bits gives good performance and provides
enough precision for most DSP applications. This, however, does not fully
conform to the C and C++ standards. The standards require that double
maintains 10 digits of precision, which requires 64 bits of storage. The
-double-size-64 switch sets the size of double to 64 bits for full standard
conformance.
With -double-size-32, a double is stored in 32-bit IEEE single-precision
format and is operated on using fast hardware floating-point instructions.
Standard math functions, such as sin, also operate on 32-bit values. This
mode is the default and is recommended for most programs. Calculations
that need higher precision can be done with the long double type, which
is always 64 bits.
-double-size-64, a double is stored in 64-bit IEEE double preci-
With
sion format and is operated on using slow floating-point emulation
software. Standard math functions, such as
sin, also operate on 64-bit val-
ues and are similarly slow. This mode is recommended only for porting
code that requires that
double have more than 32 bits of precision.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-31
for TigerSHARC Processors
Page 76
Compiler Command-Line Interface
The
-double-size-32 switch defines the __DOUBLES_ARE_FLOATS__ pre-
processor macro, while the -double-size-64 switch undefines the
__DOUBLES_ARE_FLOATS__ preprocessor macro.
L
-dry
The -dry (verbose dry run) switch directs the compiler to display main
ccts actions, but not to perform them.
-dryrun
The -dryrun (terse dry run) switch directs the compiler to display
top-level ccts actions, but not to perform them.
-E
The -E (stop after preprocessing) switch directs the compiler to stop after
the C/C++ preprocessor runs (without compiling). The output (preprocessed source code) prints to the standard output stream (<stdout>) unless
the output file is specified with -o. Note that the -C switch can only be
run in combination with the -E switch.
L
Invoke this switch with the Double size radio buttons located in
the VisualDSP++ Project Options dialog box, Compile tab,
Compile category, Processor (1) subcategory.
Invoke it with the Stop after: Preprocessor check box located in
the VisualDSP++ Project Options dialog box, Compile tab,
General category.
-ED
The -ED (run after preprocessing to file) switch directs the compiler to
write the output of the C/C++ preprocessor to a file named
original_filename.i. After preprocessing, compilation proceeds
normally.
1-32 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 77
Compiler
L
-EE
The -EE (run after preprocessing) switch is similar to the -E switch, but it
does not halt compilation after preprocessing.
-enum-is-int
The -enum-is-int switch ensures that the type of an enum is int. By
default, the compiler defines enumeration types with integral types larger
than int, if int is insufficient to represent all the values in the enumeration. This switch prevents the compiler from selecting a type wider than
int.
L
-extra-keywords
Invoke this switch with the Generate preprocessed file check box
located in the VisualDSP++ Project Options dialog box, Compile
page, General category.
Invoke this switch with the Enumerated types are always int check
box located in the VisualDSP++ Project Options dialog box,
Compile page, Language Settings category.
The -extra-keywords (enable short-form keywords) switch directs the
compiler to recognize the Analog Devices keyword extensions to
ISO/ANSI standard C and C++. This recognition includes keywords, such
as pm and dm, without leading underscores which could affect conforming
ISO/ANSI C and C++ programs. This is the default mode.
-no-extra-keywords switch (on page 1-45) can be used to disallow
The
support for the additional keywords. Table 1-16 on page 1-91 provides a
list and a brief description of keyword extensions.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-33
for TigerSHARC Processors
Page 78
Compiler Command-Line Interface
-file-attr name[=value]
The -file-attr (file attribute) switch directs the compiler to add the
specified attribute name/value pair to all the files it compiles. To add multiple attributes, use the switch multiple times. If “=value” is omitted, the
default value of “1” will be used. See “File Attributes” on page 1-312 for
more information about attributes, and what automatic attributes the
compiler emits. See also the -auto-attrs switch (on page 1-27) and the
-no-auto-attrs switch (on page 1-43).
L
in the VisualDSP++ Project Options dialog box, Compile page,
General category.
Invoke this switch with the Additional attributes text field located
-flags-{asm|compiler|lib|link|mem} switch [,switch2 [,...]]
The -flags (command-line input) switch directs the compiler to pass
command-line switches to the other build tools. The tools are listed in
Table 1-9.
Table 1-9. Switches Passed to other Analog Devices’ Tools
Option Tool
-flags-asm Assembler
-flags-compiler Compiler executable
-flags-lib Library Builder (elfar.exe )
-flags-link Linker
-flags-mem Memory Initializer
-force-circbuf
The -force-circbuf (circular buffer) switch instructs the compiler to
make use of circular buffer facilities, even if the compiler cannot verify
that the circular index or pointer is always within the range of the buffer.
Without this switch, the compiler’s default behavior is conservative, and
1-34 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 79
Compiler
does not use circular buffers unless it can verify that the circular index or
pointer is always within the circular buffer range. See “Circular Buffer
Built-In Functions” on page 1-148.
L
-fp-associative
The -fp-associative switch directs the compiler to treat floating-point
multiplication and addition as an associative. This switch is on by default.
-fp-div-lib
The -fp-div-lib switch instructs the compiler to call a run-time library
support routine for 32-bit floating-point divides rather than inlining the
code. The inline sequence is faster, and is the recommended approach, but
is only accurate to one LSB. Use the -fp-div-lib switch if higher accuracy is required
If this switch is specified, a call is planted to a run-time support routine
with an entry point named “__divsf3” for the divide operation. This routine can be overridden by user-written routines if desired.
L
Invoke this switch with the Even when pointer may be outside
buffer range check box located in the VisualDSP++ Project
Options dialog box, Compile page, Language Settings category.
Invoke this switch with the Do not inline float/double divisions
check box located in the VisualDSP++ Project Options dialog box,
Compile page, Processor category.
-full-version
The -full-version (display versions) switch directs the compiler to display version information for build tools used in a compilation.
-g
The -g (generate debug information) switch directs the compiler to output symbols and other information used by the debugger.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-35
for TigerSHARC Processors
Page 80
Compiler Command-Line Interface
When the
tion) switch, the compiler performs standard optimizations. The compiler
also outputs symbols and other information to provide limited
source-level debugging through VisualDSP++ IDDE. This combination of
options provides line debugging and global variable debugging.
L
L
-glite
The -glite (lightweight debugging) switch can be used on its own, or in
conjunction with any of the -g, -Og or -debug-types compiler switches.
When this switch is enabled it instructs the compiler to remove any
unnecessary debug information for the code that is compiled.
-g switch is used in conjunction with the -O (enable optimiza-
When the -g and -O switches are specified, no debug information is
available for local variables and the standard optimizations can
sometimes rearrange program code in a way that inaccurate line
number information may be produced. For full debugging capabilities, use the -g switch without the -O switch. See also the -Og
switch (on page 1-49).
Invoke this switch by selecting the Generate debug information
check box in the VisualDSP++ Project Options dialog box,
Compile tab, General category.
When used on its own, the switch also enables the -g option.
L
-H
The -H (list headers) switch directs the compiler to output only a list of
the files included by the preprocessor via the
compiling.
1-36 VisualDSP++ 5.0 C/C++ Compiler Manual
This switch can be used to reduce the size of object and executable
files, but will have no effect on the size of the code loaded onto the
target.
#include directive, without
for TigerSHARC Processors
Page 81
Compiler
-HH
The -HH (list headers and compile) switch directs the compiler to output to
the standard out a list of the files included by the preprocessor via the
#include directive. After preprocessing, compilation proceeds normally.
-h[elp]
The -help (command-line help) switch directs the compiler to output a
list of command-line switches with a brief syntax description.
-I-
The -I- (start include directory list) switch establishes the point in the
include directory list at which the search for header files enclosed in angle
brackets begins. Normally, for header files enclosed in double quotes, the
compiler searches in the directory containing the current input file; then
the compiler reverts back to looking in the directories specified with the
-I switch and then in the standard include directory.
It is possible to replace the initial search (within the directory containing
the current input file) by placing the -I- switch at the point on the command line where the search for all types of header file begins. All include
directories on the command line specified before the -I- switch are used
only in the search for header files that are enclosed in double quotes.
Note that this switch removes the directory containing the current input
file from the include directory list.
L
VisualDSP++ 5.0 C/C++ Compiler Manual 1-37
for TigerSHARC Processors
Invoke this switch with the Additional include directories text
field located in the VisualDSP++ Project Options dialog box,
Compile page, Preprocessor category.
Page 82
Compiler Command-Line Interface
-I directory [{,|;} directory...]
The -I (include search directory) switch directs the C/C++ compiler preprocessor to append the directory (directories) to the search path for
include files. This option can be specified more than once; all specified
directories are added to the search path.
Include files, whose names are not absolute path names and that are
enclosed in “...” when included, are searched for in the following directories in this order:
1. The directory containing the current input file (the primary source
file or the file containing the #include)
2. Any directories specified with the -I switch in the order they are
listed on the command line
3. Any directories on the standard list:
<VDSP++ install dir>/.../include
L
-implicit-pointers
for by using directories defined in items 2 and 3 above.
The -implicit-pointers (implicit pointer conversion) switch allows a
pointer to one type to be converted to a pointer to another without the use
of an explicit cast. The compiler produces a discretionary warning rather
than an error in such circumstances. This option is not valid when compiling in C++ mode. For example,
If a file is included using the <...> form, this file is only searched
int *foo(int *a) {
return a;
}
int main(void) {
char *p = 0, *r;
r = foo(p); /* Bad: will normally give an error. */
return 0;
}
1-38 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 83
Compiler
Both the argument to
compiler. Using -implicit-pointers converts these errors into warnings.
L
-include filename
The -include (include file) switch directs the preprocessor to process the
specified file before processing the regular input file. Any -D and -U
options on the command line are always processed before an -include file.
Only one -include may be given.
-ipa
The -ipa (interprocedural analysis) switch directs the compiler to turn on
the interprocedural analysis option. This option enables optimization
across the entire program, including source files that are compiled separately. Using -ipa implicitly enables the -O switch. For more information,
see “Interprocedural Analysis” on page 1-80.
L
Invoke this switch with the Allow incompatible pointer types
check box located in the VisualDSP++ Project Options dialog box,
Compile page, Language Settings category.
Invoke this switch by selecting the Interprocedural Analysis check
box in the VisualDSP++ Project Options dialog box, Compile tab,
General category.
foo and the assignment to r will be faulted by the
-L directory [{,|;} directory...]
The -L (library search directory) switch directs the compiler to append the
directory to the search path for library files.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-39
for TigerSHARC Processors
Page 84
Compiler Command-Line Interface
-l library
The -l (link library) switch directs the compiler to search the library for
functions when linking. The library name is the portion of the file name
between the lib prefix and .dlb extension. For example, the -lc switch
directs the linker to search in the library named “c” for functions. This
library resides in a file named libc.dlb.
All object files should be listed on the command line before listing libraries using the -l switch. When a reference to a symbol is made, the symbol
definition will be taken from the left-most object or library on the command line that contains the global definition of that symbol. If two
objects on the command line contain definitions of the symbol x, x will be
taken from the left-most object on the command line that contains a global definition of x.
If one of the definitions for x comes from user objects, and the other from
a user library, and the library definition should be overridden by the user
object definition, it is important that the user object comes before the
library on the command line.
Libraries included in the default .ldf file are searched last for symbol
definitions.
-list-workarounds
The -list-workarounds (list supported errata workarounds) switch displays a list of all errata workarounds which the compiler supports. For
more information on valid revisions and the interactions of the -si-revi-
sion
, -workaround and -no-workaround switches, see
“Controlling Silicon Revision and Anomaly Workarounds within the
Compiler” on page 1-82.
1-40 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 85
Compiler
-M
The -M (generate make rules only) switch directs the compiler not to compile the source file, but to output a rule suitable for the make utility,
describing the dependencies of the main program file. The format of the
make rule output by the preprocessor is:
object-file: include-file …
-MD
The -MD (generate make rules and compile) switch directs the preprocessor
to print to a file called original_filename.d a rule describing the dependencies of the main program file. After preprocessing, compilation
proceeds normally. See also the –Mo switch.
-MM
The -MM (generate make rules and compile) switch directs the preprocessor
to print to stdout a rule describing the dependencies of the main program
file. After preprocessing, compilation proceeds normally.
-Mo filename
The -Mo filename (preprocessor output file) switch directs the compiler to
use filename for the output of –MD or –ED switches.
-Mt name
The -Mt name (output make rule for the named source) switch modifies
the target of generated dependencies, renaming the target to name. It only
has an effect when used in conjunction with the
-map filename
-M or -MM switch.
The -map (generate a memory map) switch directs the compiler to output
a memory map of all symbols. The map file name corresponds to the
filename argument; if the filename argument is test, the map file name
test.xml. The .xml extension is added where necessary.
is
VisualDSP++ 5.0 C/C++ Compiler Manual 1-41
for TigerSHARC Processors
Page 86
Compiler Command-Line Interface
-mem
The -mem (enable memory initialization) switch directs the compiler to
invoke the memory initializer after linking the executable file. The MemInit utility can be controlled through the -flags-mem switch
(on page 1-34).
-multiline
The -multiline switch enables a compiler GNU compatibility mode
which allows string literals to span multiple lines without the need for a
“\” at the end of each line. This is the default mode.
L
-never-inline
The -never-inline switch instructs the compiler to ignore the inline
qualifier on function definitions, so that no calls to such functions will be
inlined. See also “-always-inline” on page 1-26.
L
-no-align-branch-lines
The -no-align-branch-lines (disable alignment of predicted-taken
branch lines) switch directs the compiler not to align all instruction lines
containing a predicted branch to a quad-word boundary.
-no-alttok
The -no-alttok (disable alternative tokens) switch directs the compiler to
not accept alternative operator keywords and digraph sequences in the
source files. For more information, see the
Invoke this switch with the Allow multi-line character strings
check box located in the VisualDSP++ Project Options dialog box,
Compile page, Language Settings category.
Invoke this switch with the Never check box located in the Inlining
area of the VisualDSP++ Project Options dialog box, Compile
page, General category.
-alttok switch (on page 1-25).
1-42 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 87
Compiler
-no-annotate
The -no-annotate (disable assembly annotations) switch directs the compiler not to annotate assembly files generated by the compiler. The default
behavior is that whenever optimizations are enabled, all assembly files generated by the compiler are annotated with information on the
performance of the generated assembly. See “Assembly Optimizer Annota-
tions” on page 2-81 for more details on this feature.
L
-no-annotate-loop-instr
The -no-annotate-loop-instr switch disables the production of additional loop annotation information by the compiler. This is the default
mode.
-no-auto-attrs
The -no-auto-attrs (no automatic attributes) switch directs the compiler
not to emit automatic attributes based on the files it compiles. Emission of
automatic attributes is enabled by default. See “File Attributes” on
page 1-312 for more information about attributes, and what automatic
attributes the compiler emits. See also the -auto-attrs switch
(on page 1-27) and the
L
Invoke this switch by clearing the Generate assembly code annotations check box located in the VisualDSP++ Project Options
dialog box, Compile page, General category.
-file-attr switch (on page 1-34).
Invoke this switch by clearing the Auto-generated attributes check
box located in the VisualDSP++ Project Options dialog box,
Compile page, General category.
-no-bss
The -no-bss switch causes the compiler to keep zero-initialized and
non-zero-initialized data in the same data section, rather than separating
zero-initialized data into a different, BSS-style section. See also the
switch (on page 1-27).
VisualDSP++ 5.0 C/C++ Compiler Manual 1-43
for TigerSHARC Processors
-bss
Page 88
Compiler Command-Line Interface
-no-builtin
The -no-builtin (no built-in functions) switch directs the compiler not
to generate short names for the built-in functions (for example, abs()),
and to accept only the full name (for example, __builtin_abs()). For a
list of the extensions that use single machine instructions when -no-buil-
tin
is not used, see “Math Intrinsics” on page 1-149. This switch also
predefines the __NO_BUILTIN preprocessor macro.
L
-no-circbuf
The -no-circbuf (no circular buffer) switch disables the automatic generation of circular buffer code by the compiler. Uses of the circindex() and
circptr() functions (that is, explicit circular buffer operations) are not
affected.
L
-no-const-strings
The -no-const-strings switch directs the compiler not to make string literals
-no-defs
The -no-defs (disable defaults) switch directs the preprocessor not to
define any default preprocessor macros, include directories, library directories, libraries, or run-time headers. It also disables the Analog Devices
compiler C/C++ keyword extensions.
Invoke this switch by selecting the Disable builtin functions check
box in the VisualDSP++ Project Options dialog box, Compile tab,
Language Settings category.
Invoke this switch with the Never check box located in the
Circular Buffer Generation area of the VisualDSP++ Project
Options dialog box, Compile page, Language Settings category.
const qualified.
1-44 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 89
Compiler
-no-extra-keywords
The -no-extra-keywords (disable short-form keywords) switch directs the
compiler not to recognize the Analog Devices keyword extensions that
might affect conformance to ISO/ANSI programs. These extensions
include keywords, such as pm and dm, which may be used as identifiers in
conforming programs. The alternate keywords that are prefixed with two
leading underscores, such as __pm and __dm, continue to work. The
-extra-keyword switch (on page 1-33) can be used to explicitly request
support for the additional keywords.
L
-no-fp-associative
The -no-fp-associative switch directs the compiler NOT to treat
floating-point multiplication and addition as an associative.
L
-no-fp-minmax
The -no-fp-minmax (No floating-point MIN or MAX instructions) switch
prevents the compiler from generating floating-point
tions, when it inlines a floating-point comparison. The
instructions on TigerSHARC processors will return 0xFFFFFFFF if either
input value is a NaN. This can result in behavior not anticipated or
intended by the original user code.
L
Invoke this switch with the Disable Analog Devices extension keywords check box located in the VisualDSP++ Project Options
dialog box, Compile page, Language Settings category.
Invoke this switch with the Do not treat floating-point operations
as associative check box located in the VisualDSP++ Project
Options dialog box, Compile page, Language Settings category.
MIN or MAX instruc-
MAX and MIN
Invoke this switch with the Do not generate float/double
MIN/MAX check box located in the VisualDSP++ Project
Options dialog box, Compile page, Processor (1) category.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-45
for TigerSHARC Processors
Page 90
Compiler Command-Line Interface
-no-mem
The -no-mem (disable memory initialization) switch directs the compiler
not to run the MemInit utility. Note that if you use -no-mem, the compiler
does not initialize globals and statics.
-no-multiline
The -no-multiline switch disables a compiler GNU compatibility mode
which allows string literals to span multiple lines without the need for a
“\” at the end of each line.
L
-no-progress-rep-timeout
The -no-progress-rep-timeout (disable progress message for long compilation) switch disables the diagnostic message issued by the compiler to
indicate that it is still working, when a function’s compilation is taking an
excessively long time. The message is disabled by default. See also the
-progress-rep-timeout switch (on page 1-56) and the
-progress-rep-timeout-secs switch (on page 1-57).
-no-saturation
The -no-saturation switch directs the compiler not to introduce faster
operations in cases where the faster operation would saturate (if the
expression overflowed) when the original operation would have wrapped
the result. The code produced in this may may be less efficient than when
the switch is not used.
Saturation is enabled by default when optimizing, and may be disabled by
this switch. Saturation is disabled when not optimizing (for example, this
switch is the default when not optimizing).
Invoke this switch by clearing the Allow multi-line character
strings check box located in the VisualDSP++ Project Options dialog box, Compile page, Language Settings category.
1-46 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 91
Compiler
-no-std-ass
The -no-std-ass (disable standard assertions) switch prevents the compiler from defining the standard assertions. See the -A switch
(on page 1-23) for the list of standard assertions.
-no-std-def
The -no-std-def (disable standard macro definitions) prevents the compiler from defining any default preprocessor macro definitions.
L
-no-std-inc
The -no-std-inc (disable standard include search) switch directs the C
preprocessor to limit its search for header files to the current directory and
directories specified with -I switch.
L
-no-std-lib
The -no-std-lib (disable standard library search) switch directs the compiler to limit its search to those libraries specified with the -l switch.
-no-threads
The -no-threads (disable thread-safe build) switch specifies that all compiled code and libraries used in the build need not be thread-safe. This is
the default setting when the
not used.
This switch also disables the Analog Devices keyword extensions
which have no leading underscores, such as pm and dm.
Invoke this switch by selecting the Ignore standard include paths
check box in the VisualDSP++ Project Options dialog box,
Compile tab, Preprocessor category.
-threads (enable thread-safe build) switch is
VisualDSP++ 5.0 C/C++ Compiler Manual 1-47
for TigerSHARC Processors
Page 92
Compiler Command-Line Interface
-no-workaround workaround_id[,workaround_id …]
The -no-workaround workaround_id (disable avoidance of specific errata)
switch disables compiler code generator workarounds for specific hardware errata. For more information on valid revisions and the interactions
of the -si-revision, -workaround and -no-workaround switches, see
“Controlling Silicon Revision and Anomaly Workarounds within the
Compiler” on page 1-82.
-O
The -O (enable optimizations) switch directs the compiler to produce code
that is optimized for performance. Optimizations are not enabled by
default for the ccts compiler.
L
-O[0|1]
The -O [0|1] (enable/disable optimizations) switch allows the compiler to
select code optimization mode. Optimizations are not enabled by default
for the ccts compiler. (Note that the switch settings are numbers—zeros
or 1s—while the switch itself is the letter “O.”) The switch setting -O or
-O1 turns optimization on, while setting -O0 turns off all optimizations.
L
-Oa
The -Oa (automatic function inlining) switch enables the inline expansion
of C/C++ functions, which are not necessarily declared inline in the source
code. The amount of auto-inlining the compiler performs is controlled
using the –Ov num (optimize for speed versus size) switch (on page 1-49).
Invoke this switch by selecting the Enable optimization check box
in the VisualDSP++ Project Options dialog box, Compile tab,
General category.
Invoke this switch by selecting the Enable optimization check box
in the VisualDSP++ Project Options dialog box, Compile tab,
General category.
1-48 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 93
Compiler
The
-Ov100 setting attempts to optimize purely for speed (and therefore
inline a greater number of functions) whereas the -Ov0 setting attempts to
optimize purely for space (and therefore inline fewer functions).
L
-Og
The -Og switch enables a compiler mode that attempts to perform optimizations while still preserving the debugging information. It is meant as an
alternative for those who want a debuggable program but who are also
concerned about the performance of their debuggable code.
-Os
The -Os (optimize for size) switch directs the compiler to produce code
that is optimized for size. This is achieved by performing all optimizations
except those that increase code size. The optimizations not performed
include loop unrolling, some delay slot filling, and jump avoidance. The
compiler also uses a function to save and restore preserved registers for a
function instead of generating the more cycle-efficient inline default
versions.
-Ov num
Invoke this switch with the Automatic check box located in the
Inlining area of the VisualDSP++ Project Options dialog box,
Compile page, General category.
For any given optimization, the compiler modifies the code being generated. Some optimizations produce code that will execute in fewer cycles,
but which will require more code space. In such cases, there is a trade-off
between speed and space.
The -Ov num (optimize for speed versus size) switch informs the compiler
of the relative importance of speed versus size, when considering whether
such trade-offs are worthwhile. The
between 0 (purely size) and 100 (purely speed).
VisualDSP++ 5.0 C/C++ Compiler Manual 1-49
for TigerSHARC Processors
num variable should be an integer
Page 94
Compiler Command-Line Interface
0
Execution
count
Optimize for speed
-Ovnum
0100
Infinity
Optimize for space
Limit line
The
num variable indicates a sliding scale between 0 and 100 which is the
probability that a linear piece of generated code – a “basic block” – will be
optimized for speed or for space. At -Ov0 all blocks are optimized for space
and at -Ov100 all blocks are optimized for speed. At any point in between,
the decision is based upon num and how many times the block is expected
to be executed – the “execution count” of the block. Figure 1-1 demonstrates this relationship.
1-50 VisualDSP++ 5.0 C/C++ Compiler Manual
Figure 1-1. -Ov Switch Optimization Curve
For any given optimization where speed and size conflict, the potential
benefit is dependent on the execution count: an optimization that
increases performance at the expense of code size is considerably more
beneficial if applied to the core loop of a critical algorithm than if applied
for TigerSHARC Processors
Page 95
Compiler
to one-time initialization code or to rarely-used error-handling functions.
If code only appears to be executed once, it will be optimized for space. As
its execution count increases, so too does the likelihood that the compiler
will consider the code increase worthwhile for the corresponding benefit
in performance.
As Figure 1-1 shows, the
cution count is considered sufficient to switch optimization from “for
space” to “for speed”. Where num is a low value, the compiler is biased
towards space, so a block’s execution count has to be relatively high for the
compiler to apply code-increasing transformations. Where num has a high
value, the compiler is biased towards speed, so the same transformation
will be considered valid for a much lower execution count.
The -Ov switch is most effective when used in conjunction with profileguided optimization, where accurate execution counts are available. Without profile-guided optimization, the compiler makes estimates of the
relative execution counts using heuristics.
L
For more information, see “Using Profile-Guided Optimization” in
Chapter 2, Achieving Optimal Performance from C/C++ Source Code.
-o filename
The -o (output file) switch directs the compiler to use filename for the
name of the final output file.
Invoke this switch with the Optimize for code size/speed slider
located in the VisualDSP++ Project Options dialog box, Compile
page, General category.
-Ov switch affects the point at which a given exe-
-overlay
The -overlay (program may use overlays) switch will disable the propagation of register information between functions and force the compiler to
assume that all functions clobber all scratch registers. Note that this switch
will affect all functions in the source file, and may result in a performance
VisualDSP++ 5.0 C/C++ Compiler Manual 1-51
for TigerSHARC Processors
Page 96
Compiler Command-Line Interface
degradation. For information on disabling the propagation of register
information only for specific functions, see “#pragma overlay” on
page 1-210.
-P
The -P (omit line numbers) switch directs the compiler to stop after the C
preprocessor runs (without compiling) and to omit the #line preprocessor
directives (with line number information) in the output from the preprocessor. The -C switch may be used in combination with the -P switch.
-PP
The -PP (omit line numbers and compile) switch directs the compiler to
omit the #line preprocessor directives with line number information from
the preprocessor output. After preprocessing, compilation proceeds
normally.
-path-{ asm | compiler | lib | link } pathname
The -path-{asm|compiler|lib|link} pathname (tool location) switch
directs the compiler to use the specified component in place of the
default-installed version of the compilation tool. The component comprises a relative or absolute path to its location. Respectively, the tools are
the assembler, compiler, librarian, or linker. Use this switch when overriding the normal version of one or more of the tools. The -path-{...}
switch also overrides the directory specified by the
-path-install directory
The -path-install (installation location) switch directs the compiler to
use the specified directory as the location for all compilation tools instead
of the default path. This is useful when working with multiple versions of
the tool set.
L
1-52 VisualDSP++ 5.0 C/C++ Compiler Manual
You can selectively override this switch with the -path-{asm|
compiler|lib|link}
switch.
-path-install switch.
for TigerSHARC Processors
Page 97
Compiler
-path-output directory
The -path-output (non-temporary files location) switch directs the compiler to place final output files in the specified directory.
-path-temp directory
The -path-temp (temporary files location) switch directs the compiler to
place temporary files in the specified directory.
-pch
The -pch (precompiled header) switch directs the compiler to automatically generate and use precompiled header files. A precompiled output
header has a .pch extension attached to the source file name. By default,
all precompiled headers are stored in a directory called PCHRepository.
L
-pchdir directory
The -pchdir (locate PCHRepository) switch specifies the location of an
alternative PCHRepository for storing and invocation of precompiled
header files. If the directory does not exist, the compiler creates it. Note
that the -o (output) switch does not influence the -pchdir option.
-pgo-session session-id
The -pgo-session session-id (specify PGO session identifier) switch is
used with profile-guided optimization. It has the following effects:
Precompiled header files can significantly speed compilation; precompiled headers tend to occupy more disk space.
• When used with the -pguide switch (on page 1-54), the compiler
associates all counters for this module with the session identifier
session-id.
• When used with a previously-gathered profile (a .pgo file), the
compiler ignores the profile contents, unless they have the same
session-id identifier.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-53
for TigerSHARC Processors
Page 98
Compiler Command-Line Interface
This is most useful when the same source file is being built in more than
one way (for example, different macro definitions, or for multiple processors) in the same application; each variant of the build can have a different
session-id associated with it, which means that the compiler will be able
to identify which parts of the gathered profile should be used when optimizing for the final build.
If each source file is built only in a single manner within the system (the
usual case), then the -pgo-session switch is not needed.
L
For more information, see “Using Profile-Guided Optimization” in
Chapter 2, Achieving Optimal Performance from C/C++ Source Code.
-pguide
The -pguide (PGO) switch causes the compiler to add instrumentation
for the gathering of a profile (a .pgo file) as the first stage of performing
profile-guided optimization.
L
For more information, see “Using Profile-Guided Optimization” in
Chapter 2, Achieving Optimal Performance from C/C++ Source Code.
-pplist filename
The -pplist (preprocessor listing) switch directs the preprocessor to output a listing to the named file. When more than one source file is
preprocessed, the listing file contains information about the last file processed. The generated file contains raw source lines, information on
transitions into and out of include files, and diagnostics generated by the
compiler.
Invoke this switch with the PGO session name text field located in
the VisualDSP++ Project Options dialog box, Compile page, Pro-
file-Guided Optimization category.
Invoke this switch with the Prepare application to create new pro-
file check box located in the VisualDSP++ Project Options dialog
box, Compile page, Profile-Guided Optimization category.
1-54 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Page 99
Each listing line begins with a key character that identifies its type as:
Table 1-10. Key Characters
Character Meaning
N Normal line of source
X Expanded line of source
S Line of source skipped by #if or #ifdef
L Change in source position
R Diagnostic message (remark)
W Diagnostic message (warning)
E Diagnostic message (error)
C Diagnostic message (catastrophic error)
-proc processor
Compiler
The -proc processor (target processor) switch specifies that the compiler
produces code suitable for the specified processor. Refer to “Supported
Processors” for the list of supported TigerSHARC processors.
For example,
ccts -proc ADSP-TS201 -o bin\p1.doj p1.asm
If no target is specified with the -proc switch, the system uses the
L
ADSP-TS101 setting as a default.
When compiling with the -proc switch, the appropriate processor macro
is defined as 1.
See also “-si-revision version” on page 1-59 for more information
L
on silicon revision of the specified processor.
VisualDSP++ 5.0 C/C++ Compiler Manual 1-55
for TigerSHARC Processors
Page 100
Compiler Command-Line Interface
-progress-rep-func
The -progress-rep-func switch provides feedback on the compiler’s
progress that may be useful when compiling and optimizing very large
source files. It issues a “warning” message each time the compiler starts
compiling a new function. The “warning” message is a remark that is disabled by default, and this switch enables the remark as a warning. The
switch is equivalent to -Wwarn=cc1472.
-progress-rep-gen-opt
The -progress-rep-gen-opt switch provides feedback on the compiler’s
progress that may be useful when compiling and optimizing a very large,
complex function. It issues a “warning” message each time the compiler
starts a new generic optimization pass on the current function. The
“warning” message is a remark that is disabled by default, and this switch
enables the remark as a warning. The switch is equivalent to
-Wwarn=cc1473.
-progress-rep-mc-opt
The -progress-rep-mc-opt switch provides feedback on the compiler’s
progress that may be useful when compiling and optimizing a very large,
complex function. It issues a “warning” message each time the compiler
starts a new machine-specific optimization pass on the current function.
The “warning” message is a remark that is disabled by default, and this
switch enables the remark as a warning. The switch is equivalent to
-Wwarn=cc1474.
-progress-rep-timeout
The -progress-rep-timeout switch issues a diagnostic message if the
compiler exceeds a time limit during compilation. This indicates the compiler is still operating, just taking a long time.
1-56 VisualDSP++ 5.0 C/C++ Compiler Manual
for TigerSHARC Processors
Loading...