ANALOG DEVICES W4.0 Library Manual

W4.0

C/C++ Compiler and Library Manual

for SHARC

Revision 5.0, January 2005

®

Processors

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

Part Number

82-001963-01

a

Copyright Information

©2005 Analog Devices, Inc., ALL RIGHTS RESERVED. This document
may not be reproduced in any form without prior, express written consent
from Analog Devices, Inc.

Printed in the USA.

Disclaimer

Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by impli­cation or otherwise under the patent rights of Analog Devices, Inc.

Trademark and Service Mark Notice

The Analog Devices logo, the CROSSCORE logo, VisualDSP++,
SHARC, 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 ............................................................... xxxi

Intended Audience ....................................................................... xxxi

Manual Contents ........................................................................ xxxii

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

Technical or Customer Support .................................................. xxxiii

Supported Processors .................................................................. xxxiv

Product Information .................................................................. xxxiv

MyAnalog.com ..................................................................... xxxiv

Processor Product Information ............................................... xxxv

Related Documents .............................................................. xxxvi

Online Technical Documentation ........................................ xxxvii

Accessing Documentation From VisualDSP++ ................. xxxvii

Accessing Documentation From Windows ...................... xxxviii

Accessing Documentation From the Web ........................ xxxviii

Printed Manuals ................................................................... xxxix

VisualDSP++ Documentation Set ..................................... xxxix

Hardware Tools Manuals .................................................. xxxix

Processor Manuals ............................................................ xxxix

VisualDSP++ 4.0 C/C++ Compiler and Library Manual iii
for SHARC Processors

CONTENTS

Data Sheets ...................................................................... xxxix

Notation Conventions ..................................................................... xl

COMPILER

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

Compiler Command-Line Interface .............................................. 1-4

Running the Compiler ............................................................ 1-5

Specifying Compiler Options in VisualDSP++ ......................... 1-9

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

-aligned-stack ............................................................... 1-24

-alttok .......................................................................... 1-24

-annotate-loop-instr ...................................................... 1-25

-bss .............................................................................. 1-25

-build-lib ...................................................................... 1-25

-C ................................................................................ 1-25

-c ................................................................................. 1-26

-compatible-pm-dm ...................................................... 1-26

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

for SHARC Processors

CONTENTS

-const-read-write ........................................................... 1-26

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

-debug-types ................................................................. 1-26

-default-linkage[-asm | -C | -C++] .................................. 1-27

-double-size[-32|-64] ..................................................... 1-27

-double-size-any ............................................................ 1-28

-dry .............................................................................. 1-28

-dryrun ......................................................................... 1-28

-E ................................................................................. 1-29

-ED .............................................................................. 1-29

-EE ............................................................................... 1-29

-extra-keywords ............................................................. 1-29

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

-float-to-int ................................................................... 1-30

-force-circbuf ................................................................ 1-30

-fp-associative ............................................................... 1-30

-full-version .................................................................. 1-30

-g .................................................................................. 1-31

-H ................................................................................ 1-31

-HH ............................................................................. 1-31

-h[elp] .......................................................................... 1-32

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

-I- ................................................................................. 1-32

-i .................................................................................. 1-33

VisualDSP++ 4.0 C/C++ Compiler and Library Manual v
for SHARC Processors

CONTENTS

-include filename .......................................................... 1-33

-ipa .............................................................................. 1-33

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

-l library ....................................................................... 1-34

-M ............................................................................... 1-35

-MD ............................................................................ 1-35

-MM ............................................................................ 1-35

-Mo _filename_ ............................................................ 1-35

-Mt filename ................................................................ 1-35

-MQ ............................................................................ 1-36

-map filename .............................................................. 1-36

-mem ........................................................................... 1-36

-multiline ..................................................................... 1-36

-no-aligned-stack .......................................................... 1-36

-no-alttok ..................................................................... 1-36

-no-annotate ................................................................. 1-37

-no-annotate-loop-instr ................................................. 1-37

-no-bss ......................................................................... 1-37

-no-builtin ................................................................... 1-37

-no-circbuf ................................................................... 1-38

-no-db .......................................................................... 1-38

-no-defs ........................................................................ 1-38

-no-extra-keywords ....................................................... 1-38

-no-fp-associative .......................................................... 1-38

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

for SHARC Processors

CONTENTS

-no-mem ....................................................................... 1-39

-no-multiline ................................................................ 1-39

-no-saturation ............................................................... 1-39

-no-simd ....................................................................... 1-39

-no-std-ass .................................................................... 1-39

-no-std-def .................................................................... 1-40

-no-std-inc .................................................................... 1-40

-no-std-lib .................................................................... 1-40

-no-threads ................................................................... 1-40

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

-Oa ............................................................................... 1-41

-Og ............................................................................... 1-41

-Os ............................................................................... 1-41

-Ov num ....................................................................... 1-41

-o filename .................................................................... 1-42

-P ................................................................................. 1-42

-PP ............................................................................... 1-42

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

-path-install directory .................................................... 1-42

-path-output directory ................................................... 1-43

-path-temp directory ..................................................... 1-43

-pch .............................................................................. 1-43

-pchdir directory ........................................................... 1-43

-pedantic ...................................................................... 1-43

VisualDSP++ 4.0 C/C++ Compiler and Library Manual vii
for SHARC Processors

CONTENTS

-pedantic-errors ............................................................ 1-44

-pguide ......................................................................... 1-44

-pplist filename ............................................................. 1-44

-proc processor ............................................................. 1-45

-progress-rep-func ......................................................... 1-45

-progress-rep-gen-opt .................................................... 1-45

-progress-rep-mc-opt ..................................................... 1-46

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

-R- ............................................................................... 1-47

-reserve register[, register …] ......................................... 1-47

-restrict-hardware-loops <maximum> ............................ 1-47

-S ................................................................................. 1-47

-s .................................................................................. 1-48

-save-temps ................................................................... 1-48

-section <id>=<section_name>[,<id>=section_name>] ... 1-48

-show ........................................................................... 1-48

-si-revision version ........................................................ 1-49

-signed-bitfield ............................................................. 1-50

-signed-char .................................................................. 1-50

-structs-do-not-overlap ................................................. 1-51

-switch-pm ................................................................... 1-51

-syntax-only .................................................................. 1-51

-sysdefs ......................................................................... 1-52

-T filename .................................................................. 1-52

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

for SHARC Processors

CONTENTS

-threads ........................................................................ 1-52

-time ............................................................................ 1-53

-Umacro ....................................................................... 1-53

-unsigned-bitfield .......................................................... 1-53

-unsigned-char .............................................................. 1-54

-v .................................................................................. 1-54

-verbose ........................................................................ 1-54

-version ......................................................................... 1-54

-W[error|remark|suppress|warn] number[,number ...] ..... 1-55

-Wdriver-limit number .................................................. 1-55

-Werror-limit number ................................................... 1-55

-Wremarks .................................................................... 1-55

-Wterse ......................................................................... 1-55

-w ................................................................................. 1-56

-warn-protos ................................................................. 1-56

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

-write-files .................................................................... 1-56

-write-opts .................................................................... 1-57

-xref <filename> ............................................................ 1-57

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

-anach ........................................................................... 1-58

-eh ................................................................................ 1-59

-no-anach ..................................................................... 1-60

-no-demangle ................................................................ 1-60

VisualDSP++ 4.0 C/C++ Compiler and Library Manual ix
for SHARC Processors

CONTENTS

-no-eh .......................................................................... 1-60

-no-implicit-inclusion ................................................... 1-60

-no-rtti ......................................................................... 1-60

-rtti .............................................................................. 1-61

Data Type and Data Type Sizes .............................................. 1-61

Integer Data Types ........................................................... 1-62

Floating-Point Data Types ................................................ 1-62

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

Optimization Control ........................................................... 1-64

Interprocedural Analysis ................................................... 1-67

Interaction with Libraries .............................................. 1-68

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

Inline Function Support Keyword (inline) ............................. 1-74

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

Assembly Construct Template ........................................... 1-77

asm() Construct Syntax Rules ....................................... 1-78

asm() Construct Template Example ............................... 1-79

Assembly Construct Operand Description ......................... 1-80

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

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

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

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

Guildelines on the Use of asm() Statements ....................... 1-89

Dual Memory Support Keywords (pm dm) ............................ 1-90

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

for SHARC Processors

CONTENTS

Memory Keywords and Assignments/Type Conversions ...... 1-92

Memory Keywords and Function Declarations/Pointers ..... 1-93

Memory Keywords and Function Arguments ..................... 1-93

Memory Keywords and Macros ......................................... 1-94

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

Placement of Compiler-Generated Data ................................. 1-95

Boolean Type Support Keywords (bool, true, false) ................. 1-96

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

Variable-Length Array Support .............................................. 1-97

Non-Constant Initializer Support .......................................... 1-99

Indexed Initializer Support .................................................... 1-99

Aggregate Constructor Expression Support ........................... 1-101

Preprocessor Generated Warnings ........................................ 1-102

C++ Style Comments ........................................................... 1-102

Compiler Built-In Functions ................................................ 1-102

Access to System Registers ............................................... 1-103

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

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

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

Compiler Performance Built-in Functions ........................ 1-108

Pragmas .............................................................................. 1-110

Data Alignment Pragmas ................................................. 1-111

#pragma align num ..................................................... 1-112

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

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xi
for SHARC Processors

CONTENTS

Interrupt Handler Pragma ............................................... 1-115

Loop Optimization Pragmas ........................................... 1-116

General Optimization Pragmas ....................................... 1-119

Function Side-Effect Pragmas ......................................... 1-120

#pragma pack (alignopt) ............................................. 1-114

#pragma pad (alignopt) ............................................... 1-114

#pragma SIMD_for .................................................... 1-116

#pragma all_aligned .................................................... 1-117

#pragma no_vectorization ........................................... 1-117

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

#pragma no_alias ........................................................ 1-118

#pragma vector_for ..................................................... 1-118

#pragma alloc ............................................................. 1-121

#pragma const ............................................................ 1-121

#pragma noreturn ....................................................... 1-122

#pragma pure ............................................................. 1-122

#pragma regs_clobbered string .................................... 1-123

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

Template Instantiation Pragmas ...................................... 1-127

#pragma instantiate instance ....................................... 1-128

#pragma do_not_instantiate instance .......................... 1-128

#pragma can_instantiate instance ................................ 1-129

Header File Control Pragmas .......................................... 1-129

#pragma hdrstop ........................................................ 1-129

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

for SHARC Processors

CONTENTS

#pragma no_implicit_inclusion ................................... 1-130

#pragma no_pch ......................................................... 1-131

#pragma once ............................................................. 1-131

#pragma system_header ............................................... 1-132

Linking Control Pragmas ................................................ 1-132

#pragma linkage_name identifier ................................. 1-132

#pragma retain_name .................................................. 1-132

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

#pragma weak_entry .................................................. 1-135

Diagnostic Control Pragmas ............................................ 1-135

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

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

Saving or Restoring the Current Behavior of All Diagnostics ..

1-137

Code Generation Pragmas ............................................... 1-138

GCC Compatibility Extensions ........................................... 1-138

Statement Expressions ..................................................... 1-138

