ANALOG DEVICES W4.5 Library Manual

Download

W4.5

C/C++ Compiler and Library Manual

for TigerSHARC

Revision 3.0, April 2006

Processors

Analog Devices, Inc. One Technology Way Norwood, Mass. 02062-9106

Part Number

82-000336-03

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, 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.

CONTENTS

PREFACE

Purpose of This Manual ............................................................ xxxvii

Intended Audience .................................................................... xxxvii

Manual Contents Description .................................................. xxxviii

What’s New in This Manual ..................................................... xxxviii

Technical or Customer Support .................................................. xxxix

Supported Processors ....................................................................... xl

Product Information ....................................................................... xl

MyAnalog.com .......................................................................... xl

Processor Product Information .................................................. xli

Related Documents ................................................................. xlii

Online Technical Documentation ........................................... xliii

Accessing Documentation From VisualDSP++ .................... xliii

Accessing Documentation From Windows ........................... xliv

Accessing Documentation From the Web ............................. xliv

Printed Manuals ....................................................................... xlv

VisualDSP++ Documentation Set ......................................... xlv

VisualDSP++ 4.5 C/C++ Compiler and Library Manual iii for TigerSHARC Processors

CONTENTS

Hardware Tools Manuals ..................................................... xlv

Processor Manuals ............................................................... xlv

Data Sheets ......................................................................... xlv

Notation Conventions ................................................................. xlvii

COMPILER

C/C++ Compiler Overview ........................................................... 1-3

Compiler Command-Line Interface .............................................. 1-5

Running the Compiler ............................................................ 1-6

Compiler Command-Line Switches ....................................... 1-11

C/C++ Compiler Switch Summaries .................................. 1-11

C/C++ Mode Selection Switch Descriptions ...................... 1-22

-c89 ............................................................................. 1-22

-c++ ............................................................................. 1-22

C/C++ Compiler Common Switch Descriptions ................ 1-23

sourcefile ...................................................................... 1-23

-@ filename .................................................................. 1-23

-A name [(<tokens>)] .................................................... 1-23

-add-debug-libpaths ...................................................... 1-25

-align-branch-lines ........................................................ 1-25

-allow-macs-to-extend-saturation .................................. 1-25

-alttok .......................................................................... 1-25

-always-inline ............................................................... 1-26

-annotate-loop-instr ...................................................... 1-27

-auto-attrs .................................................................... 1-27

iv VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

-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

-Dmacro[=definition] .................................................... 1-29

-debug-types ................................................................. 1-30

-default-branch-{np|p} ................................................... 1-30

-double-size-any ............................................................ 1-31

-double-size-{32 | 64} .................................................... 1-31

-dry .............................................................................. 1-32

-dryrun ......................................................................... 1-32

-E ................................................................................. 1-33

-ED .............................................................................. 1-33

-EE ............................................................................... 1-33

-enum-is-int .................................................................. 1-34

-extra-keywords ............................................................. 1-34

-file-attr name[=value] ................................................... 1-34

-flags-{asm|compiler|lib|link|mem} switch [,switch2 [,...]] 1-35

-force-circbuf ................................................................ 1-35

-fp-associative ............................................................... 1-35

VisualDSP++ 4.5 C/C++ Compiler and Library Manual v for TigerSHARC Processors

CONTENTS

-fp-div-lib ..................................................................... 1-36

-full-version .................................................................. 1-36

-g ................................................................................. 1-36

-glite ............................................................................ 1-37

-H ................................................................................ 1-37

-HH ............................................................................. 1-37

-h[elp] .......................................................................... 1-37

-I- ................................................................................ 1-38

-I directory [{,|;} directory...] ......................................... 1-38

-implicit-pointers .......................................................... 1-39

-include filename .......................................................... 1-40

-ipa .............................................................................. 1-40

-L directory [{,|;} directory...] ........................................ 1-40

-l library ....................................................................... 1-40

-M ............................................................................... 1-41

-MD ............................................................................ 1-41

-MM ............................................................................ 1-41

-Mo filename ................................................................ 1-42

-Mt name ..................................................................... 1-42

-MQ ............................................................................ 1-42

-map filename .............................................................. 1-42

-mem ........................................................................... 1-42

-multiline ..................................................................... 1-43

-never-inline ................................................................. 1-43

vi VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

-no-align-branch-lines ................................................... 1-43

-no-alttok ..................................................................... 1-43

-no-annotate ................................................................. 1-43

-no-annotate-loop-instr ................................................. 1-44

-no-auto-attrs ................................................................ 1-44

-no-bss .......................................................................... 1-44

-no-builtin .................................................................... 1-45

-no-circbuf .................................................................... 1-45

-no-const-strings ........................................................... 1-45

-no-defs ........................................................................ 1-45

-no-extra-keywords ........................................................ 1-46

-no-fp-associative .......................................................... 1-46

-no-fp-minmax ............................................................. 1-46

-no-mem ....................................................................... 1-47

-no-multiline ................................................................ 1-47

-no-saturation ............................................................... 1-47

-no-std-ass .................................................................... 1-47

-no-std-def .................................................................... 1-47

-no-std-inc .................................................................... 1-48

-no-std-lib .................................................................... 1-48

-no-threads ................................................................... 1-48

-O ................................................................................ 1-48

-O[0|1] ......................................................................... 1-49

-Oa ............................................................................... 1-49

VisualDSP++ 4.5 C/C++ Compiler and Library Manual vii for TigerSHARC Processors

CONTENTS

-Og .............................................................................. 1-49

-Os ............................................................................... 1-50

-Ov num ...................................................................... 1-50

-o filename ................................................................... 1-52

-overlay ........................................................................ 1-52

-P ................................................................................. 1-52

-PP ............................................................................... 1-53

-path-{ asm | compiler | lib | link | mem } directory ........ 1-53

-path-install directory ................................................... 1-53

-path-output directory .................................................. 1-53

-path-temp directory ..................................................... 1-53

-pch ............................................................................. 1-54

-pchdir directory ........................................................... 1-54

-pedantic ...................................................................... 1-54

-pedantic-errors ............................................................ 1-54

-pgo-session session-id .................................................. 1-55

-pguide ......................................................................... 1-56

-pplist filename ............................................................. 1-56

-proc processor ............................................................. 1-57

-progress-rep-func ......................................................... 1-57

-progress-rep-gen-opt .................................................... 1-58

-progress-rep-mc-opt ..................................................... 1-58

-R directory [{:|,}directory …] ....................................... 1-58

-R- ............................................................................... 1-59

viii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

-S ................................................................................. 1-59

-s .................................................................................. 1-59

-save-temps ................................................................... 1-59

-section id=section_name[,id=section_name...] .............. 1-60

-show ............................................................................ 1-61

-si-revision version ........................................................ 1-61

-signed-bitfield .............................................................. 1-62

-signed-char .................................................................. 1-62

-structs-do-not-overlap .................................................. 1-62

-syntax-only .................................................................. 1-63

-sysdefs ......................................................................... 1-63

-T filename ................................................................... 1-64

-threads ........................................................................ 1-64

-time ............................................................................ 1-65

-Umacro ....................................................................... 1-65

-unsigned-bitfield .......................................................... 1-65

-unsigned-char .............................................................. 1-66

-v .................................................................................. 1-66

-verbose ........................................................................ 1-66

-version ......................................................................... 1-66

-W {error|remark|suppress|warn} number ....................... 1-67

-Werror-limit number ................................................... 1-67

-Werror-warnings .......................................................... 1-67

-Wremarks .................................................................... 1-67

VisualDSP++ 4.5 C/C++ Compiler and Library Manual ix for TigerSHARC Processors

CONTENTS

C++ Mode Compiler Switch Descriptions ......................... 1-71

-Wterse ......................................................................... 1-68

-w ................................................................................ 1-68

-warn-protos ................................................................. 1-68

-workaround <workaround>[,<workaround>]* .............. 1-68

-write-files .................................................................... 1-69

-write-opts .................................................................... 1-69

-xref <filename> ............................................................ 1-69

-anach .......................................................................... 1-71

-check-init-order ........................................................... 1-72

-eh ............................................................................... 1-73

-full-dependency-inclusion ............................................ 1-73

-ignore-std .................................................................... 1-75

-no-anach ..................................................................... 1-75

-no-demangle ............................................................... 1-75

-no-eh .......................................................................... 1-75

-no-implicit-inclusion ................................................... 1-75

-no-rtti ......................................................................... 1-75

-rtti .............................................................................. 1-76

Data Types and Data Type Sizes ............................................ 1-77

Integer Data Types ........................................................... 1-78

Floating-Point Data Types ................................................ 1-78

Data Type Alignment ............................................................ 1-79

Environment Variables Used by the Compiler ........................ 1-80

x VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

Optimization Control ............................................................ 1-81

Interprocedural Analysis .................................................... 1-84

Interaction with Libraries .............................................. 1-85

C/C++ Compiler Language Extensions ........................................ 1-87

Byte-Addressing Mode ........................................................... 1-91

sizeof() Operator Types and Sizes ....................................... 1-91

