W3.5
C Compiler and Library
Manual for ADSP-218x DSPs
Analog Devices, Inc.
One Technology Way
Norwood, Mass. 02062-9106
Revision 4.1, October 2003
Part Number:
82-000400-03
Copyright Information
© 2003 Analog Devices, Inc., ALL RIGHTS RESERVED. This document may not be reproduced in any form without prior, express written
consent from Analog Devices, Inc.
Disclaimer
Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by implication or otherwise under the patent rights of Analog Devices, Inc.
Trademark and Service Mark Notice
The Analog Devices logo, VisualDSP++, and the VisualDSP++ logo are
registered trademarks of Analog Devices, Inc.
All other brand and product names are trademarks or service marks of
their respective owners.
CONTENTS
CONTENTS
PREFACE
Purpose ......................................................................................... xxv
Intended Audience ........................................................................ xxv
Manual Contents Description ...................................................... xxvi
What’s New in this Manual .......................................................... xxvi
Technical or Customer Support ................................................... xxvii
Supported Processors ................................................................... xxvii
Product Information .................................................................. xxviii
MyAnalog.com ..................................................................... xxviii
DSP Product Information ..................................................... xxviii
Related Documents ................................................................ xxix
Online Technical Documentation ............................................ xxx
From VisualDSP++ ............................................................. xxx
From Windows .................................................................. xxxi
From the Web .................................................................... xxxi
Printed Manuals .................................................................... xxxii
VisualDSP++ Documentation Set ...................................... xxxii
VisualDSP 3.5 C Compiler and Library Manual iii
for ADSP-218x DSPs
CONTENTS
Hardware Manuals ........................................................... xxxii
Datasheets ........................................................................ xxxii
Contacting DSP Publications ............................................... xxxiii
Notation Conventions ............................................................... xxxiii
COMPILER
C Compiler Overview ................................................................... 1-2
Standard Conformance ............................................................ 1-3
Compiler Command-Line Reference ............................................. 1-6
Running the Compiler ............................................................ 1-7
Specifying Compiler Options in VisualDSP++ ....................... 1-10
Compiler Command-Line Switches ....................................... 1-11
-@ filename ...................................................................... 1-18
-A name(tokens) ............................................................... 1-18
-alttok .............................................................................. 1-19
-bss .................................................................................. 1-19
-build-lib .......................................................................... 1-20
-C .................................................................................... 1-20
-c ..................................................................................... 1-20
-const-read-write .............................................................. 1-20
-Dmacro [=definition] ...................................................... 1-20
-debug-types <file.h> ........................................................ 1-21
-default-linkage-{asm|C} ................................................... 1-21
-dry .................................................................................. 1-22
-dryrun ............................................................................ 1-22
iv VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
-E ..................................................................................... 1-22
-ED .................................................................................. 1-22
-EE ................................................................................... 1-22
-extra-keywords ................................................................. 1-22
-flags-{asm|compiler|lib|link|mem} switch [,switch2 [,...]] .. 1-23
-fp-associative ................................................................... 1-23
-full-version ...................................................................... 1-23
-g ..................................................................................... 1-23
-H .................................................................................... 1-24
-HH ................................................................................. 1-24
-h[elp] .............................................................................. 1-24
-I- ..................................................................................... 1-25
-I directory [{,|;} directory...] ............................................. 1-25
-include filename .............................................................. 1-25
-ipa ................................................................................... 1-26
-jump-{dm|pm|same} ........................................................ 1-26
-L directory [{,|;} directory...] ............................................ 1-27
-l library ........................................................................... 1-27
-M .................................................................................... 1-27
-MD ................................................................................. 1-28
-MM ................................................................................ 1-28
-Mo filename .................................................................... 1-28
-Mt filename ..................................................................... 1-28
-MQ ................................................................................. 1-28
VisualDSP 3.5 C Compiler and Library Manual v
for ADSP-218x DSPs
CONTENTS
-make-autostatic ............................................................... 1-29
-map filename .................................................................. 1-29
-mem ............................................................................... 1-29
-no-alttok ......................................................................... 1-29
-no-bss ............................................................................. 1-30
-no-builtin ....................................................................... 1-30
-no-defs ............................................................................ 1-30
-no-extra-keywords ........................................................... 1-30
-no-fp-associative .............................................................. 1-31
-no-mem .......................................................................... 1-31
-no-std-ass ........................................................................ 1-31
-no-std-def ....................................................................... 1-31
-no-std-inc ....................................................................... 1-31
-no-std-lib ........................................................................ 1-32
-no-widen-muls ................................................................ 1-32
-O .................................................................................... 1-32
-Oa .................................................................................. 1-33
-Os .................................................................................. 1-33
-Ov num .......................................................................... 1-33
-o filename ....................................................................... 1-33
-P ..................................................................................... 1-34
-PP .................................................................................. 1-34
-path-{asm|compiler|def|lib|link|mem} filename ................. 1-34
-path-install directory ....................................................... 1-34
vi VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
-path-output directory ...................................................... 1-35
-path-temp directory ......................................................... 1-35
-pch .................................................................................. 1-35
-pch directory ................................................................... 1-35
-pedantic .......................................................................... 1-35
-pedantic-errors ................................................................ 1-36
-pplist filename ................................................................. 1-36
-proc processor .................................................................. 1-36
-R directory [{;|,}directory …] ........................................... 1-37
-R- ................................................................................... 1-38
-reserve register[,register...] ................................................ 1-38
-S ..................................................................................... 1-38
-s ...................................................................................... 1-39
-save-temps ....................................................................... 1-39
-show ................................................................................ 1-39
-si-revision version ............................................................ 1-39
-signed-bitfield .................................................................. 1-40
-signed-char ...................................................................... 1-40
-syntax-only ...................................................................... 1-40
-sysdefs ............................................................................. 1-41
-T filename ....................................................................... 1-41
-time ................................................................................ 1-41
-Umacro ........................................................................... 1-42
-unsigned-bitfield .............................................................. 1-42
VisualDSP 3.5 C Compiler and Library Manual vii
for ADSP-218x DSPs
CONTENTS
-unsigned-char .................................................................. 1-43
-v ..................................................................................... 1-43
-val-global <name-list> ..................................................... 1-43
-verbose ............................................................................ 1-43
-version ............................................................................ 1-43
-Wdriver-limit number ..................................................... 1-44
-Werror-limit number ....................................................... 1-44
-W{error|remark|suppress|warn} <num>[,num...] ............... 1-44
-Wremarks ........................................................................ 1-44
-Wterse ............................................................................ 1-45
-w .................................................................................... 1-45
-warn-protos ..................................................................... 1-45
-write-files ........................................................................ 1-45
-write-opts ........................................................................ 1-45
-xref <file> ........................................................................ 1-46
Data Type Sizes ..................................................................... 1-47
Optimization Control ........................................................... 1-49
Interprocedural Analysis ................................................... 1-50
C Compiler Language Extensions ................................................ 1-52
Inline Function Support Keyword (inline) ............................. 1-55
Inline Assembly Language Support Keyword (asm) ................ 1-56
Assembly Construct Template ........................................... 1-57
ASM() Construct Syntax: .............................................. 1-57
ASM() Construct Syntax Rules ...................................... 1-59
viii VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
ASM() Construct Template Example ............................. 1-60
Assembly Construct Operand Description ......................... 1-61
Assembly Constructs With Multiple Instructions ............... 1-67
Assembly Construct Reordering and Optimization ............. 1-67
Assembly Constructs with Input and Output Operands ..... 1-68
Assembly Constructs and Macros ...................................... 1-70
Assembly Constructs and Flow Control ............................. 1-70
Dual Memory Support Keywords (pm dm) ............................ 1-71
Memory Keywords and Assignments/Type Conversions ...... 1-73
Memory Keywords and Function Declarations/Pointers ..... 1-74
Memory Keywords and Function Arguments ..................... 1-75
Memory Keywords and Macros ......................................... 1-75
PM and DM Compiler Support for Standard C Library Functions
1-76
Placement Support Keyword (section) .................................... 1-76
Boolean Type Support Keywords (bool, true, false) ................. 1-77
Pointer Class Support Keyword (restrict) ................................ 1-77
Variable-Length Array Support .............................................. 1-78
Non-Constant Aggregate Initializer Support ........................... 1-80
Indexed Initializer Support .................................................... 1-80
Aggregate Constructor Expression Support ............................. 1-82
Preprocessor-Generated Warnings .......................................... 1-83
C++-Style Comments ............................................................ 1-83
Compiler Built-in Functions .................................................. 1-83
I/O Space for Read/Write .................................................. 1-84
VisualDSP 3.5 C Compiler and Library Manual ix
for ADSP-218x DSPs
CONTENTS
Read/Write of Non-Memory-Mapped Registers ................. 1-85
Interrupt Control ............................................................. 1-85
ETSI Support ....................................................................... 1-86
ETSI Support Overview .................................................... 1-86
Calling ETSI Library Functions ........................................ 1-88
Using the ETSI Built-In Functions .................................... 1-89
Linking ETSI Library Functions ....................................... 1-89
Working with ETSI Library Source Code .......................... 1-90
ETSI Support for Data Types ............................................ 1-90
ETSI Header File .............................................................. 1-91
Pragmas ................................................................................ 1-99
Data Alignment Pragmas ................................................ 1-101
#pragma align (num) .................................................. 1-101
#pragma pad (alignopt) ............................................... 1-102
Interrupt Handler Pragmas ............................................. 1-102
#pragma interrupt ...................................................... 1-102
#pragma altregisters .................................................... 1-103
Loop Optimization Pragmas ........................................... 1-103
#pragma loop_count(min, max, modulo) .................... 1-104
#pragma vector_for ..................................................... 1-104
#pragma no_alias ........................................................ 1-105
General Optimization Pragmas ....................................... 1-105
Linking Control Pragmas ................................................ 1-106
#pragma linkage_name identifier ................................ 1-107
x VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
#pragma retain_name ................................................. 1-107
#pragma weak_entry .................................................. 1-108
Stack Usage Pragma ........................................................ 1-108
#pragma make_auto_static .......................................... 1-108
Function Side-Effect Pragmas .......................................... 1-109
#pragma alloc .............................................................. 1-109
#pragma pure .............................................................. 1-110
#pragma const ............................................................. 1-110
#pragma regs_clobbered string ..................................... 1-111
#pragma result_alignment (n) ...................................... 1-114
Header File Control Pragmas ........................................... 1-115
#pragma hdrstop ......................................................... 1-115
#pragma no_pch ......................................................... 1-116
#pragma once ............................................................. 1-116
#pragma system_header ............................................... 1-116
GCC Compatibility Extensions ........................................... 1-117
Statement Expressions ..................................................... 1-117
Type Reference Support Keyword (typeof) ....................... 1-118
GCC Generalized Lvalues ............................................... 1-119
Conditional Expressions with Missing Operands .............. 1-120
Hexadecimal Floating-Point Numbers ............................. 1-120
Zero Length Arrays ......................................................... 1-121
Variable Argument Macros .............................................. 1-121
Line Breaks in String Literals ........................................... 1-121
VisualDSP 3.5 C Compiler and Library Manual xi
for ADSP-218x DSPs
CONTENTS
Arithmetic on Pointers to Void and Pointers to Functions 1-122
Cast to Union ................................................................. 1-122
Ranges in Case Labels ..................................................... 1-122
Declarations mixed with Code ........................................ 1-122
Escape Character Constant ............................................. 1-123
Alignment Inquiry Keyword (__alignof__) ...................... 1-123
Keyword for Specifying Names in Generated Assembler (asm) 1-123
Function, Variable and Type Attribute Keyword (__attribute__)
1-124
Preprocessor Features ................................................................ 1-125
Predefined Preprocessor Macros ........................................... 1-125
__ADSP21XX__ and __ADSP218X__ ........................... 1-126
__ADSP21{81|83|84|85|86|87|88|89}__ ......................... 1-126
__ANALOG_EXTENSIONS__ ..................................... 1-126
__DATE__ .................................................................... 1-126
__DOUBLES_ARE_FLOATS__ .................................... 1-126
__ECC__ ....................................................................... 1-126
__EDG__ ...................................................................... 1-126
__EDG_VERSION__ .................................................... 1-127
__FILE__ ....................................................................... 1-127
_LANGUAGE_C ........................................................... 1-127
__LINE__ ...................................................................... 1-127
__NO_BUILTIN ........................................................... 1-127
__NO_LONG_LONG .................................................. 1-127
__SIGNED_CHARS__ .................................................. 1-127
xii VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
__STDC__ ..................................................................... 1-128
__STDC_VERSION__ .................................................. 1-128
__TIME__ ..................................................................... 1-128
__VERSION__ .............................................................. 1-128
Header Files ........................................................................ 1-128
Writing Preprocessor Macros ................................................ 1-129
Preprocessing of .IDL Files .................................................. 1-131
C Run-Time Model and Environment ....................................... 1-132
Using the Run-Time Header ................................................ 1-133
Interrupt Table and Interface ............................................... 1-133
Autobuffering Support ......................................................... 1-134
Stack Frame ......................................................................... 1-136
Stack Frame Description ................................................. 1-137
General System-Wide Specifications ................................ 1-138
At a procedure call, the following must be true: ............ 1-139
At an interrupt, the following must be true: ................. 1-139
Return Values ................................................................. 1-139
Procedure Call and Return .............................................. 1-140
On Entry: ................................................................... 1-140
To Return from a Procedure: ....................................... 1-140
File I/O Support .................................................................. 1-141
Extending I/O Support To New Devices .......................... 1-141
Miscellaneous Information ................................................... 1-143
Register Classification .......................................................... 1-144
VisualDSP 3.5 C Compiler and Library Manual xiii
for ADSP-218x DSPs
CONTENTS
Callee Preserved Registers (“Preserved”) .......................... 1-144
Dedicated Registers ........................................................ 1-144
Caller Save Registers (“Scratch”) ..................................... 1-144
Circular Buffer Length Registers ..................................... 1-144
Mode Status (MSTAT) Register ...................................... 1-145
Complete List of Registers ................................................... 1-145
C and Assembly Language Interface .......................................... 1-148
Calling Assembly Subroutines from C Programs ................... 1-148
Calling C Routines from Assemby Programs ........................ 1-151
Using Mixed C/Assembly Support Macros ....................... 1-152
function_entry ........................................................... 1-153
exit ............................................................................. 1-153
leaf_entry ................................................................... 1-153
leaf_exit ..................................................................... 1-153
alter(x) ....................................................................... 1-153
save_reg ...................................................................... 1-154
restore_reg .................................................................. 1-154
readsfirst(register) ....................................................... 1-154
register = readsnext ..................................................... 1-154
putsfirst = register ....................................................... 1-154
putsnext = register ...................................................... 1-155
getsfirst(register) ......................................................... 1-155
register = getsnext ....................................................... 1-155
Using Mixed C/Assembly Naming Conventions ................... 1-155
xiv VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
Compatibility Call ............................................................... 1-156
ACHIEVING OPTIMAL PERFORMANCE FROM 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-4
Using Interprocedural Optimization .................................... 2-5
Data Types .............................................................................. 2-7
Avoiding Emulated Arithmetic ............................................ 2-8
Getting the Most from IPA ...................................................... 2-9
Initializing Constants Statically ........................................... 2-9
Avoiding Aliases ................................................................ 2-10
Indexed Arrays vs. Pointers .................................................... 2-12
Trying Pointer and Indexed Styles ...................................... 2-13
Function Inlining .................................................................. 2-13
Using Inline asm Statements .................................................. 2-14
Memory Usage ...................................................................... 2-15
Loop Guidelines ......................................................................... 2-17
Keeping Loops Short ............................................................. 2-17
Avoiding Unrolling Loops ...................................................... 2-17
Avoiding Loop Rotation by Hand .......................................... 2-18
Avoiding Array Writes in Loops ............................................. 2-19
Inner Loops vs. Outer Loops ................................................. 2-19
VisualDSP 3.5 C Compiler and Library Manual xv
for ADSP-218x DSPs
CONTENTS
Avoiding Conditional Code in Loops ..................................... 2-20
Avoiding Placing Function Calls in Loops .............................. 2-21
Avoiding Non-Unit Strides ................................................... 2-21
Loop Control ........................................................................ 2-21
Using the Restrict Qualifier ................................................... 2-22
Using the Const Qualifier ..................................................... 2-23
Using Built-in Functions in Code Optimization .......................... 2-24
Fractional Data ..................................................................... 2-24
System Support Built-in Functions ........................................ 2-25
Smaller Applications: Optimizing for Code Size .......................... 2-27
Pragmas ...................................................................................... 2-29
Function Pragmas ................................................................. 2-29
#pragma const .................................................................. 2-29
#pragma pure ................................................................... 2-30
#pragma alloc ................................................................... 2-30
#pragma regs_clobbered .................................................... 2-31
#pragma optimize_{off|for_speed|for_space|as_cmd_line} .. 2-33
Loop Optimization Pragmas .................................................. 2-33
#pragma loop_count ......................................................... 2-33
#pragma no_alias .............................................................. 2-34
Useful Optimization Switches ..................................................... 2-35
C RUN-TIME LIBRARY
C Run-Time Library Guide .......................................................... 3-2
Calling Library Functions ........................................................ 3-2
xvi VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
Using the Compiler’s Built-In Functions .................................. 3-2
Linking Library Functions ....................................................... 3-3
Working With Library Source Code ......................................... 3-4
Working with Library Header Files .......................................... 3-5
assert.h ............................................................................... 3-6
ctype.h ............................................................................... 3-6
def2181.h – Memory Map Definitions ................................ 3-7
def2181x.h – Memory Map Definitions ............................... 3-7
errno.h ............................................................................... 3-7
ffts.h – Fast Fourier Transforms ........................................... 3-7
filters.h – DSP Filters .......................................................... 3-8
float.h – Floating Point ....................................................... 3-8
fract.h – ADSP-218x DSP Macro Fract Definitions ............. 3-8
iso646.h ............................................................................. 3-8
locale.h ............................................................................... 3-9
math.h ................................................................................ 3-9
misc.h – ADSP-218x DSP Timer Functions ....................... 3-10
setjmp.h ............................................................................ 3-10
signal.h ............................................................................. 3-10
sport.h – ADSP-218x DSP Serial Ports .............................. 3-11
stdarg.h ............................................................................ 3-11
stdio.h .............................................................................. 3-11
stdlib.h ............................................................................. 3-12
string.h ............................................................................. 3-12
VisualDSP 3.5 C Compiler and Library Manual xvii
for ADSP-218x DSPs
CONTENTS
sysreg.h ............................................................................ 3-13
Documented Library Functions .................................................. 3-14
C Run-Time Library Reference ................................................... 3-18
Notation Conventions ........................................................... 3-18
Reference Format .................................................................. 3-18
abort .......................................................................................... 3-19
abs ............................................................................................. 3-20
acos ............................................................................................ 3-21
asin ............................................................................................ 3-22
atan ............................................................................................ 3-23
atan2 .......................................................................................... 3-24
atexit .......................................................................................... 3-25
atof ............................................................................................ 3-26
atoi ............................................................................................ 3-29
atol ............................................................................................ 3-30
biquad ........................................................................................ 3-31
bsearch ....................................................................................... 3-34
calloc ......................................................................................... 3-36
ceil ............................................................................................. 3-37
clear_interrupt ............................................................................ 3-38
copysign ..................................................................................... 3-40
cos ............................................................................................. 3-41
cosh ........................................................................................... 3-44
cot ............................................................................................. 3-45
xviii VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
demean_buffer ........................................................................... 3-46
disable_interrupts ....................................................................... 3-48
div ............................................................................................. 3-49
enable_interrupts ........................................................................ 3-50
exit ............................................................................................. 3-51
exp ............................................................................................. 3-52
fabs ............................................................................................ 3-53
fftN ........................................................................................... 3-54
fir .............................................................................................. 3-57
floor ........................................................................................... 3-59
fmod .......................................................................................... 3-60
free ............................................................................................ 3-61
frexp .......................................................................................... 3-62
ifftN .......................................................................................... 3-63
iir ............................................................................................... 3-66
interrupt .................................................................................... 3-71
io_space_read ............................................................................. 3-75
io_space_write ............................................................................ 3-77
isalnum ...................................................................................... 3-79
isalpha ........................................................................................ 3-80
iscntrl ......................................................................................... 3-81
isdigit ......................................................................................... 3-82
isgraph ....................................................................................... 3-83
isinf ........................................................................................... 3-84
xix VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
CONTENTS
islower ........................................................................................ 3-86
isnan .......................................................................................... 3-87
isprint ........................................................................................ 3-89
ispunct ....................................................................................... 3-90
isspace ........................................................................................ 3-91
isupper ....................................................................................... 3-92
isxdigit ....................................................................................... 3-93
labs ............................................................................................ 3-94
ldexp .......................................................................................... 3-95
ldiv ............................................................................................ 3-96
log ............................................................................................. 3-97
log10 .......................................................................................... 3-98
longjmp ..................................................................................... 3-99
malloc ...................................................................................... 3-101
memchr .................................................................................... 3-102
memcmp .................................................................................. 3-103
memcpy ................................................................................... 3-104
memmove ................................................................................ 3-105
memset .................................................................................... 3-106
modf ........................................................................................ 3-107
pow .......................................................................................... 3-108
qsort ........................................................................................ 3-109
raise ......................................................................................... 3-111
rand ......................................................................................... 3-113
xx VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
realloc ....................................................................................... 3-114
setjmp ...................................................................................... 3-115
signal ........................................................................................ 3-116
sin ............................................................................................ 3-120
sinh .......................................................................................... 3-122
sqrt ........................................................................................... 3-123
srand ........................................................................................ 3-124
strcat ........................................................................................ 3-125
strchr ........................................................................................ 3-126
strcmp ...................................................................................... 3-127
strcoll ....................................................................................... 3-128
strcpy ....................................................................................... 3-129
strcspn ...................................................................................... 3-130
strerror ..................................................................................... 3-131
strlen ........................................................................................ 3-132
strncat ...................................................................................... 3-133
strncmp .................................................................................... 3-134
strncpy ..................................................................................... 3-135
strpbrk ...................................................................................... 3-136
strrchr ....................................................................................... 3-137
strspn ....................................................................................... 3-138
strstr ......................................................................................... 3-139
strtod ........................................................................................ 3-140
strtodf ...................................................................................... 3-143
VisualDSP++ 3.5 C Compiler and Library Manual for ADSP-218x DSPs xxi
strtok ....................................................................................... 3-146
strtol ........................................................................................ 3-148
strtoul ...................................................................................... 3-150
strxfrm ..................................................................................... 3-152
sysreg_read ............................................................................... 3-154
sysreg_write .............................................................................. 3-156
tan ........................................................................................... 3-158
tanh ......................................................................................... 3-159
timer_off .................................................................................. 3-160
timer_on .................................................................................. 3-161
timer_set .................................................................................. 3-162
tolower ..................................................................................... 3-163
toupper .................................................................................... 3-164
va_arg ...................................................................................... 3-165
va_end ..................................................................................... 3-168
va_start .................................................................................... 3-169
COMPILER LEGACY SUPPORT
Tools Differences .......................................................................... A-1
C Compiler and C Run-Time Library ...................................... A-3
Segment Placement Support Keyword Changed to Section ... A-3
G21 Compatibility Call ...................................................... A-3
Support for G21-Based Options and Extensions .................. A-3
Indexed Initializers ............................................................. A-4
Compiler Diagnostics ......................................................... A-4
xxii VisualDSP++ 3.5 C Compiler and Library Manual for ADSP-218x DSPs
INDEX
ANSI C Extensions ............................................................ A-4
Compiler Switch Modifications .......................................... A-5
Warnings ........................................................................... A-7
Run-Time Model ............................................................... A-8
VisualDSP++ 3.5 C Compiler and Library Manual for ADSP-218x DSPs xxiii
xxiv VisualDSP++ 3.5 C Compiler and Library Manual for ADSP-218x DSPs
PREFACE
Thank you for purchasing Analog Devices development software for digital signal processors (DSPs).
Purpose
The VisualDSP++ 3.5 C Compiler and Library Manual for ADSP-218x
DSPs contains information about the C compiler and run-time library for
ADSP-218x DSPs. It includes syntax for command lines, switches, and
language extensions. It leads you through the process of using library routines and writing mixed C/assembly code.
Intended Audience
The primary audience for this manual is programmers who are familiar
with Analog Devices DSPs. This manual assumes that the audience has a
working knowledge of the ADSP-218x DSP architecture and instruction
set and the C programming language.
Programmers who are unfamiliar with ADSP-218x DSPs can use this
manual, but they should supplement it with other texts (such as the
appropriate hardware reference and instruction set reference) that provide
information about your ADSP-218x DSP architecture and instructions).
VisualDSP 3.5 C Compiler and Library Manual xxv
for ADSP-218x DSPs
Manual Contents Description
Manual Contents Description
This manual contains:
• Chapter 1, “Compiler”
Provides information on compiler options, language extensions and
C/assembly interfacing
• Chapter 2, “Achieving Optimal Performance from C Source Code”
Shows how to optimize compiler operation.
• Chapter 3, “C Run-Time Library”
Shows how to use library functions and provides a complete C
library function reference
•Appendix A, “Compiler Legacy Support”
Describes support for legacy code that was developed with previous
releases of the development tools.
What’s New in this Manual
This edition of the VisualDSP++ 3.5 C Compiler and Library Manual for
ADSP-218x DSPs documents support for all ADSP-218x processors.
Refer to VisualDSP++ 3.5 Product Bulletin for 16-Bit Processors for information on all new and updated features and other release information.
xxvi VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Technical or Customer Support
You can reach DSP Tools Support in the following ways:
• Visit the DSP Development Tools website at
www.analog.com/technology/dsp/developmentTools/index.html
• Email questions to
dsptools.support@analog.com
• Phone questions to 1-800-ANALOGD
• Contact your ADI 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
Preface
Supported Processors
The name “ADSP-218x” refers to a family of Analog Devices 16-bit,
fixed-point processors. VisualDSP++ currently supports the following
ADSP-218x processors:
ADSP-2181, ADSP-2183, ADSP-2184, ADSP-2185, ADSP-2186,
ADSP-2187, ADSP-2188, and ADSP-2189M
VisualDSP 3.5 C Compiler and Library Manual xxvii
for ADSP-218x DSPs
Product Information
Product Information
You can obtain product information from the Analog Devices website,
from the product CD-ROM, or from the printed publications (manuals).
Analog Devices is online at www.analog.com. Our website provides information 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 website that allows
customization of a webpage to display only the latest information on
products you are interested in. You can also choose to receive weekly email
notification containing updates to the webpages that meet your interests.
MyAnalog.com provides access to books, application notes, data sheets,
code examples, and more.
Registration:
Visit www.myanalog.com to sign up. Click Register to use MyAnalog.com.
Registration takes about five minutes and allows you to select the information you want to receive.
If you are already a registered user, just log on. Your user name is your
email address.
DSP Product Information
For information on digital signal processors, visit our website at
www.analog.com, which provides access to technical publications,
datasheets, application notes, product overviews, and product
announcements.
xxviii VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Preface
You may also obtain additional information about Analog Devices and its
products in any of the following ways.
• Email questions or requests for information to
dsp.support@analog.com
• Fax questions or requests for information to
1-781-461-3010 (North America)
089/76 903-557 (Europe)
• Access the Digital Signal Processing Division’s FTP website at
ftp ftp.analog.com or ftp 137.71.23.21
ftp://ftp.analog.com
Related Documents
For information on product related development software, see the following publications:
VisualDSP++ 3.5 Getting Started Guide for 16-Bit Processors
VisualDSP++ 3.5 User’s Guide for 16-Bit Processors
VisualDSP++ 3.5 Assembler and Preprocessor Manual for ADSP-218x and ADSP-219x DSPs
VisualDSP++ 3.5 Linker and Utilities Manual for 16-Bit Processors
VisualDSP++ 3.5 Loader Manual for 16-Bit Processors
VisualDSP++ 3.5 Product Bulletin 16-Bit Processors
VisualDSP++ Kernel (VDK) User’s Guide
VisualDSP++ Component Software Engineering User’s Guide
Quick Installation Reference Card
For hardware information, refer to the processor’s Hardware Reference
Manual and Instruction Set Reference Manual.
VisualDSP 3.5 C Compiler and Library Manual xxix
for ADSP-218x DSPs
Product Information
Online Technical Documentation
Online documentation comprises VisualDSP++ Help system and tools
manuals, and FlexLM network license manager software documentation.
You can easily search across the entire VisualDSP++ documentation set for
any topic of interest. For easy printing, supplementary PDF files for the
tools manuals are also provided.
If documentation is not installed on your system as part of the software
installation, you can add it from the VisualDSP++ CD-ROM at any time.
Access the online documentation from the VisualDSP++ environment,
Windows Explorer, or Analog Devices website.
A description of each documentation file type is as follows.
File Description
.CHM Help system files and VisualDSP++ tools manuals.
.HTM or .HTML FlexLM network license manager software documentation. Viewing and
printing the .
higher).
PDF VisualDSP++ tools manuals in Portable Documentation Format, one .PDF
.
file for each manual. Viewing and printing the .
reader, such as Adobe Acrobat Reader 4.0 (or higher).
HTML files require a browser, such as Internet Explorer 4.0 (or
PDF files require a PDF
From VisualDSP++
Access VisualDSP++ online Help from the Help menu’s Contents,
Search, and Index commands.
Open online Help from context-sensitive user interface items (toolbar
buttons, menu commands, and windows).
xxx VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Preface
From Windows
In addition to any shortcuts you may have constructed, there are many
ways to open VisualDSP++ online Help or the supplementary documentation from Windows.
Help system files (
.CHM files) are located in the Help folder, and .PDF files
are located in the Docs folder of your VisualDSP++ installation. The Docs
folder also contains the FlexLM network license manager software
documentation.
Using Windows Explorer
• Double-click any file that is part of the VisualDSP++ documentation set.
• Double-click the vdsp-help.chm file, which is the master Help system, to access all the other .CHM files.
Using the Windows Start Button
• Access the VisualDSP++ online Help by clicking the Start button
and choosing Programs, Analog Devices, VisualDSP++, and
VisualDSP++ Documentation.
• Access the .PDF files by clicking the Start button and choosing
Programs, Analog Devices, VisualDSP++, Documentation for
Printing, and the name of the book.
From the Web
To download the tools manuals, point your browser at
http://www.analog.com/technology/dsp/developmentTools/gen_purpose.html
Select a DSP family and book title. Download archive (.ZIP) files, one for
each manual. Use any archive management software, such as WinZip, to
decompress downloaded files.
VisualDSP 3.5 C Compiler and Library Manual xxxi
for ADSP-218x DSPs
Product Information
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
VisualDSP++ manuals may be purchased through Analog Devices Customer Service at 1-781-329-4700; ask for a Customer Service
representative. The manuals can be purchased only as a kit. For additional
information, call 1-603-883-2430.
If you do not have an account with Analog Devices, you will be referred to
Analog Devices distributors. To obtain information on our distributors,
log onto
Hardware Manuals
http://www.analog.com/salesdir/continent.asp.
Hardware reference and instruction set reference manuals can be ordered
through the Literature Center or downloaded from the Analog Devices
website. The phone number is 1-800-ANALOGD (1-800-262-5643).
The manuals can be ordered by a title or by product number located on
the back cover of each manual.
Datasheets
All data sheets can be downloaded from the Analog Devices website. As a
general rule, any data sheet with a letter suffix (L, M, N) can be obtained
from the Literature Center at 1-800-ANALOGD (1-800-262-5643) or
downloaded from the website. Data sheets without the suffix can be
downloaded from the website only—no hard copies are available. You can
ask for the data sheet by a part name or by product number.
xxxii VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Preface
If you want to have a data sheet faxed to you, call 1-800-446-6212.
Follow the prompts and a list of data sheet code numbers will be faxed to
you. Call the Literature Center first to find out if requested datasheets are
available.
Contacting DSP Publications
Please send your comments and recommendation on how to improve our
manuals and online Help. You can contact us @
dsp.techpubs@analog.com
Notation Conventions
The following table identifies and describes text conventions used in this
manual. Additional conventions, which apply only to specific chapters,
may appear throughout this document.
.
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.
Tex t i n bold style indicates 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
that.
rated by vertical bars; read the example as an optional
delimited by commas and terminated with an ellipsis; read the example
as an optional comma-separated list of
letter gothic font.
this.
this or
this or that.
VisualDSP 3.5 C Compiler and Library Manual xxxiii
for ADSP-218x DSPs
Notation Conventions
Example Description
A note, providing information of special interest or identifying a
related topic. In the online version of this book, the word Note appears
instead of this symbol.
A caution, providing information about critical design or programming issues that influence operation of a product. In the online version
of this book, the word Caution appears instead of this symbol.
xxxiv VisualDSP 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
1 COMPILER
The C compiler (cc218x) is part of Analog Devices development software
for ADSP-218x DSPs.
This chapter contains:
• “C Compiler Overview” on page 1-2
Provides an overview of C compiler for ADSP-218x DSPs.
• “Compiler Command-Line Reference” on page 1-6
Describes the operation of the compiler as it processes programs,
including input and output files, and command-line switches.
• “C Compiler Language Extensions” on page 1-52
Describes the cc218x compiler’s extensions to the ISO/ANSI standard for the C language.
• “Preprocessor Features” on page 1-125
Contains information on the preprocessor and ways to modify
source compilation.
• “C Run-Time Model and Environment” on page 1-132
Contains reference information about implementation of C programs, data, and function calls in ADSP-218x DSPs.
• “C and Assembly Language Interface” on page 1-148
Describes how to call an assembly language subroutine from C program, and how to call a C function from within an assembly
language program.
VisualDSP++ 3.5 C Compiler and Library Manual 1-1
for ADSP-218x DSPs
C Compiler Overview
C Compiler Overview
The C compiler (cc218x) is designed to aid your DSP project develop-
ment efforts by:
• Processing C source files, producing machine level versions of the
source code and object files
• Providing relocatable code and debugging information within the
object files
• Providing relocatable data and program memory segments for
placement by the linker in the processors’ memory
Using C, 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 DSP operations without having to understand the underlying DSP architecture.
The C compiler (cc218x) compiles ISO/ANSI standard C code for the
ADSP-218x DSPs. Additionally, Analog Devices includes within the compiler a number of C language extensions designed to assist in DSP
development. The cc218x compiler runs from the VisualDSP++ environ-
ment or from an operating system command line.
The C compiler (
cc218x) processes your C language source files and pro-
duces ADSP-218x DSP’s assembler source files. The assembler source files
are assembled by the ADSP-218x assembler (easm218x). The assembler
creates Executable and Linkable Format (ELF) object files that can either
be linked (using the linker) to create an ADSP-218x executable file or
included in an archive library (using
elfar). The way in which the com-
piler controls the assemble, link, and archive phases of the process depends
on the source input files and the compiler options used.
Source files contain C programs to be processed by the compiler. The
compiler takes these source files for preprocessing first. Preprocessed
source files are assembled by the ADSP-218x DSP assembler (
easm218x).
1-2 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
The assembler creates Executable and Linkable Format object files that
can either be linked (using the linker) to create an ADSP-218x executable
file
The
cc218x compiler supports the ANSI/ISO standard definitions of the
C language. For information on these standards, see any of the many reference texts on the C language. In addition to ANSI standards, the
compiler supports a set of C-language extensions. These extensions support hardware features of the ADSP-218x DSPs. For information on these
extensions, see “C Compiler Language Extensions” on page 1-52.
Compiler options are set in the VisualDSP++ Integrated Development
and Debug Environment (IDDE) from the Compile page of the Project
Options dialog box (see “Specifying Compiler Options in VisualDSP++”
on page 1-10). The selections control how the compiler processes your
source files, letting you select features that include the language dialect,
error reporting, and debugger output.
For more information on the VisualDSP++ environment, see the
VisualDSP++ 3.5 User’s Guide for ADSP-21xx DSPs and online Help.
Standard Conformance
Analog C compilers conform to the ISO/IEC 998:1990 C standard with a
small number of currently unsupported features or areas of divergence.
Unsupported features are:
• ANSI features that require operating-system support are generally
not supported. This includes time.h functionality in C.
•The
VisualDSP++ 3.5 C Compiler and Library Manual 1-3
for ADSP-218x DSPs
cc218x compiler does not provide comprehensive support of
NaN's, overflow and underflow conditions in their compiler support floating-point routines.
C Compiler Overview
Areas of divergence from Standard:
•The
double type is defined in terms of a single precision 32-bit
floats, not double precision 64-bit floats.
•The cc218x compiler makes use of the DSP’s double word (long)
MAC instruction results to avoid having to explicitly promote integer operand multiplication to long. If the integer multiplication
result overflows the integer type, then the result is not truncated
as would be the case in strict ANSI terms. This behavior is disabled
using the “-no-widen-muls” switch (on page 1-32).
• Normal ANSI C external linkage does not specifically require standard include files to be used, although it is recommended. In many
cases, Analog C compilers do require standard include files to be
used as build configurations. Instead, optimizations are used to
select the correct and optimal implementation of C library functions. For example, the include files may redefine standard C
functions to use optimal compiler built-in implementations.
The compilers also support a number of language extensions that are
essentially aids to DSP programmers and would not be defined in strict
ANSI conforming implementations. These extensions are usually enabled
by default and in some cases can be disabled using a command-line switch,
if required.
These extensions include:
• Inline (function) which directs the compiler to integrate the function code into the code of the callers. Disabled if the -O switches
(described on page 1-32) are not used.
• Dual memory support keywords (
-no-extra-keywords compiler switch (on page 1-30).
• Placement support keyword (
-no-extra-keywords compiler switch (on page 1-30).
pm/dm). Disabled using the
section). Disabled using the
1-4 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
• Boolean type support keywords in C (
bool, true, false). Disabled
using the -no-extra-keywords compiler switch (see on page 1-30).
• Variable length array support
• Non-constant aggregate initializer support
• Indexed initializer support
• Preprocessor generated warnings
• Support for C++-style comments in C programs
For more information on these extensions, see the “C Compiler Language
Extensions” on page 1-52.
VisualDSP++ 3.5 C Compiler and Library Manual 1-5
for ADSP-218x DSPs
Compiler Command-Line Reference
Compiler Command-Line Reference
This section describes how the cc218x 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-7
• “Specifying Compiler Options in VisualDSP++” on page 1-10
• “Compiler Command-Line Switches” on page 1-11
• “Data Type Sizes” on page 1-47
• “Optimization Control” on page 1-49
By default, the cc218x 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-9 lists valid extensions. By default, the
compiler processes the input file through the listed stages to produce a
.DXE file.
1-6 VisualDSP++ 3.5 C Compiler and Library Manual
When developing a DSP project, you may find it useful to modify
the compiler’s default options settings. The way you set the compiler’s options depends on the environment used to run the DSP
development software.
See “Specifying Compiler Options in VisualDSP++” on page 1-10
for more information.
for ADSP-218x DSPs
Running the Compiler
Use the following general syntax for the cc218x command line:
cc218x [-switch [-switch …]] sourcefile [sourcefile …]
where:
-switch is the name of the switch to be processed. The compiler
•
has many switches. These switches select the operations and modes
for the compiler and other tools. Command-line switches are case
sensitive. For example,
•The sourcefile is the name of the file to be preprocessed, com-
piled, assembled, and/or linked.
• A file name can include the drive, directory, file name and file
extension. The compiler supports both Win32- and POSIX-style
paths, using either forward or back slashes as the directory delimiter. It also supports UNC path names (starting with two slashes
and a network name).
-O is not the same as -o.
Compiler
•The cc218x compiler uses the file extension to determine what the
file contains and what operations to perform upon it. Table 1-1 on
page 1-9 lists the allowed extensions.
For example, the following command line
cc218x -proc ADSP-2189 -O -Wremarks -o program.dxe source.c
runs cc218x with the following switches:
-proc ADSP-2189 Specifies the processor
-O Specifies optimization for the compiler
-Wremarks Selects extra diagnostic remarks in addition to warning and error messages
-o program.dxe Selects a name for the compiled, linked output
source.c Specifies the C language source file to be compiled
VisualDSP++ 3.5 C Compiler and Library Manual 1-7
for ADSP-218x DSPs
Compiler Command-Line Reference
The normal function of the
cc218x switch is to invoke the compiler,
assembler, and linker as required to produce an executable file. The precise operation is determined by the extensions of the input filenames,
and/or by various switches.
The compiler uses the following files to perform the specified action:
Extension Action
.c .C C source file is compiled, assembled, and linked
.asm, .dsp, or .s Assembly language source file is assembled and linked
.doj Object file (from previous assembly) is linked
If multiple files are specified, each is first processed to produce an object
file; then all object files are presented to the linker.
You can stop this sequence at various points by using appropriate compiler switches, or by selecting options within the VisualDSP++ IDDE.
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, cc218x names the output for you. Table 1-1 lists the type of files, names, and extensions the
compiler appends to output files.
File extensions vary by command-line switch and file type. These extensions are influenced by the program that is processing the file, any search
directories that you select, and any path information that you include in
the file name.
Table 1-1 indicates the searches that the preprocessor, compiler, assem-
bler, and linker support. The compiler supports relative and absolute
directory names to define file search paths. Using the verbose output
switches for the preprocessor, compiler, assembler, and linker causes each
of these tools to echo the name of each file as it is processed.
1-8 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Table 1-1. Input and Output Files
Compiler
Input File Extension
.c C source file
.h Header file (referenced by a #include statement)
.i Preprocessed C source, created when preprocess only
.idl Interface definition language files for VCSE.
.ipa, .opa Interprocedural analysis files — used internally by the compiler
.pch Precompiled header file.
.s,.dsp,.asm Assembly language source file
.is Preprocessed assembly language source (retained when
.doj Object file to be linked
.dlb Library of object files to be linked as needed
.xml DSP system memory map file output
.sym DSP system symbol map file output
For information on additional search directories, see the
Input File Description
-E compiler switch) is specified
(
when performing interprocedural analysis.
-save-temps is specified)
-I directory
switch (on page 1-25) and -L directory switch (on page 1-27).
When you provide an input or output file name as an optional parameter,
use the following guidelines:
• Use a file name (include the file extension) with either an unambiguous relative path or an absolute path. A file name with an absolute
path includes the drive, directory, file name, and file extension.
Enclose long file names within straight quotes; for example,
file name.c”
. The cc218x compiler uses the file extension conven-
“long
tion listed in Table 1-1 to determine the input file type.
VisualDSP++ 3.5 C Compiler and Library Manual 1-9
for ADSP-218x DSPs
Compiler Command-Line Reference
• Verify that the compiler is using the correct file. If you do not provide the complete path as part of the parameter or add additional
search directories,
cc218x looks for input in the current directory.
Specifying Compiler Options in VisualDSP++
When using the VisualDSP++ IDDE, use the Compile tab from the
Project Options dialog box to set compiler functional options described
on Figure 1-1.
Figure 1-1. Project Options -- Compile Property Page
1-10 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
There are four sub-pages you can access—General, Preprocessor, Processor, and Warning. Most page options have a corresponding compiler
command-line switch described in “Compiler Command-Line Switches”.
The Additional options field in each sub-page is used to enter the appropriate file names and options that do not have corresponding controls on
the Compile tab but are available as compiler switches.
Use the VisualDSP++ online Help to get more information on compiler
options you can specify from the VisualDSP++ environment.
Compiler Command-Line Switches
Table 1-2 lists the command-line switches accepted by the cc218x com-
piler. A detailed description of each of these switches follows the table.
Table 1-2. Compiler Command-Line Switches
Switch Name Description
-@ filename
(on page 1-18)
-A name(tokens)
(on page 1-18)
-alttok
(on page 1-19)
-bss
(on page 1-20)
-build-lib
(on page 1-20)
-C
(on page 1-20)
-c
(on page 1-20
-const-read-write
(on page 1-20
Reads command-line input from the file.
Asserts the specified name as a predicate.
Allows alternative keywords and sequences in sources.
Causes the compiler to put global zero-initialized data into a
separate BSS-style 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; does not link.
Specifies that data accessed via a pointer to const data may be
modified elsewhere.
VisualDSP++ 3.5 C Compiler and Library Manual 1-11
for ADSP-218x DSPs
Compiler Command-Line Reference
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
-Dmacro[=definition]
(on page 1-20)
-debug-types
(on page 1-21)
-default-linkage-{asm|C}
(on page 1-21)
-dry
(on page 1-22)
-dryrun
(on page 1-22)
-E
(on page 1-22)
-ED
(on page 1-22)
-EE
(on page 1-22)
-extra-keywords
(on page 1-22)
-flags-{asm | compiler |
| lib | link | mem}
[, argument [,...]]
(on page 1-23)
Defines a macro.
Supports building a
*.h file directly and writing a complete
set of debugging information for the header file.
Sets the default linkage type (
asm, C).
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.
Produce preprocessed file and compile source.
Preprocesses and compiles the source file.
Recognizes the Analog Devices extensions to ANSI/ISO
standards for C. Default mode.
Passes command-line switches through the compiler to other
build tools.
-fp-associative
(on page 1-23)
-full-version
Treats floating-point multiplication and addition as associative.
Displays version information for build tools.
(on page 1-23)
-g
Generates DWARF-2 debug information.
(on page 1-23)
-H
Outputs a list of header files, but does not compile.
(on page 1-24)
1-12 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
Compiler
-HH
(on page 1-24)
-h[elp]
(on page 1-24)
-I-
(on page 1-25)
-I directory
(on page 1-25)
-i
(on page 1-25)
-include filename
(on page 1-25)
-ipa
(on page 1-26)
-jump-{dm|pm|same}
(on page 1-26)
-L directory
(on page 1-27)
-l library
(on page 1-27)
Outputs a list of included header files and compiles.
Outputs a list of command-line switches.
Establishes the point in the
include directory list at which
the search for header files enclosed in angle brackets should
begin.
Appends the specified search directory to the standard search
path.
Only output header details or makefile dependencies for
include files specified in double quotes.
Includes named file prior to processing each source file.
Specifies that interprocedural analysis should be performed
for optimization between translation units.
Specifies that the compiler should place jump tables in data
memory, program memory, or the same memory section as
the function to which it applies.
Appends the specified directory to the standard library search
path when linking.
Searches the specified library for functions when linking.
-M
Generates make rules only; does not compile.
(on page 1-27)
-MD
Generates make rules and compiles.
(on page 1-28)
-MM
Generates make rules and compiles.
(on page 1-28)
-Mo filename
(on page 1-28)
Specifies a file for output when using the
switches.
-ED and -MD
VisualDSP++ 3.5 C Compiler and Library Manual 1-13
for ADSP-218x DSPs
Compiler Command-Line Reference
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
-Mt filename
(on page 1-28)
-MQ
(on page 1-28)
-make-autostatic
(on page 1-29)
-map filename
(on page 1-29)
-mem
(on page 1-29)
-no-alttok
(on page 1-29)
-no-bss
(on page 1-30)
-no-builtin
(on page 1-30)
-no-defs
(on page 1-30)
-no-extra-keywords
(on page 1-30)
Makes dependencies for the specified source file.
Generates make rules only; does not compile.No notification
when input files are missing.
Directs the compiler to place all automatic variables in static
store.
Directs the linker to generate a memory map of all symbols.
Causes the compiler to invoke the Memory Initializer after
linking the executable.
Does not allow alternative keywords and sequences in
sources.
Causes the compiler to group global zero-initialized data into
the same section as global data with non-zero initializers.
Disables recognition of _
_builtin functions.
Disables preprocessor definitions: macros, include directories, library directories, run-time headers, or keyword extensions.
Does not define language extension keywords that could be
valid C identifiers.
-no-fp-associative
(on page 1-31)
-no-mem
(on page 1-31)
-no-std-ass
(on page 1-31)
-no-std-def
(on page 1-31)
Does not treat floating-point multiply and addition as an
associative.
Causes the compiler to not invoke the Memory Initializer
after linking. Set by default.
Disables any predefined assertions and system-specific
macro definitions.
Disables normal macro definitions; also disables Analog
Devices keyword extensions that do not have leading underscores (__).
1-14 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
Compiler
-no-std-inc
(on page 1-31)
-no-std-lib
(on page 1-32)
-no-widen-muls
(on page 1-32)
-O
(on page 1-32)
-Oa
(on page 1-33)
-Os
(on page 1-33)
-Ov num
(on page 1-33)
-o filename
(on page 1-33)
-P
(on page 1-34)
-PP
(on page 1-34)
Searches for preprocessor include header files only in the current directory and in directories specified with the -I switch.
Searches only for those linker libraries specified with the
-l
switch when linking.
Disable widening multiplications optimization.
Enables optimizations.
Enables automatic function inlining.
Optimize for code size.
Controls speed vs. 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 preprocessing.
-path-{asm|compiler|def
|lib|link|mem} filename
Use the specified component in place of the default installed
version of a compilation tool.
(on page 1-34)
-path-install directory
(on page 1-34)
-path-output directory
Uses the specified directory as the location of all compilation
tools.
Specifies the location of non-temporary files.
(on page 1-35)
-path-temp directory
Specifies the location of temporary files.
(on page 1-35)
-pch
Generates and uses precompiled header files (
*.pch)
(on page 1-35)
VisualDSP++ 3.5 C Compiler and Library Manual 1-15
for ADSP-218x DSPs
Compiler Command-Line Reference
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
-pchdir directory
(on page 1-35)
-pedantic
(on page 1-35)
-pedantic-errors
(on page 1-36)
-pplist filename
(on page 1-36)
-proc identifier
(on page 1-36)
-R directory
(on page 1-37 )
-R-
(on page 1-38)
-reserve <reg1>[,reg2..]
(on page 1-38)
-S
(on page 1-38)
-s
(on page 1-39)
Specifies the location of PCHRepository.
Issues compiler warnings for any constructs that are not
strictly ISO/ANSI standard C-compliant.
Issues compiler errors for any constructs that are not strictly
ISO/ANSI standard C-compliant.
Outputs a raw preprocessed listing to the specified file.
Specifies that the compiler should produce code suitable for
the specified DSP.
Appends directory to the standard search path for source
files.
Removes all directories from the standard search path for
source files.
Reserves specified registers for autobuffering.
Stops compilation before running the assembler.
Removes debugging information from the output executable
file when linking.
-save-temps
Saves intermediate files.
(on page 1-39)
-show
Displays the driver command-line information.
(on page 1-39)
-si-revision version
Specifies a silicon revision of the specified processor.
(on page 1-39)
-signed-bitfield
(on page 1-40)
Treats bitfields which have not been declared with use of
signed or unsigned keyword as signed. This is the default
behavior.
-signed-char
Makes the
char data type signed.
(on page 1-40)
1-16 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
Compiler
-syntax-only
(on page 1-40)
-sysdefs
(on page 1-41)
-T filename
(on page 1-41)
-time
(on page 1-41)
-Umacro
(on page 1-42)
-unsigned-bitfield
(on page 1-42)
-unsigned-char
(on page 1-43)
-v
(on page 1-43)
-val-global <name-list>
(on page 1-43)
-verbose
(on page 1-43)
Checks the source code for compiler syntax errors, but does
not write any output.
Defines the system definition macros.
Specifies the Linker Description File.
Displays the elapsed time as part of the output information
on each part of the compilation process.
Undefines
macro.
Treats bitfields which have not been declared with use of
signed or unsigned keyword as unsigned.
Makes the
char data type unsigned.
Displays both the version and command-line information.
Adds global names.
Displays command-line information.
-version
Displays version information.
(on page 1-43)
-Wdriver-limit number
Halts the driver after reaching the specified number of errors.
(on page 1-44)
-Werror-limit number
(on page 1-44)
-W{error|remark|suppress
<num>[,num...]
|warn}
Stops compiling after reaching the specified number of
errors.
Overrides the severity of compilation diagnostic messages.
(on page 1-44)
-Wremarks
(on page 1-44)
Indicates that the compiler may issue remarks, which are
diagnostic messages even milder than warnings.
VisualDSP++ 3.5 C Compiler and Library Manual 1-17
for ADSP-218x DSPs
Compiler Command-Line Reference
Table 1-2. Compiler Command-Line Switches (Cont’d)
Switch Name Description
-Wterse
(on page 1-45)
-w
(on page 1-45)
-warn-protos
(on page 1-45)
-write-files
(on page 1-45)
-write-opts
(on page 1-45)
-xref filename
(on page 1-46)
Issues only the briefest form of compiler warnings, errors,
and remarks.
Does not display compiler warning messages.
Produces a warning when a function is called without a prototype.
Enables compiler I/O redirection.
Passes the user options (but not input filenames) via a temporary file.
Outputs cross-reference information to the specified file.
The following sections provide detailed comman-line switch descriptions.
-@ filename
The
@ filename (command file) switch directs the compiler to read
command-line input from filename. The specified filename must contain
driver options but may also contain source filenames and environment
variables. It can be used to store frequently used options as well as to read
from a file list.
-A name(tokens)
-A (assert) switch directs the compiler to assert name as a predicate
The
with the specified
tokens. This has the same effect as the #assert prepro-
cessor directive. The following assertions are predefined:
system
machine adsp218x
embedded
1-18 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
cpu adsp218x
compiler cc218x
The
-A name(value) switch is equivalent to including
#assert name(value)
in your source file, and both may be tested in a preprocessor condition in
the following manner.
#if #name(value)
// do something
#else
// do something else
#endif
For example, the default assertions may be tested as:
#if #machine(adsp218x)
// do something
#endif
-A switch, to prevent misinterpretation. No quotes are needed for a
#assert directive in a source file.
-alttok
The parentheses in the assertion should be quoted when using the
-alttok (alternative tokens) switch directs the compiler to allow
The
digraph sequences in C source files.
-bss
The -bss switch causes the compiler to place global zero-initialized data
into a BSS-style section (called “
data section. This is default mode. See also the
bsz”), rather than into the normal global
–no-bss switch
(on page 1-30).
VisualDSP++ 3.5 C Compiler and Library Manual 1-19
for ADSP-218x DSPs
Compiler Command-Line Reference
-build-lib
The
-build-lib (build library) switch directs the compiler to use the
elfar (librarian) to produce a library file (.dlb) as the output instead of
using the linker to produce an executable file (.dxe). The -o option
(on page 1-33) must be used to specify the name of the resulting library.
-C
The -C (comments) switch, which is only active in combination with the
-E, -EE, -ED, -P or -PP switches, directs the preprocessor to retain com-
ments in its output.
-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.
-const-read-write
The -const-read-write switch directs the compiler to specify that constants may be accessed as read-write data (as in ANSI C). The compiler’s
default behavior assumes that data referenced through const pointers will
never change.
-const-read-write switch changes the compiler’s behavior to match
The
the ANSI C assumption, which is that other
non-const pointers may be
used to change the data at some point.
-Dmacro [=definition]
-D (define macro) switch directs the compiler to define a macro. If
The
you do not include the optional definition string, the compiler defines the
macro as the string ‘
1’. If definition is required to be a character string
1-20 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
constant, it must be surrounded by escaped double quotes. Note that the
compiler processes
fine macro) switches.
-D switches on the command line before any -U (unde-
-debug-types <file.h>
The -debug-types switch provides for building an *.h file directly and
writing a complete set of debugging information for the header file. The
-g option (on page 1-23) need not be specified with the -debug-types
switch because it is implied. For example,
The implicit -g option writes debugging information for only those
typedefs that are referenced in the program. The -debug-types option
provides complete debugging information for all typedefs and structs.
-default-linkage-{asm|C}
The -default-linkage-asm (assembler linkage) and
-default-linkage-C (C linkage) switches direct the compiler to set the
default linkage type. C is the default linkage type. Compatibility linkage
OldAsmCall) to previous generation calling conventions cannot be set as a
(
default linkage.
This switch can be invoked with the Definitions: dialog field from
the VisualDSP++ Project Options dialog box, Compile tab,
Preprocessor category.
cc218x -debug-types anyHeader.h
VisualDSP++ 3.5 C Compiler and Library Manual 1-21
for ADSP-218x DSPs
This switch can be specified in the Additional Options box located
in the VisualDSP++ Project Options dialog box, Compile tab,
General category.
Compiler Command-Line Reference
-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.
-E
The -E (stop after preprocessing) switch directs the compiler to stop after
the C preprocessor runs (without compiling). The output (preprocessed
source code) prints the standard output stream (<stdout>) unless the output file is specified with the -o switch. Note that the -C switch can be used
in combination with the -E switch.
-ED
The -ED (run after preprocessing to file) switch directs the compiler to
write the output of the C preprocessor to a file named
original_filename.i. After preprocessing, compilation proceeds
normally.
-EE
-EE (run after preprocessing) switch directs the compiler to write the
The
output of the C preprocessor to standard output. After preprocessing,
compilation proceeds normally.
-extra-keywords
The
-extra-keywords (enable short-form keywords) switch directs the
compiler to recognize the Analog Devices keyword extensions to
ISO/ANSI standard C language, including keywords such as
pm and dm
1-22 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
without leading underscores which could affect conforming to ISO/ANSI
C programs. This is the default mode. The “-no-extra-keywords” switch
(see on page 1-30) can be used to disallow support for the additional keywords. Table 1-5 on page 1-53 provides a list and a brief description of
keyword extensions.
-flags-{asm|compiler|lib|link|mem} switch [,switch2 [,...]]
The
-flags (command-line input) switch directs the compiler to pass each
of the comma-separated arguments to the other build tools, such as:
Table 1-3. Build Tools’ Options
Option Tool
-flags-asm easm218x Assembler
-flags-compiler Compiler executable
-flags-lib elfar Library Builder
-flags-link Linker
-flags-mem Memory Initializer
-fp-associative
The -fp-associative switch directs the compiler to treat floating-point
multiplication and addition as associative.
-full-version
-full-version (display version) switch directs the compiler to display
The
version information for all the compilation tools as they process each file.
-g
The -g (generate debug information) switch directs the compiler to output symbols and other information used by the debugger.
VisualDSP++ 3.5 C Compiler and Library Manual 1-23
for ADSP-218x DSPs
Compiler Command-Line Reference
When the
(-O) switch, the compiler performs standard optimizations. The compiler
also outputs symbols and other information to provide limited source level
debugging through VisualDSP++. This combination of options provides
line debugging and global variable debugging.
-H
The -H (list headers) switch directs the compiler to output only a list of
the files included by the preprocessor via the #include directive, without
compiling. The -o switch (on page 1-33) may be used to specify the redirection of the list to a file.
-g switch is used in conjunction with the enable optimization
You can invoke this switch by selecting the Generate debug information check box in the VisualDSP++ Project Options dialog box,
Compile tab, General category.
When -g and -O are specified, no debug information is available for
local variables and the standard optimizations can sometimes
re-arrange program code in a way that inaccurate line number
information may be produced. For full debugging capabilities, use
the -g switch without the -O switch.
-HH
HH (list headers and compile) switch directs the compiler to print to
The the standard output file stream a list of the files included by the preprocessor via the
normally.
-h[elp]
The
list of command-line switches with a brief syntax description.
1-24 VisualDSP++ 3.5 C Compiler and Library Manual
#include directive. After preprocessing, compilation proceeds
-help (command-line help) switch directs the compiler to output a
for ADSP-218x DSPs
Compiler
-I-
The
-I- (start include directory list) switch establishes the point in the
include directory list at which the search for header files enclosed in angle
brackets should begin. 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.
two searches only.
It is possible to replace the initial search (within the directory containing
the current input file) by placing the -I- switch at the point on the command line where the search for all types of header file should begin. All
For header files in angle brackets the compiler performs the latter
include directories on the command line specified before the -I- switch
will only be used in the search for header files that are enclosed in double
quotes.
This switch removes the directory containing the current input file from
the include directory list.
-I directory [{,|;} directory...]
The -I directory (include search directory) switch directs the C preprocessor to append the directory (directories) to the search path for
files. This option may be specified more than once; all specified directories
are added to the search path.
-include filename
include
The -include filename (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.
VisualDSP++ 3.5 C Compiler and Library Manual 1-25
for ADSP-218x DSPs
Compiler Command-Line Reference
Include files, whose names are not absolute path names and that are
enclosed in “...” when included, will be searched for in the following
directories in this order:
1. The directory containing the current input file (the primary source
file or the file containing the
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:
<VisualDSP++ install dir>/.../include
#include)
-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 separately. The -ipa option should be applied to all C files in the program.
For more information, see “Interprocedural Analysis” on page 1-50. Spec-
ifying -ipa also implies setting the -O switch (on page 1-32).
-jump-{dm|pm|same}
The
place jump tables in data memory (
(-jump-pm), or the same memory section as the function to which it
applies (
If a file is included using the <...> form, this file will only be
searched for by using directories defined in items 2 and 3 above.
You can invoke this switch by selecting the Interprocedural
optimization check box in the VisualDSP++ Project Options dialog box, Compile tab, General category.
-jump (select jump table memory type) switch directs the compiler to
-jump-dm) or program memory
-jump-same). Jump tables are storage that might be required to
1-26 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
hold in memory target addresses for branch instruction used in complex
if-then-else statements or switch statements. The default storage mem-
ory for jump tables is data memory.
-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 when linking. The library name is the portion of the file name
between the lib prefix and .dlb extension. For example, the compiler
command-line switch -lc directs the linker to search in the library named
c for functions. This library resides in a file named libc.dlb.
Normally, you should list all object files on the command line before the
-l switch. This ensures that the functions and global variables the object
files refer to are loaded in the given order. This option may be specified
more than once; libraries are searched as encountered during the
left-to-right processing of the command line.
-M
-M (generate make rules only) switch directs the compiler not to com-
The
pile the source file but to output a rule, which is 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 ...
VisualDSP++ 3.5 C Compiler and Library Manual 1-27
for ADSP-218x DSPs
Compiler Command-Line Reference
-MD
The
-MD (generate make rules and compile) switch directs the preprocessor
to print to a file called original_filename.d a rule describing the dependencies of the main program file. After preprocessing, compilation
proceeds normally. See also the –Mo switch.
-MM
The -MM (generate make rules and compile) switch directs the preprocessor
to print to stdout a rule describing the dependencies of the main program
file. After preprocessing, compilation proceeds normally.
-Mo filename
The -Mo filename (preprocessor output file) switch directs the compiler
to use filename for the output of –MD or –ED switches.
-Mt filename
The -Mt filename (output make rule for the named source) switch specifies
the name of the source file for which the compiler generates the make rule
when you use the -M or -MM switch. If the named file is not in the current
directory, you must provide the path name in double quotation marks
(“”). The new file name will override the default base.doj. The
-Mt option
supports the .IMPORT extension.
-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.
1-28 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
-make-autostatic
The
-make-autostatic (make automatic variables static) switch directs the
compiler to place all automatic variables in static store. This may be beneficial in code that requires many accesses of automatic variables as an
access to static store is done in one instruction, whereas an access to local
automatic stack area may require three instructions.
Alternatively, this feature can be applied on a function-by-function basis
using the make_auto_static pragma. See “Stack Usage Pragma” on
page 1-108 for more information.
-map filename
The -map (generate a memory map) switch directs the linker to output a
memory map of all symbols. The map file name corresponds to the
filename argument. For example, if the filename argument is test, the
map file name is test.xml. The .xml extension is added where necessary.
-mem
The -mem (invoke memory initializer) switch causes the compiler to invoke
the Memory Initializer tool after linking the executable. The MemInit
tool can be controlled through the
-no-alttok
The -no-alttok (disable alternative tokens) switch directs the compiler to
not accept alternative operator keywords and digraph sequences in the
source files. This is the default mode. For more information, see “-alttok”
on page 1-19.
Do not use the -make-autostatic switch if the source being compiled contains any functions that are directly or indirectly
recursive.
-flags-mem switch (on page 1-23).
VisualDSP++ 3.5 C Compiler and Library Manual 1-29
for ADSP-218x DSPs
Compiler Command-Line Reference
-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-19).
-no-builtin
The -no-builtin (no builtin functions) switch directs the compiler to recognize only built-in functions that begin with two underscores (__). Note
that this switch influences many functions. This switch also predefines the
__NO_BUILTIN preprocessor macro.
-no-defs
The -no-defs (disable defaults) switch directs the preprocessor not to
define any default preprocessor macros, include directories, library directories, libraries, or run-time headers.
-no-extra-keywords
The
compiler not to recognize the Analog Devices keyword extensions that
might affect conformance to ISO/ANSI standards for the C language.
These extensions include keywords, such as asm, which may be used as
identifiers in conforming programs. Alternate keywords that are prefixed
with two leading underscores, such as
The “-extra-keywords” switch (on page 1-22) can be used to explicitly
request support for the additional keywords.
For more information on built-in functions, see “Compiler
Built-in Functions” on page 1-83 and “Using the Compiler’s
Built-In Functions” on page 3-2.
-no-extra-keywords (disable short-form keywords) switch directs the
__pm and __dm, continue to work.
1-30 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
-no-fp-associative
The
-no-fp-associative switch directs the compiler not to treat
floating-point multiplication and addition as associative.
-no-mem
The -no-mem switch causes the compiler to not invoke the Memory Initializer tool after linking the executable. This is the default setting. See also
“-mem” on page 1-29.
-no-std-ass
The -no-std-ass (disable standard assertions) switch prevents the compiler from defining the system, machine, cpu and compiler assertions and
from defining system-specific assertions. See the -A switch (on page 1-18)
for the list of standard assertions.
-no-std-def
The -no-std-def (disable standard macro definitions) prevents the compiler from defining any default preprocessor macro definitions.
-no-std-inc
-no-std-inc (disable standard include search) switch directs the C
The
preprocessor to search for header files in only the current directory and
directories specified with -I switch (on page 1-25).
VisualDSP++ 3.5 C Compiler and Library Manual 1-31
for ADSP-218x DSPs
You can invoke this switch by selecting the Ignore standard
include paths check box in the VisualDSP++ Project Options
dialog box, Compile tab, Preprocessor category.
Compiler Command-Line Reference
-no-std-lib
The
-no-std-lib (disable standard library search) switch directs the linker
to limit its search for libraries to directories specified with the -L switch
(on page 1-27). The compiler also defines __NO_STD_LIB during the linking stage and passes it to the linker, so that the SEARCH_DIR directives in
the .LDF file can de disabled.
-no-widen-muls
The -no-widen-muls (disable widening multiplications) switch disables
the compiler optimization which it performs on multiplication operations.
By default, the compiler, attempts to optimize integer multiplication
operations which are stored in a long result to utilize the double-word
MAC result registers of ADSP-218x DSPs. The code produced this way is
better suited to the processor and therefore more efficient.
However, this optimization can generate overflow results which are not
consistent in some cases and may differ from expected results depending
on the optimizations enabled and the way that the source is written. The
inconsistency and differences are seen if an overflow and truncation of the
integer operands would normally occur.
When the optimization is applied, there is no truncation. When the optimization is disabled, the result of overflow will be truncated to integer size
before being stored in the long result.
-O
The -O (enable optimizations) switch directs the compiler to produce code
that is optimized for performance. Optimizations are not enabled by
default for the compiler.
1-32 VisualDSP++ 3.5 C Compiler and Library Manual
You can invoke this switch by selecting the Enable optimization
check box in the VisualDSP++ Project Options dialog box,
Compile tab, General category.
for ADSP-218x DSPs
Compiler
-Oa
The
-Oa (automatic function inlining) switch enables the inline expansion
of 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-33).
Therefore, use of -Ov100 indicates that as many functions as possible will
be auto-inlined whereas –Ov0 prevents any function from being
auto-inlined. Specifying -Oa also implies the use of -O.
-Os
The -Os (optimize for size) switch directs the compiler to produce code
that is optimized for size. This is achieved by performing all optimizations
except those that increase code size. The optimizations not performed
include loop unrolling and jump avoidance. It also uses a function to save
and restore preserved registers for a function instead of generating the
more cycle-efficient inline default versions.
-Ov num
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).
-o filename
The -o (output file) switch directs the compiler to use filename for the
name of the final output file.
When remarks are enabled, the compiler will produce a remark to
indicate each function that is inlined.
num' should be
VisualDSP++ 3.5 C Compiler and Library Manual 1-33
for ADSP-218x DSPs
Compiler Command-Line Reference
-P
The
-P (omit line numbers) switch directs the compiler to stop after the C
preprocessor runs (without compiling) and to omit the #line preprocessor
directives (with line number information) in the output from the preprocessor. The -C switch 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|def|lib|link|mem} filename
The -path (tool location) switch directs the compiler to use the specified
component in place of the default installed version of the compilation
tool. The component should comprise a relative or absolute path to its
location. Respectively, the tools are the assembler, compiler, driver definitions file, librarian, linker or memory initializer.
Use this switch when you wish to override the normal version of one or
more of the tools. The -path switch also overrides the directory specified
by the -path-install switch (on page 1-34).
-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.
1-34 VisualDSP++ 3.5 C Compiler and Library Manual
You can selectively override this switch with the -path switch
(on page 1-34).
for ADSP-218x DSPs
Compiler
-path-output directory
The
-path-output (non-temporary files location) switch directs the com-
piler to place output files in the specified directory.
-path-temp directory
The -path-temp (temporary files location) switch directs the compiler to
place temporary files in the specified directory.
-pch
The -pch (precompiled header) switch directs the compiler to automatically generate and use precompiled header files. A precompiled output
header has a .pch extension attached to the source file name. By default,
all precompiled headers are stored in a directory called PCHRepository.
-pch directory
The -pch directory (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 warnings for any constructs found in your program that do not
strictly conform to the ISO/ANSI standard for C.
Precompiled header files can significantly speed compilation; precompiled 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++ 3.5 C Compiler and Library Manual 1-35
for ADSP-218x DSPs
Compiler Command-Line Reference
-pedantic-errors
The
-pedantic-errors (ANSI C errors) switch causes the compiler to
issue errors instead of warnings for cases described in the -pedantic
switch.
-pplist filename
The -pplist (preprocessor listing) switch directs the preprocessor to output a listing to the named file. When more than one source file has been
preprocessed, the listing file contains information about the last file processed. The generated file contains raw source lines, information on
transitions into and out of include files, and diagnostics generated by the
compiler.
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
-proc processor
-proc (target processor) switch specifies that the compiler should pro-
The
duce code suitable for the specified processor. The
processor identifiers
directly supported in VisualDSP++ 3.5 are:
1-36 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
ADSP-2181, ADSP-2183, ADSP-2184, ADSP-2185, ADSP-2186,
ADSP-2187, ADSP-2188, and ADSP-2189
For example,
cc218x -proc ADSP-2181 p1.c
If the processor identifier is unknown to the compiler, it attempts to read
required switches for code generation from the file <processor>.ini. The
assembler searches for the .ini file in the VisualDSP ++ System folder.
For custom processors, the compiler searches the section “proc” in the
<processor>.ini for key 'architecture'. The custom processor must be
based on an architecture key that is one of the known processors. For
example, -proc Customxxx searches the Customxxx.ini file.
When compiling with the -proc switch, the compiler defines the corresponding __ADSP21{81|83|84|85|86|87|88|89}__ macro for the variant
selected in addition to the __ADSP21XX__ and __ADSP218X__ macros which
are always are defined as 1. For example, __ADSP2181__ and __ADSP218X__
are pre-defined to 1 by the compiler.
-R directory [{;|,}directory …]
If no target is specified with the -proc switch, the compiler will
generate an error message.
See also “-si-revision version” on page 1-39 for more information
on silicon revision of the specified processor.
The -R (add source directory) switch directs the compiler to add the spec-
directory to the list of directories searched for source files.
ified
On Windows™ platforms, multiple source directories are given as a
comma or semicolon separated list. The compiler searches for the source
files in the order specified on the command line. The compiler searches
VisualDSP++ 3.5 C Compiler and Library Manual 1-37
for ADSP-218x DSPs
Compiler Command-Line Reference
the specified directories before reverting to the current project directory.
This option is position-dependent on the command line; that is, it affects
only source files that follow the option.
Source files whose file names begin with /
equivalent) and contain drive specifiers (on Windows™ platforms) are
not affected by this option.
-R-
The -R- (disable source path) switch removes all directories from the standard search path for source files, effectively disabling this feature.
-reserve register[,register...]
The -reserve (reserve register) switch directs the compiler not to use the
specified register(s). This guarantees that a known register or set of registers is available for autobuffering.
You can reserve the I2, I3, I5, I7 and M0 registers. Separate register names
with commas on the compiler command line. Reserving registers seriously
reduces the effectiveness of compiler optimizations and should only be
done when autobuffering (using circular buffers) is essential. For more
information, refer to “Autobuffering Support” on page 1-134.
This option is position-dependent on the command line; it only
affects files following it.
, ./ or ../ (or Windows™
-S
-S (stop after compilation) switch directs the compiler to stop compi-
The
lation before running the assembler. The compiler outputs an assembler
file with a .s extension.
1-38 VisualDSP++ 3.5 C Compiler and Library Manual
You can invoke this switch by selecting the Stop after: Compiler
check box in the VisualDSP++ Project Options dialog box,
Compile tab, General category selection.
for ADSP-218x DSPs
Compiler
-s
The
-s (strip debugging information) switch directs the compiler to
remove debugging information (symbol table and other items) from the
output executable file during linking.
-save-temps
The -save-temps (save intermediate files) switch directs the compiler to
retain intermediate files generated and normally removed as part of the
various compilation stages. These intermediate files are placed in the
–path-output specified output directory or the build directory if the
-path-output switch (on page 1-35) is not used. See Table 1-1 on
page 1-9 for a list of input/output files (file extensions).
-show
The -show (display command line) switch directs the compiler to echo all
command-line arguments, expanded option files switches and environment variables used by the compiler.
-si-revision version
The -si-revision version (silicon revision) switch sets the version of the
hardware which is the required target for the build. It is used to enable
inherent behavior relating to any errata in specific silicon revisions. The
revision can be specified as “none” or a number of the form described by
regular expression
[0-9]+\.[0-9]{1,3} (for example 1.123). The com-
piler defines a macro __SILICON_REVISION__ to a value specific to each
silicon revision. For unknown revisions, the compiler will generate a
warning and default to the latest known revision.
The parameter “version” represents a silicon revision of the processor
specified by the -proc switch (on page 1-36). The “none” revision disables
support for silicon errata.
VisualDSP++ 3.5 C Compiler and Library Manual 1-39
for ADSP-218x DSPs
Compiler Command-Line Reference
For example,
cc218x -proc ADSP-2189 -si-revision 0.1
A compiler will “pass along” the appropriate -si-revision switch setting
when invoking another VisualDSP++ tool, for example, when the compiler driver invokes assembler and linker.
-signed-bitfield
The -signed-bitfield (make plain bitfields signed) switch directs the
compiler to make bitfields which have not been declared with an explicit
signed or unsigned keyword to be signed. This switch does not effect plain
one-bit bitfields which are always unsigned. This is the default mode. See
also the -unsigned-bitfield switch (on page 1-42).
-signed-char
The -signed-char (make char signed) switch directs the compiler to make
the default type for char signed. The compiler also defines the
__SIGNED_CHARS__ macro. This is the default mode when the
-unsigned-char (make char unsigned) switch (on page 1-43) is not used.
In the absence of silicon revision, the compiler selects the greatest
silicon revision it “knows” about, if any.
-syntax-only
-syntax-only (just check syntax) switch directs the compiler to check
The
the source code for syntax errors and warnings. No output files will be
generated with this switch.
1-40 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
-sysdefs
The
-sysdefs (system definitions) switch directs the compiler to define
several preprocessor macros describing the current user and user’s system.
The macros are defined as character string constants and are used in functions with null-terminated string arguments.
The following macros are defined if the system returns information for
them:
Macro Description
__HOSTNAME__ The name of the host machine
__MACHINE__ The machine type of the host machine
__SYSTEM__ The OS name of the host machine
__USERNAME__ The current user's login name
__GROUPNAME__ The current user's group name
__REALNAME__ The current user's real name
__MACHINE__, __GROUPNAME__, and __REALNAME__ are not available
on Windows platforms.
-T filename
-T (Linker Description File) switch directs that the linker, when
The
invoked, will use the specified Linker Description File (LDF). If
-T is not
specified, a default .LDF file is selected based on the processor variant.
-time
-time (time the compiler) switch directs the compiler to display the
The
elapsed time as part of the output information on each part of the compilation process.
VisualDSP++ 3.5 C Compiler and Library Manual 1-41
for ADSP-218x DSPs
Compiler Command-Line Reference
-Umacro
The
-U (undefine macro) switch lets you undefine macros. If you specify a
macro name, it will be undefined. The compiler processes all -D (define
macro) switches on the command line before any -U (undefine macro)
switches.
VisualDSP++ Project Options dialog box, Compile tab,
Preprocessor category.
-unsigned-bitfield
The -unsigned-bitfield (make plain bitfields unsigned) switch directs
the compiler to make bitfields which have not been declared with an
explicit signed or unsigned keyword to be unsigned. This switch does not
effect plain one-bit bitfields which are always unsigned.
For example, given the declaration
You can invoke this switch by selecting the Undefines field in the
struct {
int a:2;
int b:1;
signed int c:2;
unsigned int d:2;
} x;
the bitfield values are:
Field -unsigned-bitfield -signed-bitfield Why
x.a -2..1 0..3 Plain field
x.b 0..1 0..1 One bit
x.c -2..1 -2..1 Explicit signed
x.d 0..3 0..3 Explicit unsigned
See also the
-signed-bitfields switch (on page 1-40).
1-42 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
-unsigned-char
The
-unsigned-char (make char unsigned) switch directs the compiler to
make the default type for char unsigned. The compiler also undefines the
__SIGNED_CHARS__ preprocessor macro.
-v
The -v (version and verbose) switch directs the compiler to display both
the version and command-line information for all the compilation tools as
they process each file.
-val-global <name-list>
The -val-global (add global names) switch directs the compiler that the
names given by <name-list> are present in all globally defined variables.
The list is separated by double colons(::). In C, the names are prefixed and
separated by underscores (_). The compiler will issue an error on any globally defined variable in the current source module(s) not using
<name-list>. This switch is used to define VCSE components.
-verbose
The -verbose (display command line) switch directs the compiler to display command-line information for all the compilation tools as they
process each file.
-version
-version (display compiler version) switch directs the compiler to
The
display its version information.
VisualDSP++ 3.5 C Compiler and Library Manual 1-43
for ADSP-218x DSPs
Compiler Command-Line Reference
-Wdriver-limit number
The
-Wdriver-limit (maximum process errors) switch lets you set a maxi-
mum number of driver errors (command line, etc.) that the driver aborts
at.
-Werror-limit number
The -Werror-limit (maximum compiler errors) switch lets you set a maximum number of errors for the compiler.
-W{error|remark|suppress|warn} <num>[,num...]
The -W <...> number (override error message) switch directs the compiler
to override the severity of the specified diagnostic messages (errors,
remarks, or warnings). The num argument specifies the message to
override.
At compilation time, the compiler produces a number for each specific
compiler diagnostic message. The {D} (discretionary) string after the diagnostic message number indicates that the diagnostic may have its severity
overridden. Each diagnostic message is identified by a number that is used
across all compiler software releases.
-Wremarks
-Wremarks (enable diagnostic warnings) switch directs the compiler to
The
issue remarks, which are diagnostic messages that are even milder than
warnings.
1-44 VisualDSP++ 3.5 C Compiler and Library Manual
You can invoke this switch by selecting the Enable remarks check
box in the VisualDSP++ Project Options dialog box, Compile tab,
Warning selection.
for ADSP-218x DSPs
-Wterse
The
-Wterse (enable terse warnings) switch directs the compiler to issue
the briefest form of warnings. This also applies to errors and remarks.
-w
The -w (disable all warnings) switch directs the compiler not to issue
warnings.
Compiler
-warn-protos
The -warn-protos (prototypes warning) switch directs the compiler to
produce a warning message when a function is called without a full prototype being supplied.
-write-files
The -write-files (enable driver I/O redirection) switch directs the compiler driver to redirect the file name portions of its command line through
a temporary file. This technique helps with handling long file names,
which can make the compiler driver’s command line too long for some
operating systems.
-write-opts
The -write-opts switch directs the compiler to pass the user-specified
options (but not the input file names) to the main driver via a temporary
file. This can be helpful if the resulting main driver command line would
otherwise be too long.
You can invoke this switch by selecting the Disable all warnings
and remarks check box in the VisualDSP++ Project Options dialog box, Compile tab, Warning selection.
VisualDSP++ 3.5 C Compiler and Library Manual 1-45
for ADSP-218x DSPs
Compiler Command-Line Reference
-xref <file>
The
-xref (cross-reference list) switch directs the compiler to write
cross-reference listing information to the specified file. When more than
one source file has been compiled, the listing contains information about
the last file processed.
For each reference to a symbol in the source program, a line of the form
symbol-id name ref-code filename line-number column-number
is written to the named file. symbol-id represents a unique decimal number for the symbol.
The ref-code parameter is one of the following characters.
Character Meaning
D Definition
d Declaration
M Modification
A Address taken
U Used
C Changed (used and modified)
R Any other type of reference
E Error (unknown type of reference)
1-46 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
Data Type Sizes
The sizes of intrinsic C data types are selected by Analog Devices so that
normal C programs execute with hardware-native data types and therefore
execute at high speed.
Table 1-4. Data Type Sizes for the ADSP-218x DSPs
Ty p e Bi t Si z e sizeof returns
int 16 bits signed 1
unsigned int 16 bits unsigned 1
char 16 bits signed 1
unsigned char 16 bits unsigned 1
short 16 bits signed 1
unsigned short 16 bits unsigned 1
pointer 16 bits 1
fract16 16 bits fractional
(defined in
long 32 bits signed 2
unsigned long 32 bits unsigned 2
function pointer 32 bits 2
float 32 bits float 2
double 32 bits float 2
fract32 32 bits fractional
(defined in
On any platform the basic type
long is 32 bits, as is float. A pointer is the same size as an int.
fract_typedef.h)
fract_typedef.h)
int is the native word size. The data type
1
2
VisualDSP++ 3.5 C Compiler and Library Manual 1-47
for ADSP-218x DSPs
Compiler Command-Line Reference
On the ADSP-218x processor architecture, the
long long int
, and long double data types are not implemented (they are
long long int, unsigned
not redefined to other types). In general, double word data types should
be expected to run more slowly, relying largely on software-emulated
arithmetic.
Analog Devices does not support data sizes smaller than a single word
location for ADSP-218x processors. For the current processors, this means
that both short and char have the same size as int. Although 16-bit chars
are unusual, they conform to the standard.
Type double poses a special problem. The C language tends to default to
double for constants and in many floating-point calculations. Without
some special handling, many programs would inadvertently end up using
slow-speed emulated 64-bit floating-point arithmetic, even when variables
are declared consistently as float.
In order to avoid this problem and provide the best performance, the size
of double on the ADSP-218x DSPs is always 32 bits. This should be
acceptable for most DSP programming. It is not, however, fully standard
conforming.
The standard include files automatically redefine the math library interfaces such that functions like sin can be directly called with the proper
size operands; therefore:
float sinf (float); /* 32-bit */
double sin (double); /* 32-bit */
For full descriptions of these functions and their implementation, see
Chapter 3, “C Run-Time Library”.
1-48 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
Optimization Control
The general aim of compiler optimization is to generate correct code that
executes fast and is small in size. Not all optimizations are suitable for
every application or possible all the time so the compiler optimizer has a
number of configurations, or optimization levels, which can be applied
when suitable. Each of these levels are enabled by one or more compiler
switches (and VisualDSP++ project options) or pragmas.
The following list identifies several optimization levels. The levels are
notionally ordered with least optimization listed first and most optimization listed last. The descriptions for each level outline the optimizations
performed by the compiler and identifies any switches or pragmas
required or that have direct influence on the optimization levels
performed.
Refer to Chapter 2, “Achieving Optimal Performance from C
Source Code” for information on how to obtain maximal code per-
formance from the compiler.
• Debug
The compiler produces debug information to ensure that the object
code matches the appropriate source code line. See “-g” on
page 1-23 for more information.
• Default
The compiler does not perform any optimizations by default when
none of the compiler optimization switches are used (or enabled in
VisualDSP++ project options). Default optimization level can be
enabled using the
• Procedural Optimizations
The compiler performs advanced, aggressive optimization on each
procedure in the file being compiled. The optimizations can be
directed to favor optimizations for speed (
factor between speed and space (-Ov). If debugging is also
optimize_off pragma (on page 1-105).
-O) or space (-Os) or a
VisualDSP++ 3.5 C Compiler and Library Manual 1-49
for ADSP-218x DSPs
Compiler Command-Line Reference
requested, the optimization is given priority, so the debugging
functionality may be limited. See “-O” on page 1-32, “-Os” on
page 1-33, and “-Ov num” on page 1-33.
Procedural optimizations for speed and space (using
-O and -Os)
can be enabled in C source using the pragma
optimize_{for_speed|for_space} (see on page 1-105 for more
information on optimization pragmas).
• Automatic Inlining
The compiler automatically inlines C functions which are not necessarily declared as inline in the source code. It does this when it
has determined that doing so will reduce execution time. How
aggressively the compiler performs automatic inlining is controlled
using the -Ov switch. Automatic inlining is enabled using the -Oa
switch and additionally enables Procedural Optimizations (-O). See
“-O” on page 1-32, “-Os” on page 1-33, and “-Ov num” on
page 1-33. for more information.
• Interprocedural optimizations (IPA)
The compiler performs advanced, aggressive optimization over the
whole program, in addition to the per-file optimizations in procedural optimization. IPA is enabled using the -ipa switch and
additionally enables Procedural Optimizations (-O). See “-ipa” on
page 1-26 and “-O” on page 1-32 for more information.
Interprocedural Analysis
The compiler has an optimization capability called Interprocedural Analysis
(IPA) that allows the compiler to optimize across translation units instead
of within individual translation units. This capability allows the compiler
to see all of the source files used in a final link at compilation time and to
use that information while optimizing.
1-50 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
Interprocedural analysis is enabled by selecting the Interprocedural analysis option on the Compiler tab (accessed via the VisualDSP++ Project
Options dialog box), or by specifying the
-ipa command-line switch (see
on page 1-26). The -ipa switch automatically enables the -O switch to
turn on optimization.
Use of the -ipa switch causes additional files to be generated along with
the object file produced by the compiler. These files have .ipa and .opa
filename extensions and should not be deleted manually unless the associated object file is also deleted.
All of the -ipa optimizations are invoked after the initial link; when a special program has called, the prelinker reinvokes the compiler to perform
the new optimizations.
Because a file may be recompiled by the prelinker, you cannot use the -S
option to see the final optimized assembler file when -ipa is enabled.
Instead, you must use the -save-temps switch, so that the full compile/link cycle can be performed first.
Because IPA operates only during the final link, the -ipa switch has no
benefit when compiling the source files to object format for inclusion in a
library. Although IPA will generate usage information for potential additional optimizations at the final link stage, neither the usage information
nor the module's source file are available when the linker includes a module from a library. Therefore, each library module is compiled to the
normal -O optimization level.
The prelinker inspects object modules included from libraries and other
object files which were not compiled with the
-ipa switch to see whether
there are hidden references to the functions and variables defined in those
objects which were compiled with the
-ipa switch, and optimizes those
variables and functions accordingly.
VisualDSP++ 3.5 C Compiler and Library Manual 1-51
for ADSP-218x DSPs
C Compiler Language Extensions
C Compiler Language Extensions
The compiler supports a set of extensions to the ISO/ANSI standards for
the C language. These C extensions add support for DSP hardware and
allow some C programming features.
This section contains:
• “Inline Function Support Keyword (inline)” on page 1-55
• “Inline Assembly Language Support Keyword (asm)” on page 1-56
• “Dual Memory Support Keywords (pm dm)” on page 1-71
• “Placement Support Keyword (section)” on page 1-76
• “Boolean Type Support Keywords (bool, true, false)” on page 1-77
• “Pointer Class Support Keyword (restrict)” on page 1-77
• “Variable-Length Array Support” on page 1-78
• “Non-Constant Aggregate Initializer Support” on page 1-80
• “Indexed Initializer Support” on page 1-80
• “Aggregate Constructor Expression Support” on page 1-82
• “Preprocessor-Generated Warnings” on page 1-83
• “C++-Style Comments” on page 1-83
• “ETSI Support” on page 1-86
• “Pragmas” on page 1-99
• “GCC Compatibility Extensions” on page 1-117
1-52 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
The additional keywords that are part of these C extensions do not conflict with any ISO/ANSI C keywords. The formal definitions of these
extension keywords are prefixed with a leading double underscore. Unless
the
-no-extra-keywords command-line switch is used (see on page 1-30),
the compiler defines shorter forms of the keyword extensions that omit
the leading underscores.
This section describes only the shorter forms of the keyword extensions,
but in most cases you can use either form in your code. For example, all
references to the inline keyword in this text appear without the leading
double underscores, but you can use inline or __inline interchangeably
in your code.
You might need to use the longer forms (such as __inline) exclusively if
you are porting a program that uses the extra Analog Devices keywords as
identifiers. For example, a program might declare local variables, such as
pm or dm. In this case, you should use the -no-extra-keywords switch, and
if you need to declare a function as inline, or allocate variables to memory
spaces, you can use __inline or __pm/__dm respectively.
Table 1-5 provides a list and a brief description of keyword extensions.
Table 1-6 provides a list and a brief description of operational extensions.
Both tables direct you to sections of this chapter that document each
extension in more detail.
Table 1-5. Keyword Extensions
Keyword extensions Description
inline (function) Directs the compiler to integrate the function code into the code of
the callers. For more information, see “Inline Function Support
Keyword (inline)” on page 1-55.
dm Specifies the location of a static or global variable or qualifies a
pointer declaration “
For more information, see “Dual Memory Support Keywords (pm
dm)” on page 1-71.
*” as referring to data memory.
VisualDSP++ 3.5 C Compiler and Library Manual 1-53
for ADSP-218x DSPs
C Compiler Language Extensions
Table 1-5. Keyword Extensions (Cont’d)
Keyword extensions Description
pm Specifies the location of a static or global variable or qualifies a
pointer declaration “
For more information, see “Dual Memory Support Keywords (pm
dm)” on page 1-71.
section(string) Specifies the section in which an object or function is placed.
For more information, see “Placement Support Keyword (section)”
on page 1-76.
bool, true, false A Boolean type.
For more information, see “Boolean Type Support Keywords (bool,
true, false)” on page 1-77.
restrict keyword Specifies restricted pointer features.
For more information, see “Pointer Class Support Keyword
(restrict)” on page 1-77.
*” as referring to program memory.
Table 1-6. Operational Extensions
Operation extensions Description
Variable-length arrays Support for variable-length arrays lets you use automatic arrays
whose length is not known until runtime. For more information, see
“Variable-Length Array Support” on page 1-78.
Non-constant initializers Support for non-constant initializers lets you use non-constants as
elements of aggregate initializers for automatic variables.
For more information, see “Non-Constant Aggregate Initializer Support” on page 1-80.
Indexed initializers Support for indexed initializers lets you specify elements of an aggre-
gate initializer in an arbitrary order. For more information, see
“Indexed Initializer Support” on page 1-80.
Preprocessor generated
warnings
C++-style comments Support for C++-style comments in C programs.
Support for generating warning messages from the preprocessor.
For more information, see “Preprocessor-Generated Warnings” on
page 1-83.
For more information, see “C++-Style Comments” on page 1-83.
1-54 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
Inline Function Support Keyword (inline)
The inline keyword directs cc218x to integrate the code for the function
you declare as
and the inline keyword is a standard feature of C++; the compiler provides it as a C extension. Use of this keyword eliminates the function-call
overhead and therefore can increase the speed of your program’s execution. Argument values that are constant and that have known values may
permit simplifications at compile time.
The following example shows a function definition that uses the inline
keyword.
inline int max3 (int a, int b int c) {
return max (a, max(b, c));
}
A function declared inline must be defined (its body must be included)
in every file in which the function is used. The normal way to do this is to
place the inline definition in a header file. Usually, it will also be declared
static.
inline into the code of its callers. Inline function support
In some cases, the compiler does not output object code for the function;
for example, the address is not needed for an inline function called only
from within the defining program. However, recursive calls, and functions
whose addresses are explicitly referred to by the program, are compiled to
assembly code.
VisualDSP++ 3.5 C Compiler and Library Manual 1-55
for ADSP-218x DSPs
The compiler only inlines functions, even those declared using the
inline keyword, when optimizations are enabled (using the
switches, as described on page 1-32).
-O
C Compiler Language Extensions
Inline Assembly Language Support Keyword (asm)
The cc218x asm() construct lets you code ADSP-218x processor’s assembly language instructions within a C function and to pass declarations and
directives through to the assembler. The
expressing assembly language statements that cannot be expressed easily or
efficiently with C constructs.
The asm() keyword allows you to code complete assembly language
instructions or you can specify the operands of the instruction using C
expressions. When specifying operands with a C expression, you do not
need to know which registers or memory locations contain C variables.
asm() construct is useful for
A simplified
The complete assembly language instruction, enclosed in double quotes, is
the argument to
some additional syntax.
The compiler does not analyze code defined with the asm() construct; it passes this code directly to the assembler. The compiler
does perform substitutions for operands of the formats %0
through %9. However, it passes everything else through to the
assembler without reading or analyzing it.
The asm() constructs are executable statements, and as such, may
not appear before declarations within C functions.
asm() constructs may also be used at global scope, outside function
declarations. Such asm constructs are used to pass declarations and
directives directly to the assembler. They are not executable constructs, and may not have any inputs or outputs, or affect any
registers.
asm() construct without operands takes the form of:
asm(" ENA INTS;");
asm(). Using asm() constructs with operands requires
1-56 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
Using asm() constructs with operands requires some additional syntax.
The construct syntax is described in:
Note that the compiler generates a label before and after inline
assembly instructions when generating debug code (-g switch).
These labels are used to generate the debug line information used
by the debugger. If the inline assembler inserts conditionally
assembled code, then likely at link time, an undefined symbol error
will occur. If the inline assembler changes the section, causing the
compilers labels to be placed, for example, in a data section
(instead of the default code section), then the debug line information will be incorrect for these lines.
• “Assembly Construct Template” on page 1-57
• “Assembly Construct Operand Description” on page 1-61
• “Assembly Constructs With Multiple Instructions” on page 1-67
• “Assembly Construct Reordering and Optimization” on page 1-67
• “Assembly Constructs with Input and Output Operands” on
page 1-68
• “Assembly Constructs and Macros” on page 1-70
• “Assembly Constructs and Flow Control” on page 1-70
Assembly Construct Template
Using
instruction using C expressions. You do not need to know which registers
or memory locations contain C variables.
ASM() Construct Syntax:
Use the following general syntax for your asm() constructs.
VisualDSP++ 3.5 C Compiler and Library Manual 1-57
for ADSP-218x DSPs
asm() constructs, you can specify the operands of the assembly
C Compiler Language Extensions
asm(
template
[:[constraint(output operand)[,constraint(output operand)…]]
[:[constraint(input operand)[,constraint(input operand)…]]
[:clobber]]]
);
The syntax elements are defined as:
template
The template is a string containing the assembly instruction(s) with
%number indicating where the compiler should substitute the oper-
ands. Operands are numbered in order of occurrence from left to
right, starting at 0. Separate multiple instructions with a semicolon; then enclose the entire string within double quotes.
For more information on templates containing multiple instructions, see “Assembly Constructs With Multiple Instructions” on
page 1-67.
constraint
The constraint is a string that directs the compiler to use certain
groups of registers for the input and output operands. Enclose the
constraint string within double quotes. For more information on
operand constraints, see “Assembly Construct Operand Descrip-
tion” on page 1-61.
output operand
The output operand is the name of a C variable that receives output from a corresponding operand in the assembly instruction.
input operand
The input operand is a C expression that provides an input to a
corresponding operand in the assembly instruction.
1-58 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
clobber
The clobber notifies the compiler that a list of registers are overwritten by the assembly instructions. Use lowercase characters to
name clobbered registers. Enclose each name within double quotes,
and separate each quoted register name with a comma. The input
and output operands are guaranteed not to use any of the clobbered
registers, so you can read and write the clobbered registers as often
as you like. See Table 1-8 on page 1-66.
ASM() Construct Syntax Rules
These rules apply to assembly construct template syntax:
• The template is the only mandatory argument to asm(). All other
arguments are optional.
• An operand constraint string followed by a C expression in parentheses describes each operand. For output operands, it must be
possible to assign to the expression—that is, the expression must be
legal on the left side of an assignment statement.
Compiler
• A colon separates:
• The template from the first output operand
• The last output operand from the first input operand
• The last input operand from the clobbered registers
• A comma separates operands and registers within arguments.
• The number of operands in arguments must match the number of
operands in your template.
• The maximum permissible number of operands is ten (
%3, %4, %5, %6, %7, %8, and %9).
%0, %1, %2,
VisualDSP++ 3.5 C Compiler and Library Manual 1-59
for ADSP-218x DSPs
C Compiler Language Extensions
that are reasonable for the instruction being executed. The compiler does not parse the assembler instruction template, interpret
the template, nor verify whether the template contains valid input
for the assembler.
ASM() Construct Template Example
The following example shows how to apply the asm() construct template
to the ADSP-218x assembly language abs instruction:
The compiler cannot check whether the operands have data types
{
int result, x;
…
asm (
"%0 = abs %1;" :
"=d" (result) :
"d" (x)
);
}
In the previous example, note the following points:
• The template is "%0=abs %1;". The %0 is replaced with operand
zero (result), the first operand. The %1 is replaced with operand
one (x).
• The output operand is the C variable result.
The letter
c is the operand constraint for the variable. This con-
strains the output to an ALU result register. The compiler generates
code to copy the output from the register to the variable result, if
necessary. The “=” in =c indicates that the operand is an output.
• The input operand is the C variable x.
The letter c is the operand constraint for the variable. This con-
1-60 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Compiler
strains
registers or in memory, the compiler generates code to copy the
values into an register before the asm() construct uses them.
Assembly Construct Operand Description
The second and third arguments to the asm() construct describe the operands in the assembly language template. There are several pieces of
information that need to be conveyed for cc218x to know how to assign
registers to operands. This information is conveyed with an operand constraint. The compiler needs to know what kind of registers the assembly
instructions can operate on, so it can allocate the correct register type.
You convey this information with a letter in the operand constraint string
which describes the class of allowable registers. Table 1-7 on page 1-65
describes the correspondence between constraint letters and register
classes.
The use of any letter not listed in Table 1-7 results in unspecified
behavior. The compiler does not check the validity of the code by
using the constraint letter.
For example, if your assembly template contains “ax1 = dm(%0
+= m3);” and the address you want to load from is in the variable
p, the compiler needs to know that it should put p in a DAG1 I reg-
ister (I0–I3) before it generates your instruction. You convey this
information to
“w” is the constraint letter for DAG1I registers.
x to an ALU register. If x is stored in different kinds of
cc218x by specifying the operand “w” (p) where
To assign registers to the operands, the compiler must also be told which
operands in an assembly language instruction are inputs, which are outputs, and which outputs may not overlap inputs. The compiler is told this
in three ways.
VisualDSP++ 3.5 C Compiler and Library Manual 1-61
for ADSP-218x DSPs
C Compiler Language Extensions
• The output operand list appears as the first argument after the
assembly language template. The list is separated from the assembly
language template with a colon. The input operands are separated
from the output operands with a colon and always follow the output operands.
• The operand constraints describe which registers are modified by
an assembly language instruction. The
cates that the operand is an output; all output operand constraints
must use =.
• The compiler may allocate an output operand in the same register
as an unrelated input operand, unless the output operand has the
&= constraint modifier. This situation can occur because the com-
piler assumes that the inputs are consumed before the outputs are
produced.
“=” in =constraint indi-
This assumption may be false if the assembler code actually consists
of more than one instruction. In such a case, use &= for each output
operand that must not overlap an input or supply an “&” for the
input operand. Table 1-7 lists operand constrains.
Operand constraints indicate what kind of operand they describe by
means of preceding symbols. The possible preceding symbols are: no symbol, =, +, &, ?, and #.
•(no symbol)
The operand is an input. It must appear as part of the third
argument to the
asm() construct. The allocated register will
be loaded with the value of the C expression before the
asm() template is executed. Its C expression will not be
modified by the
asm(), and its value may be a constant or
literal. Example: d
1-62 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
• = symbol
The operand is an output. It must appear as part of the second argument to the
template has been executed, the value in the allocated register is stored into the location indicated by its C expression;
therefore, the expression must be one that would be valid as
the left-hand side of an assignment.
Example: =d
• + symbol
The operand is both an input and an output. It must appear
as part of the second argument to the asm() construct. The
allocated register is loaded with the C expression value, the
asm() template is executed, and then the allocated register’s
new value is stored back into the C expression. Therefore, as
with pure outputs, the C expression must be one that is
valid on the left-hand side of an assignment.
Example: +d
Compiler
asm() construct. Once the asm()
• ? symbol
The operand is temporary. It must appear as part of the
third argument to the asm() construct. A register is allo-
cated as working space for the duration of the
asm()
template execution. The register’s initial value is undefined,
and the register’s final value is discarded. The corresponding
C expression is not loaded into the register, but must be
present. This expression is normally specified using a literal
zero. Example: ?d
• & symbol
This operand constraint may be applied to inputs and outputs. It indicates that the register allocated to the input (or
output) may not be one of the registers that are allocated to
VisualDSP++ 3.5 C Compiler and Library Manual 1-63
for ADSP-218x DSPs
C Compiler Language Extensions
the outputs (or inputs). This operand constraint is used
when one or more output registers are set while one or more
inputs are still to be referenced. (This situation sometimes
occurs if the
asm() template contains more than one
instruction.)
Example: &d
• # symbol
The operand is an input, but the register's value is clobbered
by the asm() template execution. The compiler may make
no assumptions about the register's final value. The operand
must appear as part of the second argument to the asm()
construct.
Example: #d
Table 1-7 lists the registers that may be allocated for each register con-
straint letter. The use of any letter not listed in the “Constraint” column
of this table results in unspecified behavior. The compiler does not check
the validity of the code by using the constraint letter. Table 1-8 on
page 1-66 lists the registers that may be named as part of the clobber list.
It is also possible to claim registers directly, instead of requesting a register
from a certain class using the constraint letters. You can claim the registers
directly by simply naming the register in the location where the class letter
would be. The register names are the same as those used to specify the
clobber list; see Table 1-8.
For example,
asm("%0 = %1 + %2;”
:"=ar"(sum)/* output */
:"g"(x),"G"(y)/* input*/
);
would load x into ALU-X register, y into ALU-Y register, and sum will be cal-
culated in register
AR.
1-64 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Table 1-7. ASM() Operand Constraints
Compiler
Constraint
1
b input xregs to MAC
Description
Registers
MX1, MX0, SR1, SR0, MR1,
MR0, AR
B input yregs to MAC MY1, MY0
c results from ALU AR
C result from int multiplies MR0
cc Used in the clobber list to tell the
ASTAT
compiler that condition codes have
been clobbered
d input xregs to SHIFTER SI, SR1, SR0, MR1, MR0, AR
D result from shift SR1
e data registers, size 16 SI, AX1, AX0, MX1, MX0,
MY0, MY1, AY1, AY0, MR1,
MR0, SR1, SR0, AR
fshift amount SE
g ALU X registers AX1 AX0 AR SR1 SR0 MR1 MR0
GALU Y registers AY1 AY0
memory Used in the clobber list to tell the
compiler that the
asm() statement
writes to memory
r all registers
SR1, SR0, SI, MY1, MX1,
AY1, AX1, MY0, MX0, AY0,
AX0, MR1, MR0, AR, I0-I7,
M0-M7, L0-L7
uDAG1 L registers L0-L3
vDAG2 L registersL4-L7
wDAG1 I registersI0-I3
xDAG1 M registersM0-M3
yDAG2 I registersI4-I7
VisualDSP++ 3.5 C Compiler and Library Manual 1-65
for ADSP-218x DSPs
C Compiler Language Extensions
Table 1-7. ASM() Operand Constraints (Cont’d)
Constraint
1
Description
Registers
zDAG2 M registersM4-M7
=&constraint Indicates that the constraint is applied to an output operand that may
not overlap an input operand
=constraint Indicates that the constraint is applied to an output operand
&constraint Indicates the constraint is applied to an input operand that may not be
overlapped with an output operand
=&constraint Indicates the constraint is applied to an output operand that may not
overlap an input operand
?constraint Indicates the constraint is temporary
+constraint Indicates the constraint is both an input and output operand
1 The use of any letter not listed here results in unspecified behavior. The compiler does not check
the validity of the code by using the constraint letter.
Table 1-8. Register Names for asm() Constructs
Clobber String Meaning
"AX1", "AX0", "AY1", "AY0", "AR", "AF" ALU registers
"MX1", "MX0", "MY1", "MY0", "MR1", "MR0", "MR2", MF
MAC registers
"SI", "SE", "SR1", "SR0", "SB", "SR2" SHIFTER registers
"I0", "I1", "I2", "I3", "I6", "I7" DAG addressing registers
"M0", "M3", "M5” Modifier registers
"L0", "L1", "L2", "L3", "L5", "L6", "L7" Length register
"PX" PMD-DMD bus exchange regis-
ter
"astat" ALU status registers
"MSTAT", "MMODE", "SSTAT" Mode control registers
"IMASK", "ICNTL", "IFC" Interrupt registers
1-66 VisualDSP++ 3.5 C Compiler and Library Manual
for ADSP-218x DSPs
Loading...