Type Reference Support Keyword (Typeof) ...................... 1-140

GCC Generalized Lvalues ............................................... 1-141

Conditional Expressions with Missing Operands .............. 1-141

Hexadecimal Floating-Point Numbers ............................. 1-142

Zero-Length Arrays ......................................................... 1-142

Variable Argument Macros .............................................. 1-143

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

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

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xiii
for SHARC Processors

CONTENTS

Cast to Union ................................................................. 1-144

Ranges in Case Labels ..................................................... 1-144

Declarations Mixed With Code ....................................... 1-144

Escape Character Constant ............................................. 1-145

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

Keyword for Specifying Names in Generated Assembler (asm) 1-145

Function, Variable and Type Attribute Keyword (__attribute__)

1-146

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

Format of Fractional Literals ........................................... 1-147

Conversions Involving Fractional Values .......................... 1-147

Fractional Arithmetic Operations .................................... 1-148

Mixed Mode Operations ................................................. 1-148

Saturated Arithmetic ........................................................... 1-149

SIMD Support .................................................................... 1-150

Using SIMD Mode with Multichannel Data .................... 1-151

Using SIMD Mode with Single-Channel Data ................. 1-152

Restrictions to Using SIMD ............................................ 1-154

SIMD_for Pragma Syntax ............................................... 1-155

Compiler Constraints on Using SIMD C/C++ ................ 1-157

Impact of Anomaly #40 on SIMD ................................... 1-158

Performance When Using SIMD C/C++ ......................... 1-159

Examples Using SIMD C ................................................ 1-160

Using SIMD C (Problem Cases—Data Increments) ..... 1-160

Using SIMD C (Problem Cases—Data Alignment) ...... 1-162

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

for SHARC Processors

CONTENTS

Preprocessor Features ................................................................ 1-165

Predefined Preprocessor Macros ........................................... 1-166

__2106x__ ..................................................................... 1-166

__2116x__ ..................................................................... 1-166

__2126x__ ..................................................................... 1-166

__2136x__ ..................................................................... 1-166

__ADSP21000__ ............................................................ 1-166

__ADSP21020__ ............................................................ 1-167

__ADSP21060__ ............................................................ 1-167

__ADSP21061__ ............................................................ 1-167

__ADSP21062__ ............................................................ 1-167

__ADSP21065L__ .......................................................... 1-167

__ADSP21160__ ............................................................ 1-167

__ADSP21161__ ............................................................ 1-167

__ADSP21261__ ............................................................ 1-168

__ADSP21262__ ............................................................ 1-168

__ADSP21266__ ............................................................ 1-168

__ADSP21267__ ............................................................ 1-168

__ADSP21363__ ............................................................ 1-168

__ADSP21364__ ............................................................ 1-168

__ADSP21365__ ............................................................ 1-168

__ADSP21366__ ............................................................ 1-169

__ADSP21367__ ............................................................ 1-169

__ADSP21368__ ............................................................ 1-169

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xv
for SHARC Processors

CONTENTS

__ADSP21369__ ........................................................... 1-169

__ANALOG_EXTENSIONS__ ..................................... 1-169

__cplusplus .................................................................... 1-169

__DATE__ .................................................................... 1-169

__DOUBLES_ARE_FLOATS__ .................................... 1-170

__ECC__ ....................................................................... 1-170

__EDG__ ...................................................................... 1-170

__EDG_VERSION__ .................................................... 1-170

__FILE__ ....................................................................... 1-170

__LINE__ ...................................................................... 1-170

_NO_LONGLONG ...................................................... 1-170

__NO_BUILTIN ........................................................... 1-171

__SIGNED_CHARS__ .................................................. 1-171

__SIMDSHARC__ ........................................................ 1-171

__STDC__ .................................................................... 1-171

__STDC_VERSION__ .................................................. 1-171

__TIME__ ..................................................................... 1-171

__VERSION__ .............................................................. 1-171

__VERSIONNUM__ ..................................................... 1-172

__WORKAROUNDS_ENABLED ................................. 1-172

Writing Macros ................................................................... 1-172

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

C/C++ Run-Time Environment ........................................... 1-175

Memory Usage ............................................................... 1-177

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

for SHARC Processors

CONTENTS

Measuring the Performance of C Compiler ...................... 1-183

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

Using Multiple Heaps .......................................................... 1-185

Declaring a Heap ............................................................ 1-186

Heap Identifiers .............................................................. 1-189

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

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

Example C Programs ....................................................... 1-191

Compiler Registers .............................................................. 1-192

Miscellaneous Information About Registers ..................... 1-193

User Registers ................................................................. 1-193

Call Preserved Registers ................................................... 1-194

Scratch Registers ............................................................. 1-195

Stack Registers ................................................................ 1-196

Alternate Registers .......................................................... 1-196

Managing the Stack ......................................................... 1-197

Transferring Function Arguments and Return Value ......... 1-202

Using Data Storage Formats ............................................ 1-205

Using the Run-Time Header ........................................... 1-208

C/C++ and Assembly Interface .................................................. 1-209

Calling Assembly Subroutines from C/C++ Programs ........... 1-209

Calling C/C++ Functions from Assembly Programs .............. 1-211

Using Mixed C/C++ and Assembly Support Macros ......... 1-214

entry ........................................................................... 1-214

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xvii
for SHARC Processors

CONTENTS

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

Implementing C++ Member Functions in Assembly Language 1-220

exit ............................................................................. 1-214

leaf_entry ................................................................... 1-215

leaf_exit ..................................................................... 1-215

ccall(x) ....................................................................... 1-215

reads(x) ...................................................................... 1-215

puts=x ........................................................................ 1-215

gets(x) ........................................................................ 1-215

alter(x) ....................................................................... 1-216

save_reg ...................................................................... 1-216

restore_reg .................................................................. 1-216

Writing C/C++ Callable SIMD Subroutines .................... 1-222

C++ Programming Examples ............................................... 1-223

Using Fract Support ........................................................ 1-223

Using Complex Support ................................................. 1-224

Mixed C/C++/Assembly Programming Examples ................. 1-226

Using Inline Assembly (Add) .......................................... 1-227

Using Macros to Manage the Stack .................................. 1-228

Using Scratch Registers (Dot Product) ............................ 1-229

Using Void Functions (Delay) ......................................... 1-231

Using the Stack for Arguments and Return (Add 5) ......... 1-232

Using Registers for Arguments and Return (Add 2) ......... 1-233

Using Non-Leaf Routines That Make Calls (RMS) .......... 1-234

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

for SHARC Processors

CONTENTS

Using Call Preserved Registers (Pass Array) ...................... 1-236

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

Template Instantiation ......................................................... 1-238

Identifying Uninstantiated Templates ................................... 1-239

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 the Statistical Profiler ............................................... 2-5

Using Profile-Guided Optimization ..................................... 2-6

Using Interprocedural Optimization .................................... 2-7

Data Types .............................................................................. 2-8

Avoiding Emulated Arithmetic ............................................ 2-9

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

Initialize Constants Statically ............................................. 2-10

Dual Word-Aligning Your Data ......................................... 2-11

Using __builtin_aligned .................................................... 2-12

Avoiding Aliases ................................................................ 2-13

Indexed Arrays Versus Pointers ............................................... 2-15

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

Function Inlining .................................................................. 2-16

Using Inline asm Statements .................................................. 2-18

Memory Usage ...................................................................... 2-19

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xix
for SHARC Processors

CONTENTS

Improving Conditional Code ...................................................... 2-21

Loop Guidelines ......................................................................... 2-22

Keeping Loops Short ............................................................. 2-22

Avoiding Unrolling Loops ..................................................... 2-22

Avoiding Loop-Carried Dependencies .................................... 2-23

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

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

Inner Loops vs. Outer Loops ................................................ 2-26

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

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

Avoiding Non-Unit Strides ................................................... 2-27

Loop Control ........................................................................ 2-28

Using the Restrict Qualifier ................................................... 2-29

Using the Const Qualifier ..................................................... 2-30

Avoiding Long Latencies ....................................................... 2-31

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

System Support Built-In Functions ........................................ 2-32

Using Circular Buffers ........................................................... 2-33

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

Using Pragmas for Optimization ................................................. 2-38

Function Pragmas ................................................................. 2-38

#pragma alloc ................................................................... 2-38

#pragma const .................................................................. 2-39

#pragma pure ................................................................... 2-39

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

for SHARC Processors

CONTENTS

#pragma result_alignment ................................................. 2-40

#pragma regs_clobbered .................................................... 2-40

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

Loop Optimization Pragmas .................................................. 2-43

#pragma loop_count ......................................................... 2-43

#pragma no_vectorization ................................................. 2-43

#pragma vector_for ........................................................... 2-44

#pragma SIMD_for .......................................................... 2-45

#pragma all_aligned .......................................................... 2-45

#pragma no_alias .............................................................. 2-46

Useful Optimization Switches ...................................................... 2-47

Example: How the Optimizer Works ........................................... 2-48

Assembly Optimizer Annotations ................................................ 2-51

Procedure Statistics ................................................................ 2-52

Loop Identification ................................................................ 2-54

Loop Identification Annotations ........................................ 2-55

File Position ...................................................................... 2-58

Vectorization ......................................................................... 2-60

Loop Flattening ................................................................ 2-61

Vectorization Annotations ................................................. 2-62

Modulo Scheduling ............................................................... 2-65

C/C++ RUN-TIME LIBRARY

C and C++ Run-Time Libraries Guide ........................................... 3-3

Calling Library Functions ........................................................ 3-3

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxi
for SHARC Processors

CONTENTS

Linking Library Functions ....................................................... 3-4

Working with Library Header Files ........................................ 3-12

assert.h ............................................................................. 3-13

ctype.h ............................................................................. 3-13

cycle_count.h ................................................................... 3-13

cycles.h ............................................................................ 3-13

device.h ............................................................................ 3-14

device_int.h ...................................................................... 3-14

errno.h ............................................................................. 3-14

float.h .............................................................................. 3-15

iso646.h ........................................................................... 3-15

limits.h ............................................................................ 3-16

locale.h ............................................................................ 3-16

math.h ............................................................................. 3-16

setjmp.h ........................................................................... 3-18

signal.h ............................................................................ 3-18

Interrupt Dispatchers .................................................... 3-18

Interrupts and Circular Buffering .................................. 3-21

Avoiding Self-Modifying Code ...................................... 3-21

Interrupt Nesting Restrictions on ADSP-2116x/2126x/2136x

Processors .................................................................. 3-22

Restriction on Use of Super-Fast Dispatcher on ADSP-2106x

Processors .................................................................. 3-22

stdarg.h ............................................................................ 3-23

stddef.h ............................................................................ 3-23

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

for SHARC Processors

CONTENTS

stdio.h .............................................................................. 3-24

stdlib.h ............................................................................. 3-26

string.h ............................................................................. 3-27

time.h ............................................................................... 3-27

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

Using Compiler Built-In C Library Functions ........................ 3-30

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

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxiii
for SHARC Processors

CONTENTS

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

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

algorithm ..................................................................... 3-37

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

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

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

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

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

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

map .............................................................................. 3-38

memory ........................................................................ 3-38