Pointers ............................................................................ 1-92

Alignment of Objects ........................................................ 1-92

Initializations .................................................................... 1-93

Pragmas Used in Byte-Addressing Mode ............................ 1-93

Performance Issues ............................................................ 1-93

Libraries Used in Byte-Addressing Mode ............................ 1-94

Include Files ..................................................................... 1-95

Function Inlining .................................................................. 1-95

Inline Assembly Language Support Keyword (asm) ............... 1-100

Assembly Construct Template ......................................... 1-102

ASM() Construct Syntax: ............................................ 1-102

ASM() Construct Syntax Rules .................................... 1-103

ASM() Construct Template Example ........................... 1-104

Assembly Construct Operand Description ....................... 1-105

Assembly Constructs With Multiple Instructions ............. 1-110

Assembly Construct Reordering and Optimization ........... 1-111

Assembly Constructs With Input and Output Operands .. 1-112

Assembly Constructs and Flow Control ........................... 1-113

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xi for TigerSHARC Processors

CONTENTS

Guidelines on the Use of asm() Statements ...................... 1-113

64-Bit Integer Support (long long) ...................................... 1-114

Quad-Word Support ........................................................... 1-115

Memory Support Keywords (pm dm) .................................. 1-115

Memory Keyword Rules .................................................. 1-115

__regclass Construct ........................................................... 1-117

Bank Type Qualifiers ........................................................... 1-118

Placement Support Keyword (section) ................................. 1-119

Placement of Compiler-Generated Code and Data ............... 1-120

Boolean Type Support Keywords ......................................... 1-121

Pointer Class Support Keyword (restrict) ............................. 1-121

Variable-Length Array Support ............................................ 1-122

Non-Constant Aggregate Initializer Support ........................ 1-124

Indexed Initializer Support .................................................. 1-124

Compiler Built-In Functions ............................................... 1-126

Using the builtins.h Header File ...................................... 1-127

Optimization Guidance Built-in Functions ..................... 1-129

16-Bit Data Types .......................................................... 1-131

Packed 16-bit Integer Support Using C ....................... 1-132

Constructors (int2x16 values) ..................................... 1-132

Extractors and Expanders (int2x16 values) ................... 1-133

Arithmetic Operators .................................................. 1-133

Bitwise Operators (int2x16 values) .............................. 1-134

Comparison Operators (int2x16 values) ...................... 1-135

xii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

Sideways Sum (int2x16 values) .................................... 1-135

Constructors (int4x16 values) ...................................... 1-136

Extractors (2x16 from a 4x16 value) ............................ 1-137

Arithmetic Operators (int4x16 values) ......................... 1-138

Sideways Sum (int4x16 values) .................................... 1-139

32-Bit Data Types ........................................................... 1-140

Constructors (int2x32 values) ...................................... 1-140

Extractors (int2x32 values) .......................................... 1-141

Circular Buffer Built-In Functions ................................... 1-142

Circular Buffer Increment of an Index ......................... 1-142

Circular Buffer Increment of a Pointer ......................... 1-142

Math Intrinsics ............................................................... 1-143

RECIPS ...................................................................... 1-144

RSQRTS .................................................................... 1-145

Instructions Generated by Built-in Functions ................... 1-145

Data Alignment Buffer (DAB) Built-in Functions ............ 1-161

Circular Buffer Data Alignment Buffer (DAB) Built-in Functions

1-162

Communications Logic Unit Operations ......................... 1-164

TMAX, TMAX_ADD, TMAX_SUB, MAX_ADD, MAX_SUB

1-165

PERMUTE ................................................................. 1-170

ACS ............................................................................ 1-171

DESPREAD ............................................................... 1-174

XCORRS .................................................................... 1-176

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xiii for TigerSHARC Processors

CONTENTS

Pragmas .............................................................................. 1-179

Data Alignment Pragmas ................................................ 1-181

#pragma align num ..................................................... 1-182

#pragma alignment_region (alignopt) .......................... 1-183

Interrupt Handler Pragmas ............................................. 1-185

Loop Optimization Pragmas ........................................... 1-187

#pragma all_aligned .................................................... 1-188

#pragma different_banks ............................................. 1-188

#pragma loop_count(min, max, modulo) .................... 1-188

#pragma loop_unroll N .............................................. 1-189

#pragma no_alias ........................................................ 1-191

#pragma no_vectorization ........................................... 1-192

#pragma vector_for ..................................................... 1-192

Function Side-Effect Pragmas ......................................... 1-193

#pragma alloc ............................................................. 1-193

#pragma const ............................................................ 1-194

#pragma noreturn ....................................................... 1-194

#pragma pure ............................................................. 1-194

#pragma regs_clobbered string .................................... 1-195

#pragma regs_clobbered_call string ............................. 1-199

#pragma overlay ......................................................... 1-202

#pragma result_alignment (n) ..................................... 1-203

General Optimization Pragmas ....................................... 1-203

Inline Control Pragmas ................................................... 1-204

xiv VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

#pragma always_inline ................................................ 1-205

#pragma never_inline .................................................. 1-206

Linking Control Pragmas ................................................ 1-206

#pragma linkage_name identifier ................................. 1-206

#pragma core ............................................................. 1-207

#pragma section/#pragma default_section .................... 1-212

#pragma file_attr (name[=value] [, name[=value] [...]]) 1-214

#pragma weak_entry .................................................. 1-215

Class Conversion Optimization Pragmas .......................... 1-216

#pragma param_never_null param_name [ ... ] ............ 1-216

#pragma suppress_null_check ...................................... 1-217

Template Instantiation Pragmas ....................................... 1-219

#pragma instantiate instance ........................................ 1-220

#pragma do_not_instantiate instance ........................... 1-220

#pragma can_instantiate instance ................................. 1-220

Header File Control Pragmas ........................................... 1-221

#pragma hdrstop ......................................................... 1-221

#pragma no_implicit_inclusion ................................... 1-222

#pragma no_pch ......................................................... 1-223

#pragma once ............................................................. 1-223

#pragma system_header ............................................... 1-223

Diagnostic Control Pragmas ............................................ 1-223

Modifying the Severity of Specific Diagnostics ............. 1-224

Modifying the Behavior of an Entire Class of Diagnostics 1-225

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xv for TigerSHARC Processors

CONTENTS

Saving or Restoring the Current Behavior of All Diagnostics ..

1-225

Memory Bank Pragmas ................................................... 1-226

#pragma code_bank(bankname) .................................. 1-227

#pragma data_bank(bankname) .................................. 1-228

#pragma stack_bank(bankname) ................................. 1-229

#pragma bank_memory_kind(bankname, kind) ........... 1-230

#pragma bank_read_cycles(bankname, cycles) ............. 1-231

#pragma bank_write_cycles(bankname, cycles) ............ 1-231

#pragma bank_optimal_width(bankname, width) ........ 1-232

Increments and Decrements ................................................ 1-233

C++ Style Comments .......................................................... 1-233

C++ Fractional Type Support .............................................. 1-234

Format of Fractional Literals ........................................... 1-234

Conversions Involving Fractional Values .......................... 1-235

Fractional Arithmetic Operations .................................... 1-235

Mixed-Mode Operations ................................................. 1-236

GCC Compatibility Extensions ........................................... 1-237

Statement Expressions .................................................... 1-237

Type Reference Support Keyword (typeof) ...................... 1-238

GCC Generalized Lvalues ............................................... 1-239

Conditional Expressions With Missing Operands ............ 1-240

Hexadecimal Floating-Point Numbers ............................. 1-240

Zero-Length Arrays ........................................................ 1-241

Variable Argument Macros .............................................. 1-241

xvi VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

Line Breaks in String Literals ........................................... 1-242

Arithmetic on Pointers to Void and Pointers to Functions 1-242

Cast to Union ................................................................. 1-242

Ranges in Case Labels ..................................................... 1-242

Declarations Mixed With Code ....................................... 1-243

Escape Character Constant .............................................. 1-243

Alignment Inquiry Keyword (__alignof__) ...................... 1-243

(asm) Keyword for Specifying Names in Generated Assembler 1-244 Function, Variable and Type Attribute Keyword (__attribute__)

1-244

Unnamed struct/union fields within struct/unions ........... 1-245

Preprocessor-Generated Warnings ........................................ 1-245

Preprocessor Features ................................................................ 1-246

Predefined Preprocessor Macros ........................................... 1-246

Writing Macros ................................................................... 1-249

C/C++ Run-Time Model and Environment ............................... 1-252

Stack Frame Overview ......................................................... 1-253

Stack Frame Description ...................................................... 1-255

General System-Wide Specifications ................................ 1-257

At a procedure call, the following must be true: ............ 1-258

Argument Passage ........................................................... 1-259

Return Values ................................................................. 1-260

Procedure Call and Return .............................................. 1-261

To Call a Procedure: .................................................... 1-261

On Entry: ................................................................... 1-261

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xvii for TigerSHARC Processors

CONTENTS

To Return from a Procedure: ....................................... 1-262

Code Sequences .............................................................. 1-263