numeric ........................................................................ 3-38

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

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

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

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

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

fstream.h ...................................................................... 3-39

iomanip.h ..................................................................... 3-39

iostream.h .................................................................... 3-39

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

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

Measuring Cycle Counts ....................................................... 3-40

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

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

for SHARC Processors

CONTENTS

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

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

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

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

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

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

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

C Run-Time Library Reference .................................................... 3-64

abort .......................................................................................... 3-65

abs .............................................................................................. 3-66

acos ............................................................................................ 3-67

asctime ....................................................................................... 3-68

asin ............................................................................................. 3-70

atan ............................................................................................ 3-71

atan2 .......................................................................................... 3-72

atexit .......................................................................................... 3-73

atof ............................................................................................. 3-74

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxv
for SHARC Processors

CONTENTS

atoi ............................................................................................ 3-77

atol ............................................................................................ 3-78

atold .......................................................................................... 3-79

avg ............................................................................................. 3-82

bsearch ....................................................................................... 3-83

calloc ......................................................................................... 3-85

ceil ............................................................................................. 3-86

circindex .................................................................................... 3-87

circptr ........................................................................................ 3-89

clear_interrupt ............................................................................ 3-92

clip .......................................................................................... 3-101

clock ........................................................................................ 3-102

cos ........................................................................................... 3-103

cosh ......................................................................................... 3-104

count_ones ............................................................................... 3-105

ctime ........................................................................................ 3-106

difftime .................................................................................... 3-107

div ........................................................................................... 3-108

exit ........................................................................................... 3-109

exp ........................................................................................... 3-110

fabs .......................................................................................... 3-111

floor ......................................................................................... 3-112

fmod ........................................................................................ 3-113

free .......................................................................................... 3-114

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

for SHARC Processors

CONTENTS

frexp ......................................................................................... 3-115

getenv ....................................................................................... 3-116

gmtime ..................................................................................... 3-117

heap_calloc ............................................................................... 3-118

heap_free .................................................................................. 3-120

heap_install .............................................................................. 3-122

heap_lookup_name ................................................................... 3-125

heap_malloc ............................................................................. 3-127

heap_realloc .............................................................................. 3-129

interrupt ................................................................................... 3-132

isalnum ..................................................................................... 3-134

isalpha ...................................................................................... 3-135

iscntrl ....................................................................................... 3-136

isdigit ....................................................................................... 3-137

isgraph ...................................................................................... 3-138

isinf .......................................................................................... 3-139

islower ...................................................................................... 3-141

isnan ......................................................................................... 3-142

isprint ....................................................................................... 3-144

ispunct ..................................................................................... 3-145

isspace ...................................................................................... 3-146

isupper ..................................................................................... 3-147

isxdigit ...................................................................................... 3-148

labs ........................................................................................... 3-149

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxvii
for SHARC Processors

CONTENTS

lavg .......................................................................................... 3-150

lclip ......................................................................................... 3-151

lcount_ones .............................................................................. 3-152

ldexp ........................................................................................ 3-153

ldiv .......................................................................................... 3-154

lmax ......................................................................................... 3-155

lmin ......................................................................................... 3-156

localeconv ................................................................................ 3-157

localtime .................................................................................. 3-160

log ........................................................................................... 3-162

log10 ........................................................................................ 3-163

longjmp ................................................................................... 3-164

malloc ...................................................................................... 3-166

max .......................................................................................... 3-167

memchr .................................................................................... 3-168

memcmp .................................................................................. 3-169

memcpy ................................................................................... 3-170

memmove ................................................................................ 3-171

memset .................................................................................... 3-172

min .......................................................................................... 3-173

mktime .................................................................................... 3-174

modf ........................................................................................ 3-176

pow .......................................................................................... 3-177

qsort ........................................................................................ 3-178

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

for SHARC Processors

CONTENTS

raise .......................................................................................... 3-180

rand .......................................................................................... 3-181

realloc ....................................................................................... 3-182

setjmp ...................................................................................... 3-184

setlocale .................................................................................... 3-185

set_alloc_type ........................................................................... 3-186

signal ........................................................................................ 3-188

sin ............................................................................................ 3-190

sinh .......................................................................................... 3-191

sqrt ........................................................................................... 3-192

srand ........................................................................................ 3-193

strcat ........................................................................................ 3-194

strchr ........................................................................................ 3-195

strcmp ...................................................................................... 3-196

strcoll ....................................................................................... 3-197

strcpy ....................................................................................... 3-198

strcspn ...................................................................................... 3-199

strerror ..................................................................................... 3-200

strftime ..................................................................................... 3-201

strlen ........................................................................................ 3-205

strncat ...................................................................................... 3-206

strncmp .................................................................................... 3-207

strncpy ..................................................................................... 3-208

strpbrk ...................................................................................... 3-209

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxix
for SHARC Processors

CONTENTS

strrchr ...................................................................................... 3-210

strspn ....................................................................................... 3-211

strstr ........................................................................................ 3-212

strtod ....................................................................................... 3-213

strtold ...................................................................................... 3-216

strtok ....................................................................................... 3-219

strtol ........................................................................................ 3-221

strtoul ...................................................................................... 3-223

strxfrm ..................................................................................... 3-225

system ...................................................................................... 3-227

tan ........................................................................................... 3-228

tanh ......................................................................................... 3-229

time ......................................................................................... 3-230

tolower ..................................................................................... 3-231

toupper .................................................................................... 3-232

va_arg ...................................................................................... 3-233

va_end ..................................................................................... 3-235

va_start .................................................................................... 3-236

DSP LIBRARY FOR ADSP-2106X AND ADSP-21020

PROCESSORS

DSP Run-Time Library Guide ...................................................... 4-2

Calling DSP Library Functions ................................................ 4-2

Linking DSP Library Functions ............................................... 4-3

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

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

for SHARC Processors

CONTENTS

DSP Header Files .................................................................... 4-4

21020.h — ADSP-21020 DSP Functions ............................ 4-4

21060.h — ADSP-2106x DSP Functions ............................ 4-4

21065L.h — ADSP-21065L DSP Functions ........................ 4-5

asm_sprt.h — Mixed C/Assembly Support .......................... 4-5

cmatrix.h — Complex Matrix Functions .............................. 4-5

comm.h — A-law and µ-law Companders ............................ 4-5

complex.h — Basic Complex Arithmetic Functions .............. 4-5

cvector.h — Complex Vector Functions ............................... 4-6

Header Files Defining Processor-Specific System Register Bits 4-6

Header Files To Allow Access to Memory Mapped Registers From

C/C++ Code .................................................................... 4-7

dma.h — DMA Support Functions ..................................... 4-7

filters.h — DSP Filters ........................................................ 4-8

macros.h — Circular Buffers ............................................... 4-8

math.h — Math Functions .................................................. 4-8

matrix.h — Matrix Functions .............................................. 4-9

saturate.h — Saturation Mode Arithmetic ......................... 4-10

sport.h — Serial Port Support Functions ........................... 4-10

stats.h — Statistical Functions ........................................... 4-10

sysreg.h — Register Access ................................................ 4-10

trans.h — Fast Fourier Transforms ..................................... 4-10

vector.h — Vector Functions ............................................. 4-11

window.h — Window Generators ...................................... 4-11

Built-In DSP Functions ......................................................... 4-13

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxi
for SHARC Processors

CONTENTS

DSP Run-Time Library Reference ............................................... 4-15

a_compress ................................................................................. 4-16

a_expand .................................................................................... 4-17

alog ............................................................................................ 4-18

alog10 ........................................................................................ 4-19

arg ............................................................................................. 4-20

autocoh ...................................................................................... 4-21

autocorr ..................................................................................... 4-23

biquad ........................................................................................ 4-25

cabs ............................................................................................ 4-28

cadd ........................................................................................... 4-29

cartesian ..................................................................................... 4-30

cdiv ............................................................................................ 4-32

cexp ........................................................................................... 4-33

cfftN .......................................................................................... 4-34

cmatmadd .................................................................................. 4-37

cmatmmlt .................................................................................. 4-39

cmatmsub .................................................................................. 4-41

cmatsadd .................................................................................... 4-43

cmatsmlt .................................................................................... 4-45

cmatssub .................................................................................... 4-47

cmlt ........................................................................................... 4-49

conj ............................................................................................ 4-50

convolve ..................................................................................... 4-51

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

for SHARC Processors

copysign ..................................................................................... 4-53

cot .............................................................................................. 4-54

crosscoh ...................................................................................... 4-55

crosscorr ..................................................................................... 4-57

csub ............................................................................................ 4-59

cvecdot ....................................................................................... 4-60

cvecsadd ..................................................................................... 4-62

cvecsmlt ...................................................................................... 4-64

cvecssub ...................................................................................... 4-66

cvecvadd ..................................................................................... 4-68

cvecvmlt ..................................................................................... 4-70

cvecvsub ..................................................................................... 4-72

favg ............................................................................................ 4-74

fclip ............................................................................................ 4-75

fir ............................................................................................... 4-76

fmax ........................................................................................... 4-78

fmin ........................................................................................... 4-79

gen_bartlett ................................................................................ 4-80

gen_blackman ............................................................................. 4-82

gen_gaussian ............................................................................... 4-83

gen_hamming ............................................................................. 4-84

gen_hanning ............................................................................... 4-85

gen_harris ................................................................................... 4-86

gen_kaiser ................................................................................... 4-87

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxiii
for SHARC Processors

gen_rectangular .......................................................................... 4-89

gen_triangle ............................................................................... 4-90

gen_vonhann .............................................................................. 4-92

histogram ................................................................................... 4-93

idle ............................................................................................ 4-95

ifftN .......................................................................................... 4-96

iir ............................................................................................... 4-99

matinv ..................................................................................... 4-102

matmadd .................................................................................. 4-103

matmmlt .................................................................................. 4-105

matmsub .................................................................................. 4-107

matsadd ................................................................................... 4-109

matsmlt .................................................................................... 4-111

matssub .................................................................................... 4-113

mean ........................................................................................ 4-115

mu_compress ........................................................................... 4-116

mu_expand .............................................................................. 4-117

norm ........................................................................................ 4-118

polar ........................................................................................ 4-119

poll_flag_in .............................................................................. 4-121

rfftN ........................................................................................ 4-123

rms .......................................................................................... 4-126

rsqrt ......................................................................................... 4-127

set_flag ..................................................................................... 4-128

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

for SHARC Processors

set_semaphore .......................................................................... 4-130

timer_off .................................................................................. 4-131

timer0_off, timer1_off .............................................................. 4-132

timer_on ................................................................................... 4-133

timer0_on, timer1_on ............................................................... 4-134

timer_set .................................................................................. 4-135

timer0_set, timer1_set ............................................................... 4-137

transpm .................................................................................... 4-139

var ............................................................................................ 4-141

vecdot ....................................................................................... 4-142

vecsadd ..................................................................................... 4-144

vecsmlt ..................................................................................... 4-145

vecssub ..................................................................................... 4-146

vecvadd ..................................................................................... 4-147

vecvmlt ..................................................................................... 4-149

vecvsub ..................................................................................... 4-150

zero_cross ................................................................................. 4-152

DSP LIBRARY FOR ADSP-2116X/2126X/2136X

PROCESSORS

DSP Run-Time Library Guide ....................................................... 5-2

Calling DSP Library Functions ................................................ 5-2

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

Working With Library Source Code ......................................... 5-4

DSP Header Files .................................................................... 5-5

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxv
for SHARC Processors

21160.h – ADSP-2116x DSP Functions .............................. 5-5

21262.h – ADSP-21262 DSP Functions ............................. 5-5

21363.h – ADSP-21363 DSP Functions ............................. 5-5

21364.h – ADSP-21364 DSP Functions ............................. 5-5

21365.h – ADSP-21365 DSP Functions ............................. 5-6

asm_sprt.h – Mixed C/Assembly Support ............................ 5-6

cmatrix.h – Complex Matrix Functions ............................... 5-6

comm.h – A-law and µ-law Companders ............................. 5-6

complex.h – Basic Complex Arithmetic Functions ............... 5-7

cvector.h – Complex Vector Functions ................................ 5-7

Header Files Defining Processor-Specific System Register Bits 5-8

Header Files To Allow Access to Memory Mapped Registers From

C/C++ Code .................................................................... 5-8

dma.h – DMA Support Functions ....................................... 5-9

filter.h – DSP Filters and Transformations ........................... 5-9

filters.h – DSP Filters ....................................................... 5-11

macro.h – Circular Buffers ................................................ 5-11

math.h – Math Functions ................................................. 5-11

matrix.h – Matrix Functions ............................................. 5-13

saturate.h – Saturation Mode Arithmetic ........................... 5-13

sport.h – Serial Port Support Functions ............................. 5-13

stats.h – Statistical Functions ............................................ 5-13

sysreg.h – Register Access .................................................. 5-14

trans.h – Fast Fourier Transforms ...................................... 5-14

vector.h – Vector Functions ............................................... 5-14

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

for SHARC Processors

window.h – Window Generators ........................................ 5-14

Built-In DSP Functions ......................................................... 5-15

Implications of Using SIMD Mode ........................................ 5-17

DSP Run-Time Library Reference ............................................... 5-19

a_compress ................................................................................. 5-20

a_expand .................................................................................... 5-21

alog ............................................................................................ 5-22

alog10 ........................................................................................ 5-23

arg .............................................................................................. 5-24

autocoh ...................................................................................... 5-25

autocorr ...................................................................................... 5-27

biquad ........................................................................................ 5-29

cabs ............................................................................................ 5-32

cadd ........................................................................................... 5-33

cartesian ..................................................................................... 5-34

cdiv ............................................................................................ 5-36

cexp ............................................................................................ 5-37

cfft_mag ..................................................................................... 5-38

cfftN .......................................................................................... 5-40

cfftf ............................................................................................ 5-43

cmatmadd ................................................................................... 5-46

cmatmmlt ................................................................................... 5-48

cmatmsub ................................................................................... 5-50

cmatsadd .................................................................................... 5-52

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxvii
for SHARC Processors

cmatsmlt .................................................................................... 5-54

cmatssub .................................................................................... 5-56

cmlt ........................................................................................... 5-58

conj ............................................................................................ 5-59

convolve ..................................................................................... 5-60

copysign ..................................................................................... 5-62

cot ............................................................................................. 5-63

crosscoh ..................................................................................... 5-64

crosscorr ..................................................................................... 5-66

csub ........................................................................................... 5-68

cvecdot ....................................................................................... 5-69

cvecsadd ..................................................................................... 5-71

cvecsmlt ..................................................................................... 5-73

cvecssub ..................................................................................... 5-75

cvecvadd ..................................................................................... 5-77

cvecvmlt ..................................................................................... 5-79

cvecvsub ..................................................................................... 5-81

favg ............................................................................................ 5-83

fclip ........................................................................................... 5-84

fir .............................................................................................. 5-85

fmax ........................................................................................... 5-87

fmin ........................................................................................... 5-88

gen_bartlett ................................................................................ 5-89

gen_blackman ............................................................................ 5-91

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

for SHARC Processors

gen_gaussian ............................................................................... 5-92

gen_hamming ............................................................................. 5-93

gen_hanning ............................................................................... 5-94

gen_harris ................................................................................... 5-95

gen_kaiser ................................................................................... 5-96

gen_rectangular .......................................................................... 5-98

gen_triangle ................................................................................ 5-99

gen_vonhann ............................................................................ 5-101

histogram ................................................................................. 5-102

idle ........................................................................................... 5-104

ifftN ......................................................................................... 5-105

iir ............................................................................................. 5-108

matinv ...................................................................................... 5-112

matmadd .................................................................................. 5-113

matmmlt .................................................................................. 5-115

matmsub .................................................................................. 5-117

matsadd .................................................................................... 5-119

matsmlt .................................................................................... 5-121

matssub .................................................................................... 5-123

mean ........................................................................................ 5-125

mu_compress ............................................................................ 5-126

mu_expand ............................................................................... 5-127

norm ........................................................................................ 5-128

polar ......................................................................................... 5-129

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxix
for SHARC Processors

poll_flag_in .............................................................................. 5-131

rfft_mag ................................................................................... 5-133

rfftN ........................................................................................ 5-135

rms .......................................................................................... 5-138

rsqrt ......................................................................................... 5-139

set_flag ..................................................................................... 5-140

set_semaphore .......................................................................... 5-142

timer_off .................................................................................. 5-143

timer_on .................................................................................. 5-144

timer_set .................................................................................. 5-145

transpm .................................................................................... 5-147

twidfftf ..................................................................................... 5-149

var ........................................................................................... 5-151

vecdot ...................................................................................... 5-153

vecsadd .................................................................................... 5-155

vecsmlt ..................................................................................... 5-157

vecssub ..................................................................................... 5-159

vecvadd .................................................................................... 5-161

vecvmlt .................................................................................... 5-163

vecvsub .................................................................................... 5-165

zero_cross ................................................................................. 5-167

INDEX

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

for SHARC Processors

PREFACE

Thank you for purchasing Analog Devices, Inc. development software for
signal processing applications.

Purpose of This Manual

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

run-time library for SHARC® (ADSP-21xxx) processors. It includes syn­tax for command lines, switches, and language extensions. It leads you
through the process of using library routines and writing mixed
C/C++/assembly code.

Intended Audience

The primary audience for this manual is a programmer who is familiar
with Analog Devices processors. This manual assumes that the audience
has a working knowledge of the SHARC architecture and instruction set
and the C/C++ programming languages.

Programmers who are unfamiliar with SHARC processors can use this
manual, but they should supplement it with other texts (such as the
appropriate hardware reference and programming reference manuals) that
describe your target architecture.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxi
for SHARC Processors

Manual Contents

Manual Contents

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”

Shows how to optimize compiler operation

• 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)

• Chapter 4, “DSP Library for ADSP-2106x and ADSP-21020 Pro-

cessors”

Shows how to use DSP library functions and provides a complete
library function reference used with ADSP-2106x and
ADSP-21020 processors (for functions covered in the current com­piler release)

• Chapter 5, “DSP Library for ADSP-2116x/2126x/2136x Proces-

sors”

Shows how to use DSP library functions and provides a complete
library function reference used with ADSP-2116x/2126x/2136x
processors (for functions covered in the current compiler release)

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

for SHARC Processors

Preface

What’s New in This Manual

This edition of the VisualDSP++ 4.0 C/C++ Compiler and Library Manual
for SHARC Processors documents support for all current SHARC proces-

sors listed in “Supported Processors”.

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

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

[e-mail]

• E-mail processor questions to

[e-mail]

• Phone questions to 1-800-ANALOGD

• Contact your Analog Devices, Inc. local sales office or authorized
distributor

• Send questions by mail to:

Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
USA

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxiii
for SHARC Processors

Supported Processors

Supported Processors

The name “SHARC” refers to a family of Analog Devices, Inc.
high-performance 32-bit floating-point digital signal processors that can
be used in speech, sound, graphics, and imaging applications.
VisualDSP++® currently supports the following SHARC processors:

ADSP-21020 ADSP-21060 ADSP-21061 ADSP-21062

ADSP-21065L ADSP-21160 ADSP-21161 ADSP-21261

ADSP-21262 ADSP-21266 ADSP-21267 ADSP-21363

ADSP-21364 ADSP-21365 ADSP-21366 ADSP-21367

ADSP-21368 ADSP-21369

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 www.analog.com. Our Web site provides infor­mation about a broad range of products: analog integrated circuits,
amplifiers, converters, and digital signal processors.

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.

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

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

for SHARC Processors

Preface

Registration

Visit

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

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

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

[e-mail]

• Fax questions or requests for information to

1-781-461-3010 (North America)
089/76 903-557 (Europe)

• Access the FTP Web site at

ftp ftp.analog.com or ftp 137.71.23.21
ftp://ftp.analog.com

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxv
for SHARC Processors

Product Information

Related Documents

For information on product related development software, see these
publications:

• VisualDSP++ 4.0 Getting Started Guide

• VisualDSP++ 4.0 User’s Guide

• VisualDSP++ 4.0 C/C++ Assembler and Preprocessor Manual

• VisualDSP++ 4.0 Linker and Utilities Manual

• VisualDSP++ 4.0 Loader Manual

• VisualDSP++ 4.0 Product Release Bulletin

• VisualDSP++ Kernel (VDK) User’s Guide

• Quick Installation Reference Card

For hardware information, refer to your processors’s hardware reference,
programming reference, or data sheet. All documentation is available
online. Most documentation is available in printed form.

Visit the Technical Library Web site to access all processor and tools man­uals and data sheets:

http://www.analog.com/processors/resources/technicalLibrary

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

for SHARC Processors

Preface

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, supple­mentary

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 doc­umentation. Viewing and printing the .HTML files requires a browser, such as
Internet Explorer 4.0 (or higher).

Viewing and printing the .PDF files requires a PDF reader, such as Adobe Acrobat
Reader (4.0 or higher).

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 (tool­bar buttons, menu commands, and windows).

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xxxvii
for SHARC 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 documenta­tion 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 sys­tem, 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.

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

for SHARC 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.0 C/C++ Compiler and Library Manual xxxix
for SHARC Processors

Notation Conventions

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.

Notation Conventions

Text conventions used in this manual are identified and described as
follows.

L

Example Description

Close command
(File menu)

{this | that} Alternative required items in syntax descriptions appear within curly

[this | that] Optional items in syntax descriptions appear within brackets and sepa-

[this,…] Optional item lists in syntax descriptions appear within brackets

.SECTION Commands, directives, keywords, and feature names are in text with

filename Non-keyword placeholders appear in text with italic style format.

appear throughout this document.

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 this or that.

delimited by commas and terminated with an ellipse; read the example
as an optional comma-separated list of

letter gothic font.

this.

Additional conventions, which apply only to specific chapters, may

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

for SHARC Processors

Example Description

Note: For correct operation, ...

L

a