Support for argv/argc .......................................................... 1-264

Allocation of Memory for Stacks and Heaps in LDFs ........... 1-265

Example of Heap/Stack Memory Allocation .................... 1-265

Using Multiple Heaps ......................................................... 1-266

Heap Identifiers .............................................................. 1-267

Initializing the Heap ....................................................... 1-268

Using Alternate Heaps with the Standard Interface .......... 1-268

Using the Alternate Heap Interface ................................. 1-269

C++ Run-time Support for the Alternate Heap Interface 1-270

Using the Heap_Install Interface ..................................... 1-271

Miscellaneous Information .................................................. 1-273

Callee Preserved Registers (“Preserved”) .......................... 1-273

Caller Save Registers (“Scratch”) ...................................... 1-274

ADSP-TS101 and ADSP-TS20x Processor Registers ........ 1-274

C/C++ and Assembly Language Interface .................................. 1-280

Calling Assembly Subroutines From C/C++ Programs .......... 1-280

Calling C/C++ Functions From Assembly Programs ............. 1-283

Using Mixed C/C++ and Assembly Naming Conventions 1-284

C++ Programming Examples ............................................... 1-286

Using Fract Type Support ............................................... 1-286

Using Complex Number Support .................................... 1-287

xviii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

Compiler C++ Template Support ............................................... 1-289

Template Instantiation ......................................................... 1-289

Identifying Un-instantiated Templates ................................. 1-291

File Attributes ........................................................................... 1-293

Automatically-applied Attributes .......................................... 1-293

Default LDF Placement ....................................................... 1-295

Sections versus Attributes .................................................... 1-295

Granularity ..................................................................... 1-296

“Hard” versus “soft” ........................................................ 1-296

Number of values ............................................................ 1-297

Using attributes ................................................................... 1-297

Example ......................................................................... 1-298

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

Using Profile-Guided Optimization With a Simulator ...... 2-9

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xix for TigerSHARC Processors

CONTENTS

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-11

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-15

Getting the Most From IPA ................................................... 2-16

Initialize Constants Statically ............................................ 2-17

Quad-Word-Aligning Your Data ....................................... 2-18

Using __builtin_aligned ................................................... 2-18

Avoiding Aliases ............................................................... 2-20

Indexed Arrays Versus Pointers .............................................. 2-22

Trying Pointer and Indexed Styles ..................................... 2-23

Function Inlining .................................................................. 2-23

Using Inline asm Statements .................................................. 2-24

Memory Usage ...................................................................... 2-25

Putting Arrays into Different Memory Sections ................. 2-25

Using the Bank Qualifier .................................................. 2-28

Improving Conditional Code ...................................................... 2-28

Loop Guidelines ......................................................................... 2-29

Keeping Loops Short ............................................................. 2-29

Avoiding Unrolling Loops ..................................................... 2-30

xx VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

Avoiding Loop-Carried Dependencies .................................... 2-30

Avoiding Loop Rotation by Hand .......................................... 2-31

Avoiding Array Writes in Loops ............................................. 2-33

Inner Loops Versus Outer Loops ............................................ 2-33

Avoiding Conditional Code in Loops ..................................... 2-34

Avoiding Placing Function Calls in Loops .............................. 2-35

Avoiding Non-Unit Strides ................................................... 2-35

Loop Control ........................................................................ 2-36

Using the Restrict Qualifier ................................................... 2-37

Using the Const Qualifier ...................................................... 2-38

Avoiding Long Latencies ........................................................ 2-38

Using Built-In Functions in Code Optimization .......................... 2-40

Using Fractional Data ............................................................ 2-40

System Support Built-in Functions ......................................... 2-41

Using Circular Buffers ........................................................... 2-42

Smaller Applications: Optimizing for Code Size ........................... 2-44

Using Pragmas for Optimization .................................................. 2-46

Function Pragmas .................................................................. 2-46

#pragma const .................................................................. 2-46

#pragma pure .................................................................... 2-47

#pragma regs_clobbered .................................................... 2-47

#pragma optimize_{off|for_speed|for_space} ...................... 2-49

Loop Optimization Pragmas .................................................. 2-49

#pragma loop_count ......................................................... 2-49

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xxi for TigerSHARC Processors

CONTENTS

#pragma no_vectorization ................................................. 2-50

#pragma vector_for ........................................................... 2-50

#pragma all_aligned .......................................................... 2-51

#pragma different_banks .................................................. 2-53

#pragma no_alias .............................................................. 2-53

Useful Optimization Switches ..................................................... 2-54

How Loop Optimization Works .................................................. 2-55

Terminology ......................................................................... 2-55

Clobbered ........................................................................ 2-55

Live .................................................................................. 2-56

Spill ................................................................................. 2-56

Scheduling ....................................................................... 2-56

Loop kernel ...................................................................... 2-56

Loop prolog ..................................................................... 2-57

Loop epilog ...................................................................... 2-57

Loop invariant .................................................................. 2-57

Hoisting ........................................................................... 2-57

Sinking ............................................................................ 2-58

Loop Optimization Concepts ................................................ 2-58

Software pipelining ........................................................... 2-59

Loop Rotation .................................................................. 2-59

Loop Vectorization ........................................................... 2-62

Modulo Scheduling .......................................................... 2-64

Variable expansion ........................................................ 2-66

xxii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

CONTENTS

A Worked Example ................................................................ 2-69

Assembly Optimizer Annotations ................................................ 2-72

Global Information ............................................................... 2-74

Procedure Statistics ................................................................ 2-75

Loop Identification ................................................................ 2-79

Loop Identification Annotations ........................................ 2-80

File Position ...................................................................... 2-84

Vectorization ......................................................................... 2-85

Unroll and Jam ................................................................. 2-87

Loop Flattening ................................................................ 2-89

Vectorization Annotations ................................................. 2-90

Modulo Scheduling ............................................................... 2-92

Warnings, Failure Messages and Advice ................................ 2-100

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

Linking Library Functions ....................................................... 3-5

Working With Library Source Code ......................................... 3-8

Working With Library Header Files ......................................... 3-9

assert.h ............................................................................. 3-11

ctype.h ............................................................................. 3-11

cycle_count.h .................................................................... 3-11

cycles.h ............................................................................. 3-12

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xxiii for TigerSHARC Processors

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-15

math.h ............................................................................. 3-15

setjmp.h ........................................................................... 3-16

signal.h ............................................................................ 3-16

stdarg.h ............................................................................ 3-17

stddef.h ............................................................................ 3-17

stdio.h .............................................................................. 3-17

stdlib.h ............................................................................. 3-20

string.h ............................................................................ 3-20

time.h .............................................................................. 3-21

DSP Header Files .................................................................. 3-22

complex.h – Basic Complex Arithmetic Functions ............. 3-23

filter.h – DSP Filters and Transformations ......................... 3-24

libsim.h – Simulator Services ............................................ 3-25

matrix.h – Matrix Functions ............................................. 3-26

stats.h – Statistical Functions ............................................ 3-27

vector.h – Vector Functions ............................................... 3-28

window.h – Window Generators ....................................... 3-29

xxiv VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Calling Library Functions from an ISR .................................. 3-31

Abridged C++ Library Support .............................................. 3-32

Embedded C++ Library Header Files ................................. 3-32

complex ........................................................................ 3-32

exception ...................................................................... 3-33

fract .............................................................................. 3-33

fstream .......................................................................... 3-33

iomanip ........................................................................ 3-33

ios ................................................................................ 3-33

iosfwd ........................................................................... 3-34

iostream ........................................................................ 3-34

istream .......................................................................... 3-34

new .............................................................................. 3-34

ostream ......................................................................... 3-34

sstream ......................................................................... 3-34

stdexcept ....................................................................... 3-34

streambuf ...................................................................... 3-35

string ............................................................................ 3-35

strstream ....................................................................... 3-35

C++ Header Files for C Library Facilities ........................... 3-35

Embedded Standard Template Library Header Files ........... 3-36

algorithm ...................................................................... 3-36

deque ............................................................................ 3-37

functional ..................................................................... 3-37

VisualDSP++ 3.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxv

hash_map ..................................................................... 3-37

hash_set ....................................................................... 3-37

iterator ......................................................................... 3-37

list ................................................................................ 3-37

map .............................................................................. 3-37

memory ........................................................................ 3-37

numeric ........................................................................ 3-37

queue ........................................................................... 3-38

set ................................................................................ 3-38

stack ............................................................................. 3-38

utility ........................................................................... 3-38

vector ........................................................................... 3-38

fstream.h ...................................................................... 3-38

iomanip.h ..................................................................... 3-38

iostream.h .................................................................... 3-38

new.h ........................................................................... 3-39

Using the Thread-Safe C/C++ Run-Time Libraries with VDK 3-39

Measuring Cycle Counts ....................................................... 3-39

Basic Cycle Counting Facility ............................................ 3-40

Cycle Counting Facility with Statistics .............................. 3-41

Using time.h to Measure Cycle Counts .............................. 3-44

Determining the Processor Clock Rate .............................. 3-46