[

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.

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.

Preface

VisualDSP++ 4.0 C/C++ Compiler and Library Manual xli
for SHARC Processors

Notation Conventions

xlii VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

1 COMPILER

The C/C++ compiler (cc21k) is part of Analog Devices development soft­ware for SHARC (ADSP-21xxx) processors.

L

This chapter contains:

The code examples in this manual have been compiled using
VisualDSP++ 4.0. The examples compiled with other versions of
VisualDSP++ may result in build errors or different output
although the highlighted algorithms stand and should continue to
stand in future releases of VisualDSP++.

• “C/C++ Compiler Overview” on page 1-2
provides an overview of C/C++ compiler for SHARC processors.

• “Compiler Command-Line Interface” on page 1-4
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-70
describes the
dard for the C and C++ languages.

• “Preprocessor Features” on page 1-165
contains information on the preprocessor and ways to modify
source compilation.

• “C/C++ Run-Time Model and Environment” on page 1-175
contains reference information about implementation of C/C++
programs, data, and function calls in ADSP-21xxx processors.

cc21k compiler’s extensions to the ISO/ANSI stan-

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-1
for SHARC Processors

C/C++ Compiler Overview

• “C/C++ and Assembly Interface” on page 1-209
describes how to call an assembly language subroutine from a 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-238
describes how templates are instantiated at compile time

C/C++ Compiler Overview

The C/C++ compiler (cc21k) is designed to aid your project development
efforts by:

• Processing C and C++ source files, producing machine-level ver­sions 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 processor
operations without having to understand the underlying processor
architecture.

The C/C++ compiler (cc21k) compiles ISO/ANSI standard C and C++
code for the SHARC processors. Additionally, Analog Devices includes
within the compiler a number of C language extensions designed to assist
in processor development. The compiler runs from the VisualDSP++ envi­ronment or from an operating system command line.

1-2 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

The C/C++ compiler (

cc21k) processes your C and C++ language source

files and produces SHARC assembler source files. The assembler source
files are assembled by the SHARC assembler (easm21k). The assembler
creates Executable and Linkable Format (ELF) object files that can either
be linked (using the linker) to create an ADSP-21xxx executable file or
included in an archive library (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.

Your source files contain the C/C++ program to be processed by the com­piler. The cc21k 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 rec­ommends 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 cc21k compiler supports a set of C/C++ language extensions. These
extensions support hardware features of the ADSP-21xxx processors. For
information on these extensions, see “C/C++ Compiler Language Exten-

sions” on page 1-70.

You can set the compiler options from the Compile page of the Project
Options dialog box of the VisualDSP++ Integrated Development and
Debug Environment (IDDE) (see “Specifying Compiler Options in Visu-

alDSP++” on page 1-9). These selections control how the compiler

processes your source files, letting you select features that include the lan­guage dialect, error reporting, and debugger output.

For more information on the VisualDSP++ environment, see the
VisualDSP++ 4.0 User’s Guide and online Help.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-3
for SHARC Processors

Compiler Command-Line Interface

Compiler Command-Line Interface

This section describes how the ADSP-21xxx 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-5

• “Specifying Compiler Options in VisualDSP++” on page 1-9

• “Compiler Command-Line Switches” on page 1-11

• “Data Type and Data Type Sizes” on page 1-61

• “Environment Variables Used by the Compiler” on page 1-63

• “Optimization Control” on page 1-64

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-1 on page 1-7 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-2 on

page 1-8). Table 1-3 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-4 on page 1-12. A summary of the C++-spe­cific compiler switches appears in Table 1-5 on page 1-21. The summaries
are followed by descriptions of each switch.

1-4 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

L

compiler’s default options settings. The way the compiler’s options
are set depends on the environment used to run the processor
development software. See “Specifying Compiler Options in Visu-

alDSP++” on page 1-9 for more information.

Running the Compiler

Use the following syntax for the cc21k command line:

cc21k [-switch [-switch …] sourcefile [sourcefile …]]

runs the compiler with

When developing a project, sometimes it is useful to modify the

cc21k

-switch

sourceFile

Name of the compiler program for SHARC processors.

Switch (or switches) to process.
The compiler has many switches. These switches select the opera­tions and modes for the compiler and other tools. Command-line
switches are case sensitive. For example,

Name of the file to be preprocessed, compiled, assembled, and/or
l

inked

-O is not the same as -o.

The name of the source file to be processed:

can include the drive, directory, file name and file extension. The
compiler supports both Win32 and POSIX-style paths by using
forward or back slashes as the directory delimiter. It also supports
UNC path names (starting with two slashes and a network name).

If its length exceeds eight characters or contains spaces, enclose it
in straight quotes; for example, “long file name.c”. The cc21k
compiler uses the file extension to determine what the file contains
(Table 1-2 on page 1-8) and what operations to perform upon it
(Table 1-1 on page 1-7).

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-5
for SHARC Processors

Compiler Command-Line Interface

For example, the following command line

cc21k -O -proc ADSP-21161 -Wremarks -o program.dxe source.c

runs cc21k with:

-proc ADSP-21161 Specifies compiler instructions unique to the

ADSP-21161 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

cc21k -c++ source.cpp

runs cc21k with:

-c++ Specifies all of the source files to be compiled in

C++ mode

source.cpp Specifies the C++ language source file to be

compiled

The normal function of

cc21k is to invoke the compiler, assembler, and

linker as required to produce an executable object file. The precise opera­tion is determined by the extensions of the input filenames and by various
switches.

In normal operation, the compiler uses the files listed in Table 1-1 to per­form the 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.

1-6 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

Table 1-1. 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 com­piler 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, cc21k names the out­put for you. Table 1-2 on page 1-8 lists the type of files, names, and
extensions cc21k appends to output files.

File extensions vary by command-line switch and file type. These exten­sions 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-2 indicates the searches that the preprocessor, com­piler, 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-32)
and -L directory switch (on page 1-34).

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 unambig­uous 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 cc21k compiler uses the file extension conven-

‘long

tions listed in Table 1-2 to determine the input file type.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-7
for SHARC Processors

Compiler Command-Line Interface

• Verify that the compiler is using the correct file. If you do not pro­vide the complete file path as part of the parameter or add
additional search directories,

cc21k looks for input in the current

directory.

L

assembler, and linker causes each of these tools to echo the name of
each file as it is processed.

Table 1-2. Input and Output Files

Input File Extension File Extension Description

.c C source file.

.cc, .cpp, .cxx C++ source file