Considerations When Measuring Cycle Counts ................. 3-47

File I/O Support ................................................................... 3-49

xxvi VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Extending I/O Support To New Devices ............................ 3-50

DevEntry Structure ....................................................... 3-50

Registering New Devices ............................................... 3-55

Pre-Registering Devices ................................................. 3-56

Default Device .............................................................. 3-57

Remove and Rename Functions ..................................... 3-58

Default Device Driver Interface ......................................... 3-58

Data Packing For Primitive I/O ..................................... 3-60

Data Structure for Primitive I/O .................................... 3-60

Documented Library Functions ................................................... 3-65

Run-Time Library Reference ....................................................... 3-69

a_compress ................................................................................. 3-70

a_expand .................................................................................... 3-71

abs .............................................................................................. 3-72

acos ............................................................................................ 3-73

addbitrev .................................................................................... 3-74

alog ............................................................................................ 3-75

alog10 ........................................................................................ 3-77

arg .............................................................................................. 3-79

asctime ....................................................................................... 3-80

asin ............................................................................................. 3-82

atan ............................................................................................ 3-83

atan2 .......................................................................................... 3-84

atof ............................................................................................. 3-85

VisualDSP++ 3.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxvii

atoi ............................................................................................ 3-87

atol ............................................................................................ 3-88

atold .......................................................................................... 3-89

atoll ........................................................................................... 3-91

autocoh ...................................................................................... 3-92

autocorr ..................................................................................... 3-93

avg ............................................................................................. 3-94

bsearch ....................................................................................... 3-95

cabs ............................................................................................ 3-97

cadd ........................................................................................... 3-98

cartesian ..................................................................................... 3-99

cdiv .......................................................................................... 3-101

ceil ........................................................................................... 3-102

cexp ......................................................................................... 3-103

cfft ........................................................................................... 3-104

cfft_mag ................................................................................... 3-107

cfft2d ....................................................................................... 3-109

cfftf .......................................................................................... 3-111

clearerr ..................................................................................... 3-113

clip .......................................................................................... 3-114

clock ........................................................................................ 3-115

cmatmadd ................................................................................ 3-117

cmatmmlt ................................................................................ 3-119

cmatmsub ................................................................................ 3-121

xxviii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

cmatsadd .................................................................................. 3-123

cmatsmlt ................................................................................... 3-124

cmatssub ................................................................................... 3-126

cmlt .......................................................................................... 3-128

conj .......................................................................................... 3-129

convolve ................................................................................... 3-130

conv2d ..................................................................................... 3-132

copysign ................................................................................... 3-134

cos ............................................................................................ 3-135

cosh .......................................................................................... 3-136

cot ............................................................................................ 3-137

count_ones ............................................................................... 3-138

crosscoh .................................................................................... 3-139

crosscorr ................................................................................... 3-140

csub .......................................................................................... 3-141

ctime ........................................................................................ 3-142

cvecdot ..................................................................................... 3-143

cvecsadd ................................................................................... 3-144

cvecsmlt .................................................................................... 3-145

cvecssub .................................................................................... 3-146

cvecvadd ................................................................................... 3-147

cvecvmlt ................................................................................... 3-148

cvecvsub ................................................................................... 3-149

difftime .................................................................................... 3-150

VisualDSP++ 3.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxix

div ........................................................................................... 3-152

exp ........................................................................................... 3-153

__emuclk ................................................................................. 3-154

fabs .......................................................................................... 3-155

favg .......................................................................................... 3-156

fclip ......................................................................................... 3-157

fclose ........................................................................................ 3-158

feof .......................................................................................... 3-159

ferror ........................................................................................ 3-160

fir ............................................................................................ 3-161

fir_decima ................................................................................ 3-163

fir_interp .................................................................................. 3-166

fflush ....................................................................................... 3-172

fgetc ......................................................................................... 3-173

fgetpos ..................................................................................... 3-174

fgets ......................................................................................... 3-176

floor ......................................................................................... 3-178

fmax ......................................................................................... 3-179

fmin ......................................................................................... 3-180

fmod ........................................................................................ 3-181

fopen ....................................................................................... 3-182

fprintf ...................................................................................... 3-184

fputc ........................................................................................ 3-190

fputs ........................................................................................ 3-191

xxx VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

fread ......................................................................................... 3-192

freopen ..................................................................................... 3-194

frexp ......................................................................................... 3-196

fscanf ........................................................................................ 3-197

fseek ......................................................................................... 3-201

fsetpos ...................................................................................... 3-203

ftell ........................................................................................... 3-204

fwrite ........................................................................................ 3-205

gen_bartlett .............................................................................. 3-207

gen_blackman ........................................................................... 3-209

gen_gaussian ............................................................................. 3-210

gen_hamming ........................................................................... 3-211

gen_hanning ............................................................................. 3-212

gen_harris ................................................................................. 3-213

gen_kaiser ................................................................................. 3-214

gen_rectangular ........................................................................ 3-216

gen_triangle .............................................................................. 3-217

gen_vonhann ............................................................................ 3-219

getc .......................................................................................... 3-220

getchar ...................................................................................... 3-221

gets ........................................................................................... 3-222

gmtime ..................................................................................... 3-224

histogramf ................................................................................ 3-226

ifft ............................................................................................ 3-228

VisualDSP++ 3.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxxi

ifft2d ........................................................................................ 3-230

iir ............................................................................................. 3-232

interrupt, interruptf, interrupts, interruptnr, interruptfnr,

interruptsnr ........................................................................... 3-235

localtime .................................................................................. 3-240

log ........................................................................................... 3-242

log10 ........................................................................................ 3-243

matinv ..................................................................................... 3-244

matmadd .................................................................................. 3-245

matmmlt .................................................................................. 3-246

matmsub .................................................................................. 3-248

matsadd ................................................................................... 3-249

matsmlt .................................................................................... 3-250

matssub .................................................................................... 3-251

max .......................................................................................... 3-252

mean ........................................................................................ 3-253

min .......................................................................................... 3-254

mktime .................................................................................... 3-255

modf ........................................................................................ 3-257

mu_compress ........................................................................... 3-258

mu_expand .............................................................................. 3-259

norm ........................................................................................ 3-260

perror ....................................................................................... 3-261

polar ........................................................................................ 3-262

pow .......................................................................................... 3-263

xxxii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

printf ........................................................................................ 3-264

putc .......................................................................................... 3-265

putchar ..................................................................................... 3-266

puts .......................................................................................... 3-267

qsort ......................................................................................... 3-268

raise .......................................................................................... 3-270

rand .......................................................................................... 3-273

remove ...................................................................................... 3-274

rename ..................................................................................... 3-275

rewind ...................................................................................... 3-277

rfft ............................................................................................ 3-278

rfft_mag ................................................................................... 3-281

rfft2d ........................................................................................ 3-283

rfftf .......................................................................................... 3-285

rfftf_mag .................................................................................. 3-287

rms ........................................................................................... 3-289

rsqrt ......................................................................................... 3-290

scanf ......................................................................................... 3-291

setbuf ....................................................................................... 3-293

setvbuf ...................................................................................... 3-295

sign .......................................................................................... 3-297

signal, signalf, signals, signalnr, signalfnr, signalsnr ..................... 3-298

sin ............................................................................................ 3-302

sinh .......................................................................................... 3-303

VisualDSP++ 3.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxxiii

snprintf .................................................................................... 3-304

sprintf ...................................................................................... 3-306

sqrt .......................................................................................... 3-308

srand ........................................................................................ 3-309

sscanf ....................................................................................... 3-310

strftime .................................................................................... 3-312

strtod ....................................................................................... 3-316

strtof ........................................................................................ 3-318

strtoi ........................................................................................ 3-320

strtol ........................................................................................ 3-322

strtold ...................................................................................... 3-324

strtoll ....................................................................................... 3-326

strtoul ...................................................................................... 3-328

strtoull ..................................................................................... 3-330

tan ........................................................................................... 3-332

tanh ......................................................................................... 3-333

time ......................................................................................... 3-334

transpm .................................................................................... 3-335

twidfft ...................................................................................... 3-336

twidfftf ..................................................................................... 3-338

ungetc ...................................................................................... 3-340

var ........................................................................................... 3-342

vecdot ...................................................................................... 3-343

vecsadd .................................................................................... 3-344

xxxiv VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

vecsmlt ..................................................................................... 3-345

vecssub ..................................................................................... 3-346

vecvadd ..................................................................................... 3-347

vecvmlt ..................................................................................... 3-348

vecvsub ..................................................................................... 3-349

vfprintf ..................................................................................... 3-350

vprintf ...................................................................................... 3-352

vsnprintf ................................................................................... 3-354

vsprintf ..................................................................................... 3-356

zero_cross ................................................................................. 3-358

INDEX

VisualDSP++ 3.0 C/C++ Compiler and Library Manual for TigerSHARC DSPs xxxv

xxxvi VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

PREFACE

Thank you for purchasing Analog Devices, Inc. development software for digital signal processing (DSP) applications.

Purpose of This Manual

The VisualDSP++ 4.5 C/C++ Compiler and Library Manual for TigerSHARC Processors contains information about the C/C++ compiler

and run-time library for TigerSHARC 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.

(ADSP-TSxxx) processors. It

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 your target architecture.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xxxvii

for TigerSHARC Processors

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++ 4.5 C/C++Compiler and Library Manual for TigerSHARC Processors documents support for all currently available

TigerSHARC processors listed in “Supported Processors”.

Refer to the VisualDSP++ 4.5 Product Release Bulletin for a complete list of new compiler features and enhancements.

xxxviii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

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/technicalSupport

• E-mail tools questions to

processor.tools.support@analog.com

• 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

Preface

• 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

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xxxix for TigerSHARC Processors

Supported Processors

The name “TigerSHARC” refers to a family of Analog Devices, Inc. floating-point and [8-bit, 16-bit, and 32-bit] fixed-point processors. VisualDSP++ currently supports the following TigerSHARC processors:

ADSP-TS101 ADSP-TS202

ADSP-TS201 ADSP-TS203

Product Information

You can obtain product information from the Analog Devices Web site, from the product CD-ROM, or from the printed publications (manuals).

Analog Devices is online at mation about a broad range of products—analog integrated circuits, amplifiers, converters, and digital signal processors.

www.analog.com. Our Web site provides infor-

MyAnalog.com

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 on products you are interested in. You can also choose to receive weekly e-mail notifications containing updates to the Web pages that meet your interests. sheets, code examples, and more.

Registration

Visit Registration takes about five minutes and serves as a means to select the information you want to receive.

MyAnalog.com provides access to books, application notes, data

www.myanalog.com to sign up. Click Register to use MyAnalog.com.

xl VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Preface

If you are already a registered user, just log on. Your user name is your e-mail address.

Processor Product Information

For information on embedded processors and DSPs, visit our Web site at

www.analog.com/processors, which provides access to technical publica-

tions, data sheets, application notes, product overviews, and product announcements.

You may also obtain additional information about Analog Devices and its products in any of the following ways.

• E-mail questions or requests for information to

processor.support@analog.com (World wide support) processor.europe@analog.com (Europe support) processor.china@analog.com (China support)

• Fax questions or requests for information to

1-781-461-3010 (North America) +49-89-76903-157 (Europe)

• Access the FTP Web site at

ftp ftp.analog.com (or ftp 137.71.25.69) ftp://ftp.analog.com

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xli for TigerSHARC Processors

Product Information

Online Technical Documentation

Online documentation includes the VisualDSP++ Help system, software tools manuals, hardware tools manuals, processor manuals, Dinkum Abridged C++ library, and Flexible License Manager (FlexLM) network license manager software documentation. You can easily search across the entire VisualDSP++ documentation set for any topic of interest using the Search function of VisualDSP++ Help system. For easy printing, supplementary

Each documentation file type is described as follows.

File Description

.CHM Help system files and manuals in Help format

.PDF files of most manuals are also provided.

.HTM or .HTML

.PDF VisualDSP++ and processor manuals in Portable Documentation Format (PDF).

Dinkum Abridged C++ library and FlexLM network license manager software documentation. Viewing and printing the Internet Explorer 5.01 (or higher).

Viewing and printing the Reader (4.5 or higher).

.PDF files requires a PDF reader, such as Adobe Acrobat

.HTML files requires a browser, such as

Access the online documentation from the VisualDSP++ environment, Windows® Explorer, or the Analog Devices Web site.

Accessing Documentation From VisualDSP++

From the VisualDSP++ environment:

• Access VisualDSP++ online Help from the Help menu’s Contents, Search, and Index commands.

• Open online Help from context-sensitive user interface items (toolbar buttons, menu commands, and windows).

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xliii for TigerSHARC Processors

Product Information

Accessing Documentation From Windows

In addition to any shortcuts you may have constructed, there are many ways to open VisualDSP++ online Help or the supplementary documentation from Windows.

Help system files (.

CHM) are located in the Help folder of VisualDSP++

environment. The .PDF files are located in the Docs folder of your VisualDSP++ installation CD-ROM. The Docs folder also contains the Dinkum Abridged C++ library and the FlexLM network license manager software documentation.

Using Windows Explorer

• Double-click the vdsp-help.chm file, which is the master Help system, to access all the other .CHM files.

• Open your VisualDSP++ installation CD-ROM and double-click any file that is part of the VisualDSP++ documentation set.

Using the Windows Start Button

• Access VisualDSP++ online Help by clicking the Start button and choosing Programs, Analog Devices, VisualDSP++, and VisualDSP++ Documentation.

Accessing Documentation From the Web

Download manuals in PDF format at the following Web site:

http://www.analog.com/processors/resources/technicalLibrary/manuals

Select a processor family and book title. Download archive (.ZIP) files, one for each manual. Use any archive management software, such as WinZip, to decompress downloaded files.

xliv VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Preface

Printed Manuals

For general questions regarding literature ordering, call the Literature Center at 1-800-ANALOGD (1-800-262-5643) and follow the prompts.

VisualDSP++ Documentation Set

To purchase VisualDSP++ manuals, call 1-603-883-2430. The manuals may be purchased only as a kit.

If you do not have an account with Analog Devices, you are referred to Analog Devices distributors. For information on our distributors, log onto

http://www.analog.com/salesdir/continent.asp.

Hardware Tools Manuals

To purchase EZ-KIT Lite® and In-Circuit Emulator (ICE) manuals, call 1-603-883-2430. The manuals may be ordered by title or by product number located on the back cover of each manual.

Processor Manuals

Hardware reference and instruction set reference manuals may be ordered through the Literature Center at 1-800-ANALOGD (1-800-262-5643), or downloaded from the Analog Devices Web site. Manuals may be ordered by title or by product number located on the back cover of each manual.

Data Sheets

All data sheets (preliminary and production) may be downloaded from the Analog Devices Web site. Only production (final) data sheets (Rev. 0, A, B, C, and so on) can be obtained from the Literature Center at 1-800-ANALOGD (1-800-262-5643); they also can be downloaded from the Web site.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xlv for TigerSHARC Processors

Product Information

To have a data sheet faxed to you, call the Analog Devices Faxback System at 1-800-446-6212. Follow the prompts and a list of data sheet code numbers will be faxed to you. If the data sheet you want is not listed, check for it on the Web site.

xlvi VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Notation Conventions

Text conventions used in this manual are identified and described as follows.

Example Description

Preface

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.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual xlvii for TigerSHARC Processors

Notation Conventions

Additional conventions, which apply only to specific chapters, may appear throughout this document.

xlviii VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

1 COMPILER

The C/C++ compiler (ccts) is part of Analog Devices development software for TigerSHARC (ADSP-TSxxx) processors.

This chapter contains:

The code examples in this manual have been compiled using VisualDSP++ 4.5. 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-87 describes the for the C and C++ languages.

• “Preprocessor Features” on page 1-246 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-252 contains reference information about implementation of C/C++ programs, data, and function calls in TigerSHARC processors

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-1 for TigerSHARC Processors

• “C/C++ and Assembly Language Interface” on page 1-280 describes how to call an assembly language subroutine from C or C++ program, and how to call a C or C++ function from within an assembly language program.

• “Compiler C++ Template Support” on page 1-289 describes how templates are instantiated at compile time

1-2 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

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 ccts compiler runs from the VisualDSP++ 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 ( ates 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++ 4.5 C/C++ Compiler and Library Manual 1-3 for TigerSHARC Processors

easmts). The assembler cre-

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-87.

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-77, and “Byte-Addressing Mode” on page 1-91.

For more information on the VisualDSP++ environment, see online Help.

1-4 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

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-11

• “Data Types and Data Type Sizes” on page 1-77

• “Data Type Alignment” on page 1-79

• “Environment Variables Used by the Compiler” on page 1-80

• “Optimization Control” on page 1-81

Compiler

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 .DXE file. (See file names in Table 1-3 on

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-12. A summary of the C++ specific compiler switches appears in Table 1-6 on page 1-21. The summaries are followed by descriptions of each switch.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-5 for TigerSHARC Processors

When developing a DSP project, sometimes it is useful to modify 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.

Compiler Command-Line Interface

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

Command Element

ccts Name of the compiler program for TigerSHARC processors.

-switch Switch (or switches) to process.

sourceFile Name of the file to be preprocessed, compiled, assembled, and/or linked

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.

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

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.

ccts compiler uses the file extension to determine what the file con-

The tains and what operations to perform upon it. Table 1-3 on page 1-9 lists the allowed extensions.

1-6 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

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

Compiler

ccts -proc ADSP-TS101 -c++ source.cpp

runs ccts with:

-c++ Specifies that all of the source files to be com-

piled 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:

If multiple files are specified, each is first processed to produce an object file; then all object files are presented to the linker.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-7 for TigerSHARC Processors

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

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) and -L directory switch (on page 1-40).

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.

• 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.

1-8 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

• 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.

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

Using the verbose output switches for the preprocessor, compiler,

.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