.h Header file (referenced by a #include directive)

.hpp .hh .hxx .h++ C++ header file (referenced by a #include statement)

.pch C++ pre-compiled header file

.ii, .ti Template instantiation files – used internally by the compiler when

instantiating templates

.ipa, .opa Interprocedural analysis files – used internally by the compiler when

performing interprocedural analysis

.i Preprocessed C source, created when preprocess only is specified

.s, .asm Assembler source file

.is Preprocessed assembly source (retained when -save-temps is speci-

fied)

Using the verbose output switches for the preprocessor, compiler,

.ldf Linker Description File

.doj Object file to be linked

.dlb Library of object files to be linked as needed

.dxe Executable file produced by compiler

.xml Processor memory map file output

.sym Processor symbol map file output

1-8 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

The compiler refers to a number of environment variables during its oper­ation, and these environment variables can affect the compiler’s behavior.
Refer to “Environment Variables Used by the Compiler” on page 1-63 for
more information.

Specifying Compiler Options in VisualDSP++

When using the VisualDSP++ Integrated Development and Debug Envi­ronment (IDDE), use the Compile option from the Project Options
dialog box to set compiler functional options as shown on Figure 1-1.

Figure 1-1. Project Options — Compile Tab

There are four sub-pages you can access—General, Preprocessor, Proces-
sor, and Warning. Most page options have a corresponding compiler
command-line switch described in “Compiler Command-Line Switches”

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-9
for SHARC Processors

Compiler Command-Line Interface

on page 1-11. The Additional options field is used to enter the appropri-

ate file names and options that do not have corresponding controls on the
Compile tab but are available as compiler switches.

For example, the Processor page (Figure 1-2) provides selection of data
word sizes, processor speed, and other options.

Figure 1-2. Project Options – Compile (Processor) Page

For more information, use the VisualDSP++ context-sensitive online Help
for each target architecture to select information on compiler options you
can specify in VisualDSP++. To do that, click on the ? button and then
click in a field or box you need information about.

1-10 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC 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 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).

• “C or C++ Mode Selection Switches”, Table 1-3

• “C/C++ Compiler Common Switches”, Table 1-4

• “C++ Mode Compiler Switches”, Table 1-5 on page 1-21

A brief description of each switch follows the tables, beginning

on page 1-22.

Table 1-3. 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. Note that C++ is not supported on the
ADSP-21020 processor.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-11
for SHARC Processors

Compiler Command-Line Interface

Table 1-4. C/C++ Compiler Common Switches

Switch Name Description

sourcefile

(on page 1-23)

-@ filename

(on page 1-23)

-A name[tokens]

(on page 1-23)

-aligned-stack

(on page 1-24)

-alttok

(on page 1-24)

-annotate-loop-instr

(on page 1-25)

-bss

(on page 1-25)

-build-lib

(on page 1-25)

-C

(on page 1-25)

-c

(on page 1-26)

-compatible-pm-dm

(on page 1-26)

Specifies file to be compiled

Reads command-line input from the file

Asserts the specified name as a predicate

Aligns the program stack on a double-word boundary

Allows alternative keywords and sequences in sources

Provides additional annotation information for the prolog,
kernel and epilog of a loop

Places zero-initialized global data into a BSS section

Directs the librarian to build a library file

Retains preprocessor comments in the output file; must
run with the -E or -P switch

Compiles and/or assembles only, but does not link

Specifies that the compiler shall treat dm- and pm-qualified
pointers as assignment-compatible

-const-read-write

(on page 1-26)

-Dmacro[=definition]

Specifies that data accessed via a pointer to
may be modified elsewhere

Defines a macro.

const data

(on page 1-26)

-debug-types

(on page 1-26)

-default-linkage-{asm|C|C++}

Supports building an

*.h file directly and writing a com-

plete set of debugging information for the header file

Sets the default linkage type (

C, C++, asm)

(on page 1-27)

1-12 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-double-size [-32|-64]

(on page 1-27)

-double-size-any

(on page 1-28)

-dry

(on page 1-28)

-dryrun

(on page 1-28)

-E

(on page 1-29)

-ED

(on page 1-29)

-EE

(on page 1-29)

-extra-keywords

(on page 1-29)

-flags-{tools} <arg1>
[,arg2...]

(on page 1-29)

-float-to-int

(on page 1-30)

Selects 32- or 64-bit IEEE format for double.
The -double-size-32 is the default mode.

Indicates that the resulting object can be linked with
objects built with any double size

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

Preprocesses and compiles the source file

Recognizes ADI extensions to ANSI/ISO standards for C
and C++ (default mode)

Passes command-line switches through the compiler to
other build tools

Uses a support library function to convert a float to an

integer

-force-circbuf

(on page 1-26)

-fp-associative

(on page 1-30)

-full-version

(on page 1-30)

-g

Treats array references of the form

array[i%n] as circular

buffer operations

Treats floating-point multiply and addition as an associa­tive

Displays the version number of the driver and any pro­cesses invoked by the driver

Generates DWARF-2 debug information

(on page 1-31)

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-13
for SHARC Processors

Compiler Command-Line Interface

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-H

(on page 1-31)

-HH

(on page 1-31)

-h[elp]

(on page 1-32)

-I directory

(on page 1-32)

-I-

(on page 1-32)

-i

(on page 1-32)

-include filename

(on page 1-33)

-ipa

(on page 1-33)

-L directory

(on page 1-34)

-l library

(on page 1-34)

Outputs a list of included header files, but does not com­pile

Outputs a list of included header files and compiles

Outputs a list of command-line switches

Appends directory to the standard search path

Establishes the point in the include directory list at
which the search for header files enclosed in angle brackets
should begin

Outputs only header details or makefile dependencies for

include files specified in double quotes

Includes named file prior to preprocessing each source file

Enables interprocedural analysis

Appends directory to the standard library search path

Searches library for functions when linking

-M

Generates make rules only, but does not compile

(on page 1-35)

-MD

Generates make rules, compiles, and prints to a file

(on page 1-35)

-MM

Generates make rules and compiles

(on page 1-35)

-Mo filename

(on page 1-35)

Writes dependency information to
is used in conjunction with the

-ED or -MD options

filename. This switch

1-14 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-Mt filename

(on page 1-35)

-MQ

(on page 1-36)

-map filename

(on page 1-36)

-mem

(on page 1-36)

-multiline

on page 1-36

-no-aligned-stack

(on page 1-36)

-no-alttok

(on page 1-36)

-no-annotate

(on page 1-37)

-no-annotate-loop-instr

(on page 1-37)

-no-bss

(on page 1-37)

Makes dependencies, where the target is renamed as

filename

Generates make rules only; does not compile. No notifica­tion when input files are missing

Directs the linker to generate a memory map of all sym­bols

Enables memory initialization

Enables string literals over multiple lines (default)

Does not double-word align the program stack

Does not allow alternative keywords and sequences in
sources

Disables the annotation of assembly files

Disables the production of additional loop annotation
information by the compiler (default mode)

Causes the compiler to group global zero-initialized data
into the same section as global data with non-zero initial­izers. Set by default

-no-builtin

(on page 1-37)

-no-circbuf

(on page 1-38)

-no-db

(on page 1-38)

-no-defs

(on page 1-38)

Recognizes only built-in functions that begin with two
underscores(

__)

Disables the automatic generation of circular buffer code
by the compiler

Specifies that the compiler shall not generate code con­taining delayed branches jumps

Disables preprocessor definitions: macros, include directo­ries, library directories, run-time headers, or keyword
extensions

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-15
for SHARC Processors

Compiler Command-Line Interface

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-no-extra-keywords

(on page 1-38)

-no-fp-associative

(on page 1-38)

-no-mem

(on page 1-39)

-no-multiline

(on page 1-39)

-no-saturation

(on page 1-39)

-no-simd

(on page 1-39)

-no-std-ass

(on page 1-39)

-no-std-def

(on page 1-40)

-no-std-inc

(on page 1-40)

-no-std-lib

(on page 1-40)

Does not accept ADI keyword extensions that might affect
ISO/ANSI standards for C and C++

Does not treat floating-point multiply and addition as an
associative

Disables memory initialization

Disables multiple line string literal support

Causes the compiler not to introduce saturation semantics
when optimizing expressions

Disables automatic SIMD mode when compiling for
ADSP-2116x, ADSP-2126x or ADSP-2136x processors

Disables any predefined assertions and system-specific
macro definitions

Disables preprocessor definitions and ADI keyword exten­sions that do not have leading underscores(__)

Searches for preprocessor include header files only in the
current directory and in directories specified with the -I
switch

Searches for only those library files specified with the

-l

switch

-no-threads

Specifies that all compiled code need not be thread-safe

(on page 1-40)

-O [0|1]

Enables code optimizations

(on page 1-40)

-Oa

Enables automatic function inlining

(on page 1-41)

-Og

(on page 1-41)

Enables a compiler mode that performs optimizations
while still preserving the debugging information

1-16 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-Os

(on page 1-41)

-Ov num

(on page 1-41)

-o filename

(on page 1-42)

-P

(on page 1-42)

-PP

(on page 1-42)

-path-{asm|compiler|lib|
link|mem} directory

(on page 1-42)

-path-install directory
(on page 1-42)

-path-output directory
(on page 1-43)

-path-temp directory
(on page 1-43)

-pch

(on page 1-43)

Optimizes for code size

Controls speed versus size optimizations

Specifies the output file name

Preprocesses, but does not compile, the source file; omits
line numbers in the preprocessor output

Similar to -P, but does not halt compilation after prepro­cessing

Uses the specified directory as the location of the specified
compilation tool (assembler, compiler, librarian, linker, or
and memory initializer, respectively)

Uses the specified directory as the location of all compila­tion tools

Specifies the location of non-temporary files

Specifies the location of temporary files

Generates and uses precompiled header files (*.pch)

-pchdir directory
(

on page 1-43)

-pedantic

(on page 1-43)

-pedantic-errors

(on page 1-44)

-pguide

(on page 1-44)

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

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-17
for SHARC Processors

Compiler Command-Line Interface

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-pplist filename

(on page 1-44)

-proc processor

(on page 1-45)

-progress-rep-func

(on page 1-45)

-progress-rep-gen-opt

(on page 1-45)

-progress-rep-mc-opt

(on page 1-46)

-R directory

(on page 1-46)

-R-

(on page 1-47)

-reserve <reg1>[,reg2...]

(on page 1-47)

-restrict-hardware-loops
<maximum> (on page 1-47)

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.

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

Removes all directories from the standard search path for
source files

Reserves certain registers from compiler use.
Note: Reserving registers can have a detrimental effect on
the compiler’s optimization capabilities.

Restrict the number of levels of loop nesting used by the
compiler

-S

Stops compilation before running the assembler

(on page 1-47)

-s

Removes debug info from the output executable file

(on page 1-48)

-save-temps

Saves intermediate files

(on page 1-48)

-section <id>=<section_name>

(on page 1-48)

-show

Orders the compiler to place data/program of type “
into the section “

section_name”

Displays the driver command-line information

id”

(on page 1-48)

1-18 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

Compiler

-si-revision version

(on page 1-49)

-signed-bitfield

(on page 1-50)

-signed-char

(on page 1-50)

-structs-do-not-overlap

(on page 1-51)

-switch-pm

(on page 1-51)

-syntax-only

(on page 1-51)

-sysdefs

(on page 1-52)

-T filename

(on page 1-52)

-threads

(on page 1-52)

-time

(on page 1-53)

Specifies a silicon revision of the specified processor. The
default setting is the latest silicon revision.

Makes the default type for int bitfields signed

Makes the default type for

char signed

Specifies that struct copies may use “memcpy” semantics,
rather than the usual “memmove” behavior

Specifies that the compiler should place switch tables in
program memory

Checks the source code for compiler syntax errors, but
does not write any output

Defines the system definition macros

Specifies the Linker Description File

Specifies that support for multithreaded applications is to
be enabled

Displays the elapsed time as part of the output informa­tion on each part of the compilation process

-Umacro

Undefines macro(s)

on page 1-53

-unsigned-bitfield

Makes the default type for plain

int bitfields unsigned

(on page 1-53)

-unsigned-char

Makes the default type for

char unsigned

(on page 1-54)

-v

Displays both the version and command-line information

(on page 1-54)

-verbose

Displays command-line information

(on page 1-54)

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-19
for SHARC Processors

Compiler Command-Line Interface

Table 1-4. C/C++ Compiler Common Switches (Cont’d)

Switch Name Description

-version

(on page 1-54)

-W{error|remark|
suppress|warn} number

(on page 1-55)

-Wdriver-limit number

(on page 1-55)

-Werror-limit number

(on page 1-55)

-Wremarks

(on page 1-55)

-Wterse

(on page 1-55)

-w

(on page 1-56)

-warn-protos

(on page 1-56)

-workaround <workaround>

(on page 1-56)

-write-files

(on page 1-56)

Displays version information

Overrides the default severity of the specified error mes­sage

Aborts the driver after reaching the specified number of
errors

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 warning, errors,
and remarks.

Does not display compiler warning messages

Produces a warnings when a function is called without a
prototype

Enables code generator workaround for specific hardware
errata

Enables compiler I/O redirection

-write-opts

(on page 1-57)

-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-57)

1-20 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Table 1-5. C++ Mode Compiler Switches

Switch Name Description

Compiler

-anach

on page 1-58

-eh

on page 1-59

-no-anach

on page 1-60

-no-demangle

(on page 1-60)

-no-eh

on page 1-60

-no-implicit-inclusion

(on page 1-60)

-no-rtti

on page 1-60

-rtti

on page 1-61

Supports some language features (anachronisms) that are prohib­ited by the C++ standard but still in common use

Enables exception handling

Disallows the use of anachronisms that are prohibited by the C++
standard

Prevents filtering of any linker errors through the demangler

Disables exception-handling

Prevents implicit inclusion of source files as a method of finding
definitions of template entities to be instantiated

Disables run-time type information

Enables run-time type information

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-21
for SHARC 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 stan­dard, the following switches should be used: -alttok, -const-read-write,