.dlb Library of object files to be linked as needed

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-9 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-3. Input and Output Files (Cont’d)

Input File Extension File Extension Description

.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-80 for more information.

1-10 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

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 or C++ Mode Selection Switches”

• Table 1-5 “C/C++ Compiler Common Switches” on page 1-12

• Table 1-6 “C++ Mode Compiler Switches” on page 1-21

A brief description of each switch follows the tables, beginning

on page 1-22.

Table 1-4. C or C++ Mode Selection Switches

Switch Name Description

-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

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-11 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-5. C/C++ Compiler Common Switches

Switch Name Description

-allow-macs-to-extend-saturation

(on page 1-25)

sourcefile

(on page 1-23)

-@ filename

(on page 1-23)

-A name[tokens]

(on page 1-23)

-add-debug-libpaths

(on page 1-25)

-align-branch-lines

(on page 1-25)

-alttok

(on page 1-25)

-always-inline

(on page 1-26)

-annotate-loop-instr

(on page 1-27)

-auto-attrs

(on page 1-35)

Instructs the compiler to try to generate multiply-accumulate instructions using saturating add and subtract operations.

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

Allows alternative keywords and sequences in sources

Tr e a t s

inline keyword as a requirement rather than a

suggestion.

Provides additional annotation information for the prolog, kernel and epilog of a loop

Directs the compiler to emit automatic attributes based on the files it compiles. Enabled by default.

-bss

(on page 1-27)

-build-lib

Causes the compiler to place global zero-initialized data into a separate BSS-style section

Directs the librarian to build a library file

(on page 1-27)

-C

(on page 1-27)

-c

Retains preprocessor comments in the output file; active only with the

-E or -P switch)

Compiles and/or assembles only; does not link

(on page 1-28)

-char-size-any

(on page 1-28

Indicate that the resulting object can link against any char size object

1-12 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-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-31)

-double-size-{32|64}

(on page 1-31)

-dry

(on page 1-32)

-dryrun

(on page 1-32)

-E

(on page 1-33)

-ED

(on page 1-33)

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

Selects 32- or 64-bit IEEE format for double; the

-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)

Preprocesses, but does not compile, the source file

Preprocesses and sends all output to a file

-EE

Preprocesses and compiles the source file

(on page 1-33)

-enum-is-int

(on page 1-34)

-extra-keywords

(on page 1-34)

-file-attr name[=value]

(on page 1-35)

By default option ensures the

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

enums can have a type larger than int. This

enum type is int.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-13 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-flags-{tools} <arg1> [,arg2...]

(on page 1-35)

-force-circbuf

(on page 1-35)

-fp-associative

(on page 1-35)

-fp-div-lib

(on page 1-36)

-full-version

(on page 1-36)

-g

(on page 1-36)

-glite

(on page 1-37)

-H

(on page 1-37)

-HH

(on page 1-37)

-h[elp]

(on page 1-37)

Passes command-line switches through the compiler to other build tools

Treats array references of the form

array[i%n] as circular

buffer operations

Treats floating-point multiply and addition as an associative

Do not use inline code for floating-point divides

Displays version information for build tools

Generates DWARF-2 debug information

Generates lightweightDWARF-2 debug information

Outputs a list of header files, but does not compile the source file

Outputs a list of included header files and compiles

Outputs a list of command-line switches with brief syntax descriptions

-I-

(on page 1-38)

Establishes the point in the

include directory list at

which the search for header files enclosed in angle brackets should begin

-I directory

Appends directory to the standard search path.

(on page 1-38)

-implicit-pointers

(on page 1-39)

-include filename

Demotes incompatible-pointer-type errors into discretionary warnings. Not valid when compiling in C++ mode.

Includes named file prior to preprocessing each source file

(on page 1-40)

1-14 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-ipa

(on page 1-40)

-L directory

(on page 1-40)

-l library

(on page 1-40)

-M

(on page 1-41)

-MD

(on page 1-41)

-MM

(on page 1-41)

-Mo filename

(on page 1-42)

-Mt filename

(on page 1-42)

-MQ

(on page 1-42)

-map filename

(on page 1-42)

-mem

(on page 1-42)

Enables interprocedural analysis

Appends the specified directory to the standard library search path when linking

Searches the specified library for functions when linking

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 filename. This switch is used in conjunction with the -ED or -MD options.

Makes dependencies, where the target is renamed as

filename

Generates make rules only; does not compile. No notification when input files are missing

Directs the linker to generate a memory map of all symbols

Enables memory initialization

-multiline

Enables string literals over multiple lines (default)

(on page 1-43)

-never-inline

inline keyword on function definitions

Ignores

(on page 1-43)

-no-align-branch-lines

Do not align predicted branches to a quad word boundary

(on page 1-43)

-no-alttok

(on page 1-43)

Does not allow alternative keywords and sequences in sources

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-15 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-no-annotate

(on page 1-43)

-no-annotate-loop-instr

(on page 1-44)

-no-auto-attrs

(on page 1-35)

-no-bss

(on page 1-44)

-no-builtin

(on page 1-45)

-no-circbuf

(on page 1-45)

-no-const-strings

(on page 1-45)

-no-defs

(on page 1-45)

-no-extra-keywords

(on page 1-46)

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-143.

Disables the automatic generation of circular buffer code by the compiler

Indicates that string literals should not be qualified as

const

Does not define any default preprocessor macros, include directories, library directories, libraries, run-time headers, or keyword extensions

Does not define language extension keywords that could be valid C or C++ identifiers

-no-fp-associative

(on page 1-46)

-no-mem

Does not treat floating-point multiply and addition as an associative

Disables memory initialization

(on page 1-47)

-no-multiline

Disables multiple line string literal support

(on page 1-47)

-no-saturation

(on page 1-47)

-no-std-ass

(on page 1-47)

Causes the compiler not to introduce saturation semantics when optimizing expressions

Disables any predefined assertions and system-specific macro definitions

1-16 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-no-std-def

(on page 1-47)

-no-std-inc

(on page 1-48)

-no-std-lib

(on page 1-48)

-no-threads

(on page 1-48)

-O

(on page 1-48)

-O [0|1]

(on page 1-49)

-Oa

(on page 1-49)

-Og

(on page 1-49)

-Os

(on page 1-50)

-Ov num

(on page 1-50)

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 the

-l switch when linking

Specifies that compiled code does not need to be thread-safe

Enables code optimizations

Enables/disables code optimizations

Enables automatic function inlining

Enables a compiler mode that performs optimizations while still preserving the debugging information

Optimizes for code size

Controls speed vs. size optimizations

-o filename

Specifies the output file name

(on page 1-52)

-P

(on page 1-52)

-PP

(on page 1-53)

-path-{asm|compiler|lib| link|mem} directory

(on page 1-53)

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, linker, or and memory initializer, respectively)

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-17 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-path-install directory

(on page 1-53)

-path-output directory

(on page 1-53)

-path-temp directory

(on page 1-53)

-pch

(on page 1-54)

-pchdir directory

(on page 1-54)

-pedantic

(on page 1-54)

-pedantic-errors

(on page 1-54)

-pguide

(on page 1-56)

-pplist filename

(on page 1-56)

-proc processor

(on page 1-57)

-progress-rep-func

(on page 1-57)

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)

Specifies the location of PCHRepository

Issues compiler warnings for any constructs that are not ISO/ANSI standard C/C++-compliant

Issues compiler errors for any constructs that are not ISO/ANSI standard C/C++-compliant

Adds instrumentation for the gathering of a profile as the first stage of performing profile-guided optimization

Outputs a raw preprocessed listing to the specified file

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.

-progress-rep-gen-opt

(on page 1-58)

-progress-rep-mc-opt

(on page 1-58)

-R directory

(on page 1-58)

Issues a diagnostic message each time the compiler starts a new generic optimization pass on the current function. Equivalent to

-Wwarn=cc1473.

Issues a diagnostic message each time the compiler starts a new machine-specific optimization pass on the current function. Equivalent to

-Wwarn=cc1473.

Appends directory to the standard search path for source files

1-18 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-R-

(on page 1-59)

-S

(on page 1-59)

-s

(on page 1-59)

-save-temps

(on page 1-59)

-section id=section_name

(on page 1-60)

-show

(on page 1-61)

-si-revision version

(on page 1-61)

-signed-bitfield

(on page 1-62)

-signed-char

(on page 1-62)

-structs-do-not-overlap

(on page 1-62)

-syntax-only

(on page 1-63)

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.

Makes the default type for plain int bitfields signed

Makes the default type for

char signed

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

-sysdefs

Defines the system definition macros

(on page 1-63)

-T filename

(on page 1-64)

-threads

Uses the specified the Linker Description File as control input for linking

Specifies that the build and link should be thread-safe

(on page 1-64)

-time

(on page 1-65)

Displays the elapsed time as part of the output information on each part of the compilation process

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-19 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-Umacro

(on page 1-65)

-unsigned-bitfield

(on page 1-65)

-unsigned-char

(on page 1-66)

-v

(on page 1-66)

-verbose

(on page 1-66)

-version

(on page 1-66)

-W{error|remark| suppress|warn} number

(on page 1-67)

-Werror-limit number

(on page 1-67)

-Wremarks

(on page 1-67)

-Wterse

(on page 1-68)

Undefines macro(s)

Makes the default type for plain int bitfields unsigned

Makes the default type for

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

Overrides the default severity of the specified diagnosticmessages (errors, remarks, or warnings)

Stops compiling after reaching the specified number of errors

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

-w

Disables all warnings

(on page 1-68)

-warn-protos

Issues warnings about functions without prototypes

(on page 1-68)

-workaround <workaround>

(on page 1-68)

-write-files

Enables code generator workaround for specific hardware defects

Enables compiler I/O redirection

(on page 1-69)

1-20 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Table 1-5. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-write-opts

(on page 1-69)

-xref filename

Passes the user options (but not input filenames) via a temporary file

Outputs cross-reference information to the specified file.

(on page 1-69)

Table 1-6. C++ Mode Compiler Switches

Switch Name Description

-anach

(on page 1-71)

-check-init-order

(on page 1-72)

-eh

(on page 1-73)

-ignore-std

(on page 1-75)

-no-anach

(on page 1-75)

-no-demangle

(on page 1-75)

-no-eh

(on page 1-75)

Supports some language features (anachronisms) that are prohibited by the C++ standard but still in common use

Adds run-time checking to the generated code highlighting potential uninitialized external objects.

Enables exception handling

Disables namespace std within the C++ Standard header files.

Disallows the use of anachronisms that are prohibited by the C++ standard

Prevents filtering of any linker errors through the demangler

Disables exception-handling

-no-implicit-inclusion

(on page 1-75)

-no-rtti

Prevents implicit inclusion of source files as a method of finding definitions of template entities to be instantiated

Disables run-time type information

(on page 1-75)

-rtti

Enables run-time type information

(on page 1-76)

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-21 for TigerSHARC Processors

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,

no-extra-keywords, and -pedantic. (See Table 1-5 on page 1-12.)

-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-21.)

Exceptions also require modifications to the Linker Description Files; 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 as well: .frt, .edt, .cht, and .gdt. See the default LDFs included with the release for example modifications.

1-22 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

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 embedded

machine adspts

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-23 for TigerSHARC Processors

Compiler Command-Line Interface

Table 1-7. Predefined Assertions (Cont’d)

Assertion Value

cpu adspts101 for ADSP-TS101 processor

adspts201 for ADSP-TS201 processor adspts202 for ADSP-TS202 processor adspts203 for ADSP-TS203 processor

compiler ccts

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

The parentheses in the assertion need quotes when using the -A

switch, to prevent misinterpretation. No quotes are needed for a

#assert directive in a source file.

1-24 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-add-debug-libpaths

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.

-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. This switch will override that behaviour. Note that using this switch may result in different output as the multiply-accumulate instruction will saturate to 40 bits for intermediate results and then saturate to 32 bits on extraction from the accumulator.

-alttok

The alternative operator keywords and digraph sequences in source files. This is the default mode. The switch “-no-alttok” on page 1-43 can be used to disallow such support.

Invoke this switch with the Use Debug System Libraries radio button located in the VisualDSP++ Project Options dialog box, Link page, Processor category.

-alttok (alternative tokens) switch directs the compiler to allow

The ANSI C trigraphs sequences are always expanded (even with the

-no-alttok option), and only digraph sequences are expanded in C source

files.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-25 for TigerSHARC Processors

Compiler Command-Line Interface

The following operator keywords are enabled by default.

Table 1-8. Keyword Equivalents

Keyword Equivalent

and &&

and_eq &=

bitand &

bitor |

compl ~

not !

not_eq !=

or ||

or_eq |=

xor ^

xor_eq ^=

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 equivalent to applying module that have the

#pragma always_inline to all functions in the

inline qualifier See also “-never-inline” on

page 1-43.

Invoke this switch with the Always radio button located in the

Inlining area of the VisualDSP++ Project Options dialog box, Compile page, General category.

1-26 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

inline qualifier. It is

Compiler

-annotate-loop-instr

The

-annotate-loop-instr switch directs the compiler to provide addi-

tional annotation information for the prolog, kernel and epilog of a loop. See “Assembly Optimizer Annotations” on page 2-72 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-293 for more information about attributes, and what automatic attributes the compiler emits. See also the -no-auto-attrs switch (on page 1-44) 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” on page 1-44.

-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++ 4.5 C/C++ Compiler and Library Manual 1-27 for TigerSHARC Processors

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.

-char-size-{8|32}

The (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.

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.

-char-size-{8|32} switch specifies that chars are 8-bit data items

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++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-const-read-write

The

-const-read-write switch directs the compiler to specify that con-

stants 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.

-const-strings

The -const-strings (const-qualify strings) swich 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-45).

-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 ‘

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, Source 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, Source Language Settings category.

1’. If definition is required to be a character string

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-29 for TigerSHARC Processors

Compiler Command-Line Interface

constant, it must be surrounded by escaped double quotes. Note that the compiler processes fine macro) switches.

-D switches on the command line before any -U (unde-

-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 infor-

mation 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}

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

-default-branch-{np|p} switch instructs the assembler and linker to

The set the branch behavior to be predictable or non-predictable. The default is the predicted condition.

1-30 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-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).

located in the VisualDSP++ Project Options dialog box, Compile page, Processor (1) category.

-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

Invoke this switch with the Allow mixing of sizes check box

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 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.

double

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

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-31 for TigerSHARC Processors

Compiler Command-Line Interface

mode is the default and is recommended for most programs. Calculations that need higher precision can be done with the is always 64 bits.

With -double-size-64, a double is stored in 64-bit IEEE double precision format and is operated on using slow floating-point emulation software. Standard math functions, such as sin, also operate on 64-bit values and are similarly slow. This mode is recommended only for porting code that requires that double have more than 32 bits of precision.

The -double-size-32 switch defines the __DOUBLES_ARE_FLOATS__ preprocessor macro, while the -double-size-64 switch undefines the

__DOUBLES_ARE_FLOATS__ preprocessor macro.

long double type, which

-dry

The -dry (verbose dry-run) switch directs the compiler to display ccts actions, but not to perform them.

-dryrun

The actions, but not to perform them.

Invoke this switch with the Double size radio buttons located in the VisualDSP++ Project Options dialog box, Compile tab, Compile category, Processor (1) subcategory.

-dryrun (terse dry-run) switch directs the compiler to display ccts

1-32 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-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.

-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.

-EE

The does not halt compilation after preprocessing.

Invoke it with the Stop after: Preprocessor check box located in the VisualDSP++ Project Options dialog box, Compile tab, General category.

Invoke this switch with the Generate preprocessed file check box located in the VisualDSP++ Project Options dialog box, Compile page, General category.

-EE (run after preprocessing) switch is similar to the -E switch, but it

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-33 for TigerSHARC Processors

Compiler Command-Line Interface

-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.

-extra-keywords

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.

The -no-extra-keywords switch (on page 1-46) can be used to disallow support for the additional keywords. Table 1-15 on page 1-89 provides a list and a brief description of keyword extensions.

-file-attr name[=value]

The specified attribute name/value pair to all the files it compiles. To add multiple attributes, use the switch multiple times. If " the default value of "1" will be used. See “File Attributes” on page 1-293 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-44).

Invoke this switch with the Enumerated types are always int check box located in the VisualDSP++ Project Options dialog box, Compile page, Source Language Settings category.

-file-attr (file attribute) switch directs the compiler to add the

=value" is omitted,

1-34 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

Invoke this switch with the Additional attributes text field located in the VisualDSP++ Project Options dialog box, Compile page, General category.

for TigerSHARC Processors

-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, such as:

Table 1-9. Switches Passed to other ADI 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

Compiler

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 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-142.

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, Source Language Settings

category.

-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.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-35 for TigerSHARC Processors

Compiler Command-Line Interface

-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 that inlining the code. 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.

-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.

When the -g switch is used in conjunction with the -O (enable optimization) 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.

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.

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).

1-36 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-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.

When used on its own, the switch also enables the -g option.

-H

The -H (list headers) switch directs the compiler to output only a list of the files included by the preprocessor via the #include directive, without compiling.

Invoke this switch by selecting the Generate debug information check box in the VisualDSP++ Project Options dialog box, Compile tab, General category.

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.

-HH

HH (list headers and compile) switch directs the compiler to output to

The the standard out a list of the files included by the preprocessor via the

#include directive. After preprocessing, compilation proceeds normally.

-h[elp]

-help (command-line help) switch directs the compiler to output a

The list of command-line switches with a brief syntax description.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-37 for TigerSHARC Processors

Compiler Command-Line Interface

-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.

-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-38 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

Invoke this switch with the Additional include directories text field located in the VisualDSP++ Project Options dialog box, Compile page, Preprocessor category.