no-extra-keywords, and -pedantic (see Table 1-4 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 is
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. Sup­port for these features can be enabled with the -eh and -rtti switches (see

Table 1-5).

C++ is not supported on the ADSP-21020 processor.

L

1-22 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

C/C++ Compiler Common Switch Descriptions

The following command-line switches apply in both C and C++ modes.

sourcefile

The

sourcefile parameter (or parameters) 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

cc21k compiler uses the file extension to determine the operations to per-

form. Table 1-2 on page 1-8 lists the permitted extensions and matching
compiler operations.

-@ filename

The -@filename (command file) switch directs the compiler to read
command-line input from filename.

-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 prepro­cessor directive. The following assertions are predefined:

system embedded

machine adsp21xxx

cpu adsp21xxx

compiler cc21k

-A name(value) switch is equivalent to including

The

#assert name(value)

in your source file, and both may be tested in a preprocessor condition in
the following manner:

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-23
for SHARC Processors

Compiler Command-Line Interface

#if #name(value)

// do something

#else

// do something else

#endif

For example, the default assertions may be tested as:

#if #machine(adsp21xxx)

// do something

#endif

L

switch, to prevent misinterpretation. No quotes are needed for a

#assert directive in a source file.

-aligned-stack

The -aligned-stack switch directs the compiler to align the program
stack on a double-word boundary.

-alttok

The -alttok (alternative tokens) switch directs the compiler to allow
alternative operator keywords and digraph sequences in source files. Addi­tionally, this switch enables the recognition of these alternative operator
keywords in C++ source files:

Keyword Equivalent

and &&

and_eq &=

bitand &

bitor |

compl ~

or ||

or_eq |=

not !

The parentheses in the assertion need quotes when using the -A

1-24 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Keyword Equivalent

not_eq !=

xor ^

xor_eq ^=

Compiler

L

<iso646.h>

.

-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-51 for more details on
this feature.

-bss

The -bss (build library) switch directs the compiler to place global data
into a BSS-style section (called “bsz”), rather than into normal global data
section. See also “-no-bss” on page 1-37.

-build-lib

The -build-lib (build library) switch directs the compiler to use the

To use alternative tokens in C, you should use #include

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 may only be run in combination with
the

-E or -P switches, directs the C/C++ preprocessor to retain comments

in its output file.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-25
for SHARC 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.

-compatible-pm-dm

The compatible-pm-dm switch specifies that the compiler shall treat dm­and pm-qualified pointers as assignment-compatible.

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

-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 ‘1’. Note that the compiler processes all
the command line before any

-U (undefine macro) switches.

-D switches on

-debug-types

-debug-types switch builds a *.h file directly and writes a complete

The
set of debugging information for the header file. The
be specified with the

-debug-types switch because it is implied. For

-g option need not

example,

cc21k -debug-types anyHeader.h

1-26 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

Until the introduction of

*.h file as a valid input file. The implicit -g option writes debugging infor-

-debug-types, the compiler would not accept a

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-linkage[-asm | -C | -C++]

The -default-linkage-asm (assembler linkage), -default-linkage-C (C
linkage), and -default-linkage-C++ (C++ linkage) directs the compiler to
set the default linkage type. C linkage is the default type in C mode, and
C++ linkage is the default type in C++ mode.

Invoke this switch with the Additional Options box located in the

L

VisualDSP++ Project Options dialog box, Compile tab, General
category.

-double-size[-32|-64]

The -double-size-32 (double is 32 bits) and the -double-size-64 (dou­ble is 64 bits) switches select the storage format that the compiler uses for
type double. The default mode is -double-size-32.

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 emulated 64-bit
floating-point arithmetic, even when variables are declared consistently as

float.

To avoid this problem, cc21k 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

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 standard requires that double

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-27
for SHARC Processors

Compiler Command-Line Interface

maintains 10 digits of precision, which requires 64 bits of storage. The

-double-size-64 switch sets the size of double to 64 bits for full standard

conformance.

With -double-size-32, a double is stored in 32-bit IEEE single-precision
format and is operated on using fast hardware floating-point instructions.
Standard math functions such as sin also operate on 32-bit values. This
mode is the default and is recommended for most programs. Calculations
that need higher precision can be done with the long double type, which
is always 64 bits.

With -double-size-64, a double is stored in 64-bit IEEE single 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__
macro, while the -double-size-64 switch undefines the

__DOUBLES_ARE_FLOATS__ macro.

-double-size-any

The -double-size-any switch specifies that the resulting object files
should be marked in such a way that will enable them to be linked against
objects built with

doubles either 32-bit or 64-bit in size.

-dry

The -dry (verbose dry-run) switch directs the compiler to display main
driver actions, but not to perform them.

-dryrun

The -dryrun (terse dry-run) switch directs the compiler to display
top-level driver actions, but not to perform them.

1-28 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

-E

The

-E (stop after preprocessing) switch directs the compiler to stop after

the C/C++ preprocessor runs (without compiling). The output (prepro­cessed source code) prints to the standard output stream (<stdout>) unless
the output file is specified with the -o switch. Note that the -C switch can
only be run in combination with the -E switch.

L

-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 -EE (run after preprocessing) switch is similar to the -E switch, but it
does not halt compilation after preprocessing.

-extra-keywords

The
compiler to recognize the Analog Devices keyword extensions to
ANSI/ISO standard C and C++, such as
scores, which can affect conforming ANSI/ISO C and C++ programs.
This is the default mode.

Invoke this switch with the Stop after: Preprocessor check box
located in the VisualDSP++ Project Options dialog box, Compile
tab, General category.

-extra-keywords (enable short-form keywords) switch directs the

pm and dm, without leading under-

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

-flags (command-line input) switch directs the compiler to pass

The
command-line switches to the other build tools. The tools are:

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-29
for SHARC Processors

Compiler Command-Line Interface

Option Tool

-flags-asm Assembler

-flags-compiler Compiler executable

-flags-lib Library Builder (elfar.exe)

-flags-link Linker

-flags-mem Memory Initializer

-float-to-int

The

-float-to-int switch instructs the compiler to use a support library

function to convert a float to an integer. The library support routine per­forms extra checking to avoid a floating-point underflow occurring.

-force-circbuf

The -force-circbuf (circular buffer) switch instructs the compiler to
make use of circular buffer facilities, even if the compiler cannot verify
that the circular index or pointer is always within the range of the buffer.
Without this switch, the compiler's default behavior is conservative, and
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-107.

-fp-associative

-fp-associative switch directs the compiler to treat floating-point

The
multiplication and addition as an associative. This switch is on by default.

-full-version

The -full-version (display versions) switch directs the compiler to dis­play version information for build tools used in a compilation.

1-30 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

-g

The

-g (generate debug information) switch directs the compiler to out-

put symbols and other information used by the debugger.

When the -g switch is used in conjunction with the enable optimization
(-O) switch, the compiler performs standard optimizations. The compiler
also outputs symbols and other information to provide limited
source-level debugging through the VisualDSP++ IDDE (debugger). This
combination of options provides line debugging and global variable
debugging.

L

L

-H

The
the files included by the preprocessor via the #include directive, without
compiling.

-HH

The -HH (list headers and compile) switch directs the compiler to output
to the standard output stream a list of the files included by the preproces­sor via the #include directive. After preprocessing, compilation proceeds
normally.

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 capabil­ities, use the -g switch without the -O switch. See also the -Og
switch (on page 1-41).

Invoke this switch by selecting the Generate debug information
check box in the VisualDSP++ Project Options dialog box,
Compile tab, General category.

-H (list headers) switch directs the compiler to output only a list of

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-31
for SHARC Processors

Compiler Command-Line Interface

-h[elp]

The

-help (command-line help) switch directs the compiler to output a

list of command-line switches with a brief syntax description.

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

The -I (include search directory) switch directs the C/C++ compiler pre­processor 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 directo­ries in this order:

1. The directory containing the current input file (the primary source
file or the file containing the #include)

2. Any directories specified with the -I switch in the order they are
listed on the command line

3. Any directories on the standard list:

<VDSP++ install dir>/.../include

If a file is included using the <...> form, this file is only searched

L

for by using directories defined in items 2 and 3 above.

-I-

-I- (start include directory list) switch establishes the point in the

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.

1-32 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

L

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 com­mand 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.

L

-i

The -i (less includes) switch may be used with the –H, -HH, -M, or -MM
switches to direct the compiler to only output header details (-H, -HH) or
makefile dependencies (-M, -MM) for include files specified in double
quotes.

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

For header files in angle brackets, the compiler performs the latter
two searches only.

This switch removes the directory containing the current input file
from the include directory list.

-ipa

The -ipa (interprocedural analysis) switch turns on Interprocedural
Analysis (IPA) in the compiler. This option enables optimization across
the entire program, including between source files that were compiled sep­arately. The -ipa option should be applied to all C and C++ files in the
program. For more information, see “Interprocedural Analysis” on

page 1-67. Specifying

(on page 1-40).

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-33
for SHARC Processors

-ipa also implies setting the -O switch

Compiler Command-Line Interface

L

-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 -l (link library) switch directs the linker to search the library for
functions and global variables when linking. The library name is the por­tion of the file name between the lib prefix and .dlb extension.

For example, the -lc compiler switch directs the linker to search in the
library named c. This library resides in a file named libc.dlb.

All object files should be listed on the command line before listing librar­ies 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 com­mand line that contains the global definition of that symbol. If two
objects on the command line contain definitions of the symbol x, x will be
taken from the left-most object on the command line that contains a glo­bal definition of x.

Invoke this switch by selecting the Interprocedural Analysis check
box in the VisualDSP++ Project Options dialog box, Compile tab,
General category.

If one of the definitions for
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.

1-34 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

x comes from user objects, and the other from

for SHARC Processors

Compiler

-M

The

-M (generate make rules only) switch directs the compiler not to com-

pile 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 depen­dencies 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 standard out a rule describing the dependencies of the main
program file. After preprocessing, compilation proceeds normally.

-Mo _filename_

The -Mo filename (preprocessor output file) switch directs the compiler
to use

filename for the output of –MD or –ED switches.

-Mt filename

The -Mt filename (output make rule for the named source) switch modi­fies the target of dependencies, renaming the target to filename. It only
has an effect when used in conjunction with the -M or -MM switch..

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-35
for SHARC Processors

Compiler Command-Line Interface

-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 notifica­tion when input files are missing.

-map filename

The -map filename (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. For example, if the argument is test, the map file
name is test.xml. The .xml extension is added where necessary.

-mem

The -mem (enable memory initialization) switch directs the compiler to
run the mem21k initializer.

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

-no-aligned-stack

-no-aligned-stack (disable stack alignment) switch directs the com-

The
piler to not align the program stack on a double-word boundary.

-no-alttok

The -no-alttok (disable alternative tokens) switch directs the compiler
not to accept alternative operator keywords and digraph sequences in the
source files. This is the default mode. For more information, see “-alttok”

on page 1-24.

1-36 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

-no-annotate

The

-no-annotate (disable assembly annotations) switch directs the com-

piler not to annotate assembly files. The default behavior is that whenever
optimizations are enabled all assembly files generated by the compiler are
annotated with information on the performance of the generated assem­bly. See “Assembly Optimizer Annotations” on page 2-51 for more details
on this feature.

-no-annotate-loop-instr

The -no-annotate-loop-instr switch disables the production of addi­tional loop annotation information by the compiler. This is the default
mode.

-no-bss

The -no-bss switch causes the compiler to keep zero-initialized and
non-zero-initialized data in the same data section, rather than separating
zero-initialized data into a different, BSS-style section. See also the -bss
switch on page 1-25.

-no-builtin

The -no-builtin (no built-in functions) switch directs the compiler to
ignore built-in functions that begin with two underscores (
this switch influences many functions. This switch also predefines the

__NO_BUILTIN preprocessor macro. For more information on built-in func-

tions, see “C++ Fractional Type Support” on page 1-146.

L

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-37
for SHARC Processors

Invoke this switch by selecting the Disable builtin functions check
box in the VisualDSP++ Project Options dialog box, Compile tab,
General category.

__). Note that

Compiler Command-Line Interface

-no-circbuf

The

-no-circbuf (no circular buffer) switch disables the automatic gener-

ation of circular buffer code by the compiler. Uses of the circindex() and

circptr() functions (that is, explicit circular buffer operations) are not

affected.

-no-db

The -no-db (no delayed branches) switch specifies that the compiler shall
not generate jumps that use delayed branches.

-no-defs

The -no-defs (disable defaults) switch directs the preprocessor not to
define any default preprocessor macros, include directories, library direc­tories, libraries, and run-time headers. It also disables the Analog Devices

cc21k C/C++ keyword extensions.

-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 standards for C and C++ lan­guages. These include keywords such as pm and dm, which may be used as
identifiers in standard conforming programs. Alternate keywords, which
are prefixed with two leading underscores, such as __pm and __dm, con­tinue to work.

-no-fp-associative

The -no-fp-associative switch directs the compiler NOT to treat
floating-point multiplication and addition as an associative.

1-38 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

Compiler

-no-mem

The

-no-mem (disable memory initialization) switch directs the compiler

not to run the mem21k initializer. Note that if you use -no-mem, the com­piler 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-simd

The -no-simd (disable SIMD mode) switch directs the compiler to disable
automatic SIMD code generation when compiling for ADSP-2116x,
ADSP-2126x and ADSP-2136x processors. Note that SIMD code is still
generated for a loop if it is preceded with the “SIMD_for” pragma. The
pragma is treated as an explicit user request to generate SIMD code and is
always obeyed, if possible. See “SIMD Support” on page 1-150 for more
information.

-no-std-ass

-no-std-ass (disable standard assertions) switch prevents the com-

The
piler from defining the standard assertions. See the -A switch
(on page 1-23) for the list of standard assertions.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-39
for SHARC Processors

Compiler Command-Line Interface

-no-std-def

The

-no-std-def (disable standard macro definitions) switch prevents the

compiler from defining default preprocessor macro definitions.

L

-no-std-inc

The -no-std-inc (disable standard include search) switch directs the
C/C++ preprocessor to search for header files in the current directory and
directories specified with the -I switch.

L

-no-std-lib

The -no-std-lib (disable standard library search) switch directs the linker
to search for libraries in only the current project directory and directories
specified with the -L switch.

-no-threads

The
piled code and libraries used in the build need not be thread-safe. This is
the default setting when the
not used.

This switch also disables the Analog Devices keyword extensions
that have no leading underscores, such as pm and dm.

You can invoke this switch by selecting the Ignore standard
include paths check box in the VisualDSP++ Project Options dia­log box, Compile tab, Preprocessor category.

-nothreads (disable thread-safe build) switch specifies that all com-

-threads (enable thread-safe build) switch is

-O[0|1]

The -O (enable optimizations) switch directs the compiler to produce code
that is optimized for performance. Optimizations are not enabled by
default for the
zation on, while setting

1-40 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

cc21k compiler. The switch setting -O or -O1 turns optimi-

-O0 turns off all optimizations.

for SHARC Processors

Compiler

L

-Oa

The -Oa (automatic function inlining) switch enables the inline expansion
of C/C++ functions, which are not necessarily declared inline in the source
code. The amount of auto-inlining the compiler performs is controlled
using the –Ov (optimize for speed versus size) switch (on page 1-41).
Therefore, use of -Ov100 indicates that as many functions as possible are
auto-inlined, whereas –Ov0 prevents any function from being auto-inlined.
Specifying -Oa also implies the use of -O.

-Og

The -Og switch enables a compiler mode that attempts to perform optimi­zations while still preserving the debugging information. It is meant as an
alternative for those who want a debuggable program but who are also
concerned about the performance of their debuggable code.

-Os

You can invoke this switch by selecting the Enable optimization
check box in the VisualDSP++ Project Options dialog box,
Compile tab, General category.

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.

-Ov num

The -Ov num (optimize for speed versus size) switch directs the compiler to
produce code that is optimized for speed versus size. The “
an integer between 0 (purely size) and 100 (purely speed).

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-41
for SHARC Processors

num” should be

Compiler Command-Line Interface

-o filename

The

-o (output file) switch directs the compiler to use filename for the

name of the final output file.

-P

The -P (omit line numbers) switch directs the compiler to stop after the
C/C++ preprocessor runs (without compiling) and to omit the #line pre­processor command with line number information from the preprocessor
output. The -C switch can be used in conjunction with -P to retain
comments.

-PP

The -PP (omit line numbers and compile) switch is similar to the -P
switch; however, it does not halt compilation after preprocessing.

-path-{ asm | compiler | lib | link | mem } directory

The -path-{asm|compiler|lib|link|mem} directory (tool location)
switch directs the compiler to use the specified component in place of the
default-installed version of the compilation tool. The component com­prises a relative or absolute path to its location. Respectively, the tools are
the assembler, compiler, librarian, linker or memory initializer. Use this
switch when overriding the normal version of one or more of the tools.
The -path-{} switch also overrides the directory specified by the

-path-install switch.

-path-install directory

The

-path-install (installation location) switch directs the compiler to

use the specified directory as the location for all compilation tools instead
of the default path. This is useful when working with multiple versions of
the tool set.

L

1-42 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

You can selectively override this switch with the -path-tool
switch.

for SHARC Processors

Compiler

-path-output directory

The

-path-output (non-temporary files location) switch directs the com-

piler to place final output files in the specified directory.

-path-temp directory

The -path-temp (temporary files location) switch directs the compiler to
place temporary files in the specified directory.

-pch

The -pch (precompiled header) switch directs the compiler to automati­cally generate and use precompiled header files. A precompiled output
header has a .pch extension attached to the source file name. By default,
all precompiled headers are stored in a directory called PCHRepository.

L

-pchdir directory

The -pchdir (locate PCHRepository) switch specifies the location of an
alternative PCHRepository for storing and invocation of precompiled
header files. If the directory does not exist, the compiler creates it. Note
that

-pedantic

The -pedantic (ANSI standard warnings) switch causes the compiler to
issue a warning for each construct found in your program that does not
strictly conform to ANSI/ISO standard C or C++.

L

Precompiled header files can significantly speed compilation; pre­compiled headers tend to occupy more disk space.

-o (output) does not influence the -pchdir option.

The compiler may not detect all such constructs. In particular, the

-pedantic switch does not cause the compiler to issue errors when

Analog Devices keyword extensions are used.

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-43
for SHARC Processors

Compiler Command-Line Interface

-pedantic-errors

The

-pedantic-errors (ANSI standard errors) switch causes the compiler

to issue errors instead of warnings for cases described in the -pedantic
switch.

-pguide

The -pguide switch causes the compiler to add instrumentation for the
gathering of a profile as the first stage of performing profile-guided
optimization.

-pplist filename

The -pplist (preprocessor listing) directs the preprocessor to output a
listing to the named file. When more than one source file is preprocessed,
the listing file contains information about the last file processed. The gen­erated file contains raw source lines, information on transitions into and
out of include files, and diagnostics generated by the compiler.

Each listing line begins with a key character that identifies its type as:

Character Meaning

N Normal line of source

X Expanded line of source

S Line of source skipped by #if or #ifdef

L

R Diagnostic message (remark)

W Diagnostic message (warning)

E Diagnostic message (error)

C Diagnostic message (catastrophic error)

Change in source position

1-44 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors

-proc processor

The

-proc processor (target processor) switch specifies the compiler pro-

duces code suitable for the specified processor. Refer to “Supported

Processors” for the list of supported SHARC processors.

For example,

cc21k -proc ADSP-21161 -o bin\p1.doj p1.asm

Compiler

L

When compiling with the -proc switch, the appropriate processor macro
as well as __ADSP21000__ are defined as 1. For example, __ADSP21060__
and __ADSP-21000__ are 1.

L

-progress-rep-func

The -progress-rep-func switch provides feedback on the compiler’s
progress that may be useful when compiling and optimizing very large
source files. It issues a “warning” message each time the compiler starts
compiling a new function. The “warning” message is a remark that is dis­abled by default, and this switch enables the remark as a warning. The
switch is equivalent to

-progress-rep-gen-opt

The
progress that may be useful when compiling and optimizing a very large,
complex function. It issues a “warning” message each time the compiler
starts a new generic optimization pass on the current function. The “warn-

If no target is specified with the -proc switch, the system uses the

ADSP-21060 processor settings as a default.

See also “-si-revision version” on page 1-49 for more information
on silicon revision of the specified processor.

-Wwarn=cc1472.

-progress-rep-gen-opt switch provides feedback on the compiler’s

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-45
for SHARC Processors

Compiler Command-Line Interface

ing” message is a remark that is disabled by default, and this switch
enables the remark as a warning. The switch is equivalent to

-Wwarn=cc1473.

-progress-rep-mc-opt

The -progress-rep-mc-opt switch provides feedback on the compiler’s
progress that may be useful when compiling and optimizing a very large,
complex function. It issues a “warning” message each time the compiler
starts a new machine-specific optimization pass on the current function.
The “warning” message is a remark that is disabled by default, and this
switch enables the remark as a warning. The switch is equivalent to

-Wwarn=cc1474.

-R directory[{:|,}directory …]

The -R directory (add source directory) switch directs the compiler to
add the specified directory to the list of directories searched for source
files. On Windows platforms, multiple source directories are given as a
colon, comma, or semicolon separated list.

The compiler searches for the source files in the order specified on the
command line. The compiler searches the specified directories before
reverting to the current project directory. The -R directory option is
position-dependent on the command line. That is, it affects only source
files that follow the option.

[

1-46 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

Source files whose file names begin with /, ./ or ../ (or Windows
equivalent) and contain drive specifiers (on Windows platforms)
are not affected by this option

for SHARC Processors

-R-

The

-R- (disable source path) switch removes all directories from the stan-

dard search path for source files, effectively disabling this feature.

Compiler

L

-reserve register[, register …]

The -reserve (reserve register) switch directs the compiler not to use the
specified registers. This guarantees that a known set of registers are avail­able for inline assembly code or linked assembly modules. Separate each
register name with a comma on the compiler command line.

You can reserve the following registers: b0, l0, m0, i0, b1, l1, m1, i1, b8,

l8, m8, i8, b9, l9, m9, i9, ustat1, and ustat2 (as well as ustat3 and ustat4

on ADSP-2116x, ADSP-2126x and ADSP-2136x processors). When
reserving an L (length) register, you must reserve the corresponding I
(index) register; reserving an L register without reserving the correspond­ing I register may result in execution problems.

-restrict-hardware-loops <maximum>

The -restrict-hardware-loops <maximum> switch restricts the level of
nested hardware loops that the compiler generates. The default setting is
6, which is the maximum number of levels that the hardware supports.

This option is position-dependent on the command line; it only
affects files following it.

-S

The -S (stop after compilation) switch directs cc21k to stop compilation
before running the assembler. The compiler outputs an assembly file
with an

L

VisualDSP++ 4.0 C/C++ Compiler and Library Manual 1-47
for SHARC Processors

.s extension.

Invoke this switch by selecting the Stop after: Compiler check box
in the VisualDSP++ Project Options dialog box, Compile tab,
General category selection.

Compiler Command-Line Interface

-s

The

-s (strip debug information) switch directs the compiler to remove

debug information (symbol table and other items) from the output execut­able file during linking.

-save-temps

The -save-temps (save intermediate files) switch directs the compiler not
to discard intermediate files. The compiler places the intermediate output
(*.i, *.is, *.s, *.doj) files in the temp subdirectory of the current
project directory. See Table 1-2 on page 1-8 for a list of intermediate files.

-section <id>=<section_name>[,<id>=section_name>]

The -section switch controls the placement of types of data produced by
the compiler. The data is placed into the section “section_name” as speci­fied on the command line.

The compiler currently supports the following section identifiers:

vtbl — controls placement of the C++ virtual lookup tables
switch — controls placement of tables used in the implementation of

switch statements

Make sure that the section selected via the command line exists within the

.LDF file (refer to the Linker chapter in the VisualDSP++ 4.0 Linker and

Utilities manual).

-show

The -show (display command line) switch directs the compiler to display
the command-line arguments passed to the driver, including expanded
option files and environment variables. This option allows you to ensure
that command-line options have been successfully invoked by the driver.

1-48 VisualDSP++ 4.0 C/C++ Compiler and Library Manual

for SHARC Processors