1. The directory containing the current input file (the primary source file or the file containing the #include)

for TigerSHARC Processors

Compiler

2. Any directories specified with the listed on the command line

3. Any directories on the standard list:

<VDSP++ install dir>/.../include

-implicit-pointers

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,

int *foo(int *a) {

} int main(void) {

}

If a file is included using the <...> form, this file is only searched for by using directories defined in items 2 and 3 above.

return a;

char *p = 0, *r; r = foo(p); /* Bad: will normally give an error. */ return 0;

-I switch in the order they are

Both the argument to foo and the assignment to r will be faulted by the compiler. Using

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-39 for TigerSHARC Processors

Invoke this switch with the Allow incompatible pointer types check box located in the VisualDSP++ Project Options dialog box, Compile page, Source Language Settings category.

-implicit-pointers converts these errors into warnings.

Compiler Command-Line Interface

-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-84.

-L directory [{,|;} directory...]

The -L (library search directory) switch directs the linker to append the directory to the search path for library files.

-l library

The 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

Invoke this switch by selecting the Interprocedural Analysis check box in the VisualDSP++ Project Options dialog box, Compile tab, General category.

-l (link library) switch directs the linker to search the library for

1-40 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

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.

-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.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-41 for TigerSHARC Processors

Compiler Command-Line Interface

-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 -M or -MM switch..

-MQ

The -MQ switch directs the compiler not to compile the source file but to output a rule. In addition, the -MQ switch does not produce any notification when input files are missing.

-map filename

The -map (generate a memory map) switch directs the linker 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

is test.xml. The .xml extension is added where necessary.

-mem

-mem (enable memory initialization) switch directs the compiler to

The invoke the memory initializer after linking the executable file. The MemInit utility can be controlled through the

-flags-mem switch

(on page 1-35).

1-42 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-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.

-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.

-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, Source Language Settings category.

Invoke this switch with the Never check box located in the Inlin- ing area of the VisualDSP++ Project Options dialog box, Compile page, General category.

-alttok switch (on page 1-25).

-no-annotate

The -no-annotate (disable assembly annotations) switch directs the compiler not to annotate assembly files. The default behavior is that whenever optimizations are enabled, all assembly files generated by the compiler are

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-43 for TigerSHARC Processors

Compiler Command-Line Interface

annotated with information on the performance of the generated assembly. See “Assembly Optimizer Annotations” on page 2-72 for more details on this feature.

-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-293 for more information about attributes, and what automatic

attributes the compiler emits. See also the -auto-attrs switch (on page 1-27) and the -file-attr switch (on page 1-34).

Invoke this switch by clearing the Generate assembly code annotations check box located in the VisualDSP++ Project Options

dialog box, Compile page, General category.

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

-no-bss switch causes the compiler to keep zero-initialized and

The 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).

1-44 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

-bss

Compiler

-no-builtin

The

-no-builtin (no built-in functions) switch directs the compiler to use

generic implementations in preference to intrinsic functions for certain language extensions. For a list of the extensions that use single machine instructions when -no-builtin is not used, see “Math Intrinsics” on

page 1-143. This switch also predefines the __NO_BUILTIN preprocessor

macro.

-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.

-no-const-strings

The -no-const-strings switch directs the compiler not to make string literals const qualified.

-no-defs

Invoke this switch by selecting the Disable builtin functions check box in the VisualDSP++ Project Options dialog box, Compile tab, Source 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, Source Language Settings

category.

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.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-45 for TigerSHARC Processors

Compiler Command-Line Interface

-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

“-no-extra-keywords” switch (on page 1-46) can be used to explicitly

request support for the additional keywords.

-no-fp-associative

The -no-fp-associative switch directs the compiler NOT to treat floating-point multiplication and addition as an associative.

-no-fp-minmax

The -no-fp-minmax (No floating-point MIN or MAX instructions) switch prevents the compiler from generating floating-point MIN or MAX instructions, when it inlines a floating-point comparison. The instructions on TigerSHARC will return 0xFFFFFFFF if either input value is a NaN. This can result in behaviour not anticipated or intended by the original user code.

Invoke this switch with the Disable Analog Devices extension key- words check box located in the VisualDSP++ Project Options dialog box, Compile page, Source 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, Source Language Settings

category.

MAX and MIN

1-46 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

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.

for TigerSHARC Processors

Compiler

-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.

-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.

-no-std-ass

The piler from defining the standard assertions. See the (on page 1-23) for the list of standard assertions.

-no-std-def

The piler from defining any default preprocessor macro definitions.

Invoke this switch by clearing the Allow multi-line character strings check box located in the VisualDSP++ Project Options dia- log box, Compile page, Source Language Settings category.

-no-std-ass (disable standard assertions) switch prevents the com-

-A switch

-no-std-def (disable standard macro definitions) prevents the com-

This switch also disables the Analog Devices keyword extensions which have no leading underscores, such as

pm and dm.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-47 for TigerSHARC Processors

Compiler Command-Line Interface

-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.

-no-std-lib

The -no-std-lib (disable standard library search) switch directs the linker 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 -threads (enable thread-safe build) switch is not used.

-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

Invoke this switch by selecting the Ignore standard include paths check box in the VisualDSP++ Project Options dialog box, Compile tab, Preprocessor category.

ccts compiler.

Invoke this switch by selecting the Enable optimization check box in the VisualDSP++ Project Options dialog box, Compile tab, General category.

1-48 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Compiler

-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.

-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-50). 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).

-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.

Invoke this switch by selecting the Enable optimization check box in the VisualDSP++ Project Options dialog box, Compile tab, General category.

Invoke this switch with the Automatic check box located in the

Inlining area of the VisualDSP++ Project Options dialog box, Compile page, General category.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-49 for TigerSHARC Processors

Compiler Command-Line Interface

-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

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 num variable should be an integer between 0 (purely size) and 100 (purely speed).

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 the decision is based upon

-Ov100 all blocks are optimized for speed. At any point in between, num and how many times the block is expected

to be executed – the “execution count” of the block. Figure 1-1 demonstrates this relationship.

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 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

1-50 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

for TigerSHARC Processors

Infinity

Execution

count

Compiler

Optimize for speed

Limit line

Optimize for space

0100

-Ovnum

Figure 1-1. -Ov Switch Optimization Curve

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

-Ov switch affects the point at which a given exe-

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.

VisualDSP++ 4.5 C/C++ Compiler and Library Manual 1-51 for TigerSHARC Processors

Compiler Command-Line Interface

The

-Ov switch is most effective when used in conjuction with pro-

file-guided optimization, where accurate execution counts are available. Without profile-guided optimization, the compiler makes estimates of the relative execution counts using heuristics.

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.

-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 degradation. For information on disabling the propagation of register information only for specific functions, see “#pragma overlay” on

page 1-202.

Invoke this switch with the Optimize for code size/speed slider located in the VisualDSP++ Project Options dialog box, Compile page, General category.

-P

The -P (omit line numbers) switch directs the compiler to stop after the C preprocessor runs (without compiling) and to omit the directives (with line number information) in the output from the preprocessor. The

1-52 VisualDSP++ 4.5 C/C++ Compiler and Library Manual

-C switch may be used in combination with the -P switch.

for TigerSHARC Processors

#line preprocessor

ANALOG DEVICES W4.5 Library Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

CONTENTS

PREFACE

Purpose of This Manual

Intended Audience

Manual Contents Description

What’s New in This Manual

Technical or Customer Support

Supported Processors

Product Information

MyAnalog.com

Processor Product Information

Related Documents

Online Technical Documentation

Accessing Documentation From VisualDSP++

Accessing Documentation From Windows

Accessing Documentation From the Web

Printed Manuals

VisualDSP++ Documentation Set

Hardware Tools Manuals

Processor Manuals

Data Sheets

Notation Conventions

1 COMPILER

C/C++ Compiler Overview

Compiler Command-Line Interface

Running the Compiler

Table 1-1. TigerSHARC Command Line Syntax

Table 1-2. File Extensions

Compiler Command-Line Switches

C/C++ Compiler Switch Summaries

Table 1-4. C or C++ Mode Selection Switches

Table 1-6. C++ Mode Compiler Switches

C/C++ Mode Selection Switch Descriptions

-c89

-c++

C/C++ Compiler Common Switch Descriptions

sourcefile

-@ filename

-A name [(<tokens>)]

-add-debug-libpaths

-align-branch-lines

-allow-macs-to-extend-saturation

-alttok

Table 1-8. Keyword Equivalents

-always-inline

-annotate-loop-instr

-auto-attrs

-bss

-build-lib

-char-size-any

-char-size-{8|32}

-const-read-write

-const-strings

-Dmacro[=definition]

-debug-types

-default-branch-{np|p}

-double-size-any

-double-size-{32 | 64}

-dry

-dryrun

-enum-is-int

-extra-keywords

-file-attr name[=value]

-flags-{asm|compiler|lib|link|mem} switch [,switch2 [,...]]

Table 1-9. Switches Passed to other ADI Tools

-force-circbuf

-fp-associative

-fp-div-lib

-full-version

-glite

-h[elp]

-I directory [{,|;} directory...]

-implicit-pointers

-include filename

-ipa

-L directory [{,|;} directory...]