a
W5.0
Assembler and Preprocessor Manual
Revision 3.2, March 2009
Part Number:
82-000420-04
Analog Devices, Inc.
One Technology Way
Norwood, Mass. 02062-9106
Copyright Information
© 2009 Analog Devices, Inc., ALL RIGHTS RESERVED. This document may not be reproduced in any form without prior, express written
consent from Analog Devices, Inc.
Printed in the USA.
Disclaimer
Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by implication or otherwise under the patent rights of Analog Devices, Inc.
Trademark and Service Mark Notice
The Analog Devices logo, VisualDSP++, Blackfin, SHARC, and TigerSHARC are registered trademarks of Analog Devices, Inc.
All other brand and product names are trademarks or service marks of
their respective owners.
CONTENTS
PREFACE
Purpose ......................................................................................... xiii
Intended Audience ........................................................................ xiii
Manual Contents ........................................................................... xiv
What’s New in this Manual ............................................................ xiv
Technical or Customer Support ....................................................... xv
Supported Processors ...................................................................... xvi
Product Information ...................................................................... xvi
Analog Devices Web Site .......................................................... xvi
VisualDSP++ Online Documentation ...................................... xvii
Technical Library CD ............................................................. xviii
Notation Conventions .................................................................. xviii
ASSEMBLER
Assembler Guide ........................................................................... 1-2
Assembler Overview ................................................................ 1-3
Writing Assembly Programs ..................................................... 1-4
Program Content ................................................................ 1-6
Assembly Instructions ..................................................... 1-6
VisualDSP++ 5.0 Assembler and Preprocessor Manual iii
CONTENTS
Assembler Directives ....................................................... 1-6
Preprocessor Commands ................................................. 1-7
Program Structure .............................................................. 1-7
Code File Structure for SHARC Processors .................... 1-10
LDF for SHARC Processors .......................................... 1-10
Code File Structure for TigerSHARC Processors ............ 1-13
LDF for TigerSHARC Processors .................................. 1-13
Code File Structure for Blackfin Processors .................... 1-17
LDF for Blackfin Processors .......................................... 1-18
Program Interfacing Requirements .................................... 1-20
Using Assembler Support for C Structs .................................. 1-21
Preprocessing a Program ........................................................ 1-24
Using Assembler Feature Macros ........................................... 1-25
-D__VISUALDSPVERSION__ Predefined Macro ............ 1-31
Generating Make Dependencies ............................................ 1-33
Reading a Listing File ............................................................ 1-34
Enabling Statistical Profiling for Assembly Functions ............. 1-35
Assembler Syntax Reference ........................................................ 1-37
Assembler Keywords and Symbols ......................................... 1-38
Assembler Expressions ........................................................... 1-50
Assembler Operators ............................................................. 1-51
Numeric Formats .................................................................. 1-56
Representation of Constants in Blackfin ............................ 1-56
Fractional Type Support .................................................... 1-57
iv VisualDSP++ 5.0 Assembler and Preprocessor Manual
CONTENTS
1.31 Fracts .................................................................... 1-58
1.0r Special Case ........................................................... 1-59
Fractional Arithmetic .................................................... 1-59
Mixed Type Arithmetic ................................................. 1-59
Comment Conventions ......................................................... 1-60
Conditional Assembly Directives ............................................ 1-60
C Struct Support in Assembly Built-In Functions ................... 1-63
OFFSETOF Built-In Function .......................................... 1-63
SIZEOF Built-In Function ................................................ 1-63
Struct References ................................................................... 1-64
Assembler Directives .............................................................. 1-67
.ALIGN, Specify an Address Alignment ............................. 1-72
.ALIGN_CODE, Specify an Address Alignment ................ 1-74
.ASCII .............................................................................. 1-76
.BYTE, Declare a Byte Data Variable or Buffer .................. 1-77
ASCII String Initialization Support ............................... 1-79
.COMPRESS, Start Compression ...................................... 1-81
.EXTERN, Refer to a Globally Available Symbol ............... 1-82
.EXTERN STRUCT, Refer to a Struct Defined Elsewhere . 1-83
.FILE, Override the Name of a Source File ........................ 1-85
.FILE_ATTR, Create an Attribute in the Object File ......... 1-86
.FORCECOMPRESS, Compress the Next Instruction ....... 1-87
.GLOBAL, Make a Symbol Available Globally ................... 1-88
.IMPORT, Provide Structure Layout Information .............. 1-90
VisualDSP++ 5.0 Assembler and Preprocessor Manual v
CONTENTS
.INC/BINARY, Include Contents of a File ........................ 1-92
.LEFTMARGIN, Set the Margin Width of a Listing File ... 1-93
.LIST/.NOLIST, Listing Source Lines and Opcodes .......... 1-94
.LIST_DATA/.NOLIST_DATA, Listing Data Opcodes ..... 1-95
.LIST_DATFILE/.NOLIST_DATFILE, Listing Data
Initialization Files ........................................................ 1-96
.LIST_DEFTAB, Set the Default Tab Width for Listings ... 1-97
.LIST_LOCTAB, Set the Local Tab Width for Listings ...... 1-99
.LIST_WRAPDATA/.NOLIST_WRAPDATA ................ 1-100
.LONG, Defines and initializes 4-byte data objects .......... 1-101
.MESSAGE, Alter the Severity of an Assembler Message .. 1-102
.NEWPAGE, Insert a Page Break in a Listing File ............ 1-106
.NOCOMPRESS, Terminate Compression ..................... 1-107
.PAGELENGTH, Set the Page Length of a Listing File .... 1-108
.PAGEWIDTH, Set the Page Width of a Listing File ....... 1-109
.PORT, Legacy Directive ................................................. 1-111
.PRECISION, Select Floating-Point Precision ................. 1-112
.PREVIOUS, Revert to the Previously Defined Section ... 1-114
.PRIORITY, Allow Prioritized Symbol Mapping in Linker 1-115
Linker Operation ........................................................ 1-116
.REFERENCE, Provide Better Info in an X-REF File ...... 1-118
.RETAIN_NAME, Stop Linker from Eliminating Symbol 1-118
.ROUND_, Select Floating-Point Rounding .................... 1-119
.SECTION, Declare a Memory Section .......................... 1-122
Common .SECTION Attributes ................................. 1-122
vi VisualDSP++ 5.0 Assembler and Preprocessor Manual
CONTENTS
DOUBLE* Qualifiers .................................................. 1-123
TigerSHARC-Specific Qualifiers .................................. 1-124
SHARC-Specific Qualifiers .......................................... 1-125
Initialization Section Qualifiers ................................... 1-126
.SEGMENT and .ENDSEG, Legacy Directives ............... 1-128
.SEPARATE_MEM_SEGMENTS ................................... 1-128
.SET, Set a Symbolic Alias ............................................... 1-129
.SHORT, Defines and initializes 2-byte data objects ......... 1-129
.STRUCT, Create a Struct Variable ................................. 1-130
.TYPE, Change Default Symbol Type .............................. 1-134
.VAR, Declare a Data Variable or Buffer .......................... 1-135
.VAR and ASCII String Initialization Support .............. 1-138
.WEAK, Support Weak Symbol Definition and Reference 1-140
Assembler Command-Line Reference ......................................... 1-141
Running the Assembler ........................................................ 1-142
Assembler Command-Line Switch Descriptions .................... 1-144
-align-branch-lines .......................................................... 1-149
-anomaly-detect [id1[,id2...]] .......................................... 1-149
-anomaly-warn {id1[,id2]|all|none} .................................. 1-149
-anomaly-workaround [id] .............................................. 1-150
-char-size-8 ..................................................................... 1-151
-char-size-32 ................................................................... 1-151
-char-size-any .................................................................. 1-151
-default-branch-np .......................................................... 1-151
VisualDSP++ 5.0 Assembler and Preprocessor Manual vii
CONTENTS
-default-branch-p ........................................................... 1-152
-Dmacro[=definition] ..................................................... 1-152
-double-size-32 ............................................................... 1-152
-double-size-64 ............................................................... 1-153
-double-size-any ............................................................. 1-153
-expand-symbolic-links ................................................... 1-153
-expand-windows-shortcuts ............................................. 1-154
-file-attr attr[=val] .......................................................... 1-154
-flags-compiler ................................................................ 1-154
-flags-pp -opt1 [,-opt2...] ............................................... 1-156
User-Specified Defines Options ................................... 1-155
Include Options ......................................................... 1-155
-g ................................................................................... 1-156
WARNING ea1121: Missing End Labels ..................... 1-157
-h[elp] ............................................................................ 1-158
-i .................................................................................... 1-158
-l filename ...................................................................... 1-159
-li filename ..................................................................... 1-159
-M ................................................................................. 1-160
-MM .............................................................................. 1-160
-Mo filename .................................................................. 1-161
-Mt filename .................................................................. 1-161
-micaswarn ..................................................................... 1-161
-no-source-dependency ................................................... 1-161
viii VisualDSP++ 5.0 Assembler and Preprocessor Manual
CONTENTS
-no-anomaly-detect [id1[,id2...]] ..................................... 1-162
-no-anomaly-workaround [id1[,id2...]] ............................ 1-162
-no-expand-symbolic-links .............................................. 1-162
-no-expand-windows-shortcuts ........................................ 1-163
-no-temp-data-file ........................................................... 1-163
-normal-word-code or -nwc ............................................. 1-163
-o filename ..................................................................... 1-164
-pp ................................................................................. 1-164
-proc processor ................................................................ 1-164
-save-temps ..................................................................... 1-165
-short-word-code or -swc ................................................. 1-165
-si-revision version .......................................................... 1-165
-sp .................................................................................. 1-166
-stallcheck ....................................................................... 1-166
-swc-exclude name1[,name2] ........................................... 1-167
-v[erbose] ....................................................................... 1-167
-version .......................................................................... 1-167
-w ................................................................................... 1-167
-Werror number[,number] .............................................. 1-168
-Winfo number[,number] ............................................... 1-168
-Wno-info ...................................................................... 1-168
-Wnumber[,number] ....................................................... 1-168
-Wsuppress number[,number] ......................................... 1-169
-Wwarn number[,number] .............................................. 1-169
VisualDSP++ 5.0 Assembler and Preprocessor Manual ix
CONTENTS
-Wwarn-error ................................................................. 1-169
Specifying Assembler Options in VisualDSP++ .................... 1-170
PREPROCESSOR
Preprocessor Guide ....................................................................... 2-2
Writing Preprocessor Commands ............................................. 2-3
Header Files and #include Command ...................................... 2-4
System Header Files ............................................................ 2-5
User Header Files ............................................................... 2-5
Sequence of Tokens ............................................................ 2-6
Include Path Search ............................................................ 2-7
Writing Macros ....................................................................... 2-7
Macro Definition and Usage Guidelines .............................. 2-9
Examples of Multi-Line Code Macros with Arguments ...... 2-12
Debugging Macros ........................................................... 2-13
Using Predefined Preprocessor Macros ................................... 2-15
-D__VISUALDSPVERSION____ Predefined Macro (Preprocessor)
2-21
Specifying Preprocessor Options ............................................ 2-21
Preprocessor Command Reference ............................................... 2-22
Preprocessor Commands and Operators ................................. 2-22
#define ............................................................................. 2-24
Variable-Length Argument Definitions .......................... 2-25
#elif ................................................................................. 2-27
#else ................................................................................. 2-28
x VisualDSP++ 5.0 Assembler and Preprocessor Manual
CONTENTS
#endif ............................................................................... 2-29
#error ............................................................................... 2-30
#if .................................................................................... 2-31
#ifdef ................................................................................ 2-32
#ifndef .............................................................................. 2-33
#include ........................................................................... 2-34
#line ................................................................................. 2-36
#pragma ........................................................................... 2-37
#undef .............................................................................. 2-38
#warning .......................................................................... 2-39
# (Argument) .................................................................... 2-40
## (Concatenate) .............................................................. 2-42
? (Generate a unique label) ................................................ 2-43
Preprocessor Command-Line Reference ....................................... 2-45
Running the Preprocessor ...................................................... 2-45
Preprocessor Command-Line Switches ................................... 2-46
-cpredef ............................................................................ 2-48
-cs! ................................................................................... 2-49
-cs/* .................................................................................. 2-49
-cs// .................................................................................. 2-50
-cs{ ................................................................................... 2-50
-csall ................................................................................. 2-50
-Dmacro[=def] ................................................................. 2-50
-h[elp] .............................................................................. 2-50
VisualDSP++ 5.0 Assembler and Preprocessor Manual xi
CONTENTS
-i ...................................................................................... 2-51
-i ...................................................................................... 2-51
-I- .................................................................................... 2-52
-M ................................................................................... 2-53
-MM ................................................................................ 2-53
-Mo filename .................................................................... 2-53
-Mt filename .................................................................... 2-54
-o filename ....................................................................... 2-54
-stringize .......................................................................... 2-54
-tokenize-dot .................................................................... 2-54
-Uname ............................................................................ 2-55
-v[erbose] ......................................................................... 2-55
-version ............................................................................ 2-55
-w .................................................................................... 2-55
-Wnumber ....................................................................... 2-56
-warn ............................................................................... 2-56
INDEX
xii VisualDSP++ 5.0 Assembler and Preprocessor Manual
PREFACE
Thank you for purchasing Analog Devices, Inc. development software for
digital signal processing (DSP) applications.
Purpose
The VisualDSP++ 5.0 Assembler and Preprocessor Manual contains infor-
mation about the assembler and preprocessor utilities for the following
Analog Devices, Inc. processor families—Blackfin® (ADSP-BFxxx),
SHARC® (ADSP-21xxx), and TigerSHARC® (ADSP-TSxxx) processors.
The manual describes how to write assembly programs for these processors
and provides reference information about related development software.
It also provides information on new and legacy syntax for assembler and
preprocessor directives and comments, as well as command-line switches.
Intended Audience
The primary audience for this manual is a programmer who is familiar
with Analog Devices processors. This manual assumes that the audience
has a working knowledge of the appropriate processor architecture and
instruction set. Programmers who are unfamiliar with Analog Devices
processors can use this manual, but should supplement it with other texts
(such as the appropriate hardware reference and programming reference
manuals) that describe your target architecture.
VisualDSP++ 5.0 Assembler and Preprocessor Manual xiii
Manual Contents
Manual Contents
The manual consists of:
• Chapter 1, “Assembler”
Provides an overview of the process of writing and building
assembly programs. It also provides information about assembler
switches, expressions, keywords, and directives.
• Chapter 2, “Preprocessor”
Provides procedures for using preprocessor commands within
assembly source files as well as the preprocessor’s command-line
interface options and command sets.
What’s New in this Manual
This revision of the VisualDSP++ 5.0 Assembler and Preprocessor Manual
documents assembler and preprocessor functionality that is new to VisualDSP++® 5.0 and updates (up to update 6), including support for new
ADSP-2146x SHARC processors.
In addition, modifications and corrections based on errata reports against
the previous revision of the manual have been made.
xiv VisualDSP++ 5.0 Assembler and Preprocessor Manual
Technical or Customer Support
You can reach Analog Devices, Inc. Customer Support in the following
ways:
• Visit the Embedded Processing and DSP products Web site at
http://www.analog.com/processors/technical_support
• E-mail tools questions to
processor.tools.support@analog.com
• E-mail processor questions to
processor.support@analog.com (World wide support)
processor.europe@analog.com (Europe support)
processor.china@analog.com (China support)
• Phone questions to 1-800-ANALOGD
Preface
• Contact your Analog Devices, Inc. local sales office or authorized
distributor
• Send questions by mail to:
Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
USA
VisualDSP++ 5.0 Assembler and Preprocessor Manual xv
Supported Processors
Supported Processors
The assembler and preprocessor of VisualDSP++ 5.0 supports the following Analog Devices, Inc. processors.
• Blackfin (ADSP-BFxxx)
• SHARC (ADSP-21xxx)
• TigerSHARC (ADSP-TSxxx)
The majority of the information in this manual applies to all processors.
For a complete list of processors supported by VisualDSP++ 5.0, refer to
the online Help.
Product Information
Product information can be obtained from the Analog Devices Web site,
VisualDSP++ online Help system, and a technical library CD.
Analog Devices Web Site
The Analog Devices Web site, www.analog.com, provides information
about a broad range of products—analog integrated circuits, amplifiers,
converters, and digital signal processors.
To access a complete technical library for each processor family, go to
http://www.analog.com/processors/technical_library. The manuals
selection opens a list of current manuals related to the product as well as a
link to the previous revisions of the manuals. When locating your manual
title, note a possible errata check mark next to the title that leads to the
current correction report against the manual.
xvi VisualDSP++ 5.0 Assembler and Preprocessor Manual
Preface
Also note,
MyAnalog.com is a free feature of the Analog Devices Web site
that allows customization of a Web page to display only the latest information about products you are interested in. You can choose to receive
weekly e-mail notifications containing updates to the Web pages that meet
your interests, including documentation errata against all manuals. MyAn-
alog.com
provides access to books, application notes, data sheets, code
examples, and more.
Visit MyAnalog.com to sign up. If you are a registered user, just log on.
Your user name is your e-mail address.
VisualDSP++ Online Documentation
Online documentation comprises the VisualDSP++ Help system, software
tools manuals, hardware tools manuals, processor manuals, Dinkum
Abridged C++ library, and FLEXnet License Tools documentation. You
can search easily across the entire VisualDSP++ documentation set for any
topic of interest.
For easy printing, supplementary Portable Documentation Format (.pdf)
files for all manuals are provided on the VisualDSP++ installation CD.
Each documentation file type is described as follows.
File Description
.chm Help system files and manuals in Microsoft help format
.htm or
.html
.pdf VisualDSP++ and processor manuals in PDF format. Viewing and printing the
Dinkum Abridged C++ library and FLEXnet license tools software
documentation. Viewing and printing the .html files requires a browser, such as
Internet Explorer 6.0 (or higher).
.pdf files requires a PDF reader, such as Adobe Acrobat Reader (4.0 or higher).
VisualDSP++ 5.0 Assembler and Preprocessor Manual xvii
Notation Conventions
Technical Library CD
The technical library CD contains seminar materials, product highlights,
a selection guide, and documentation files of processor manuals, VisualDSP++ software manuals, and hardware tools manuals for the following
processor families: Blackfin, SHARC, TigerSHARC, ADSP-218x, and
ADSP-219x.
To order the technical library CD, go to http://www.analog.com/proces-
sors/technical_library
processor, click the request CD check mark, and fill out the order form.
Data sheets, which can be downloaded from the Analog Devices Web site,
change rapidly, and therefore are not included on the technical library
CD. Technical manuals change periodically. Check the Web site for the
latest manual revisions and associated documentation errata.
, navigate to the manuals page for your
Notation Conventions
Text conventions used in this manual are identified and described as
follows.
L
Example Description
Close command
(File menu)
{this | that} Alternative required items in syntax descriptions appear within curly
[this | that] Optional items in syntax descriptions appear within brackets and sepa-
xviii VisualDSP++ 5.0 Assembler and Preprocessor Manual
Additional conventions, which apply only to specific chapters, may
appear throughout this document.
Titles in in bold style reference sections indicate the location of an item
within the VisualDSP++ environment’s menu system (for example, the
Close command appears on the File menu).
brackets and separated by vertical bars; read the example as
that. One or the other is required.
rated by vertical bars; read the example as an optional
this or
this or that.
Preface
L
a
[
Example Description
[this,…] Optional item lists in syntax descriptions appear within brackets
delimited by commas and terminated with an ellipse; read the example
as an optional comma-separated list of
.SECTION Commands, directives, keywords, and feature names are in text with
letter gothic font.
filename Non-keyword placeholders appear in text with italic style format.
Note: For correct operation, ...
A Note provides supplementary information on a related topic. In the
online version of this book, the word Note appears instead of this
symbol.
Caution: Incorrect device operation may result if ...
Caution: Device damage may result if ...
A Caution identifies conditions or inappropriate usage of the product
that could lead to undesirable results or product damage. In the online
version of this book, the word Caution appears instead of this symbol.
Warn in g: Injury to device users may result if ...
A Warning identifies conditions or inappropriate usage of the product
that could lead to conditions that are potentially hazardous for devices
users. In the online version of this book, the word Wa rning appears
instead of this symbol.
this.
VisualDSP++ 5.0 Assembler and Preprocessor Manual xix
Notation Conventions
xx VisualDSP++ 5.0 Assembler and Preprocessor Manual
1 ASSEMBLER
This chapter provides information on how to use the assembler to develop
and assemble programs for SHARC (ADSP-21xxx), TigerSHARC
(ADSP-TSxxx), and Blackfin (ADSP-BFxxx) processors.
The chapter contains the following sections:
• “Assembler Guide” on page 1-2
Describes how to develop new programs using the processor’s
assembly language
• “Assembler Syntax Reference” on page 1-37
Provides the assembler rules and conventions of syntax used to
define symbols (identifiers), expressions, and to describe different
numeric and comment formats
• “Assembler Command-Line Reference” on page 1-141
Provides reference information on the assembler’s switches and
conventions
L
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-1
The code examples in this manual have been compiled using
VisualDSP++ 5.0 The examples compiled with other versions of
VisualDSP++ may result in build errors or different output
although the highlighted algorithms stand and should continue to
stand in future releases of VisualDSP++.
Assembler Guide
Assembler Guide
In VisualDSP++ 5.0, you can run the assembler drivers for each processor
family from the VisualDSP++ integrated debugging and development
environment (IDDE) or from an operating system command line The
assembler processes assembly source, data, and header files to produce an
object file. Assembler operations depend on two types of controls:
assembler directives and assembler switches.
VisualDSP++ 5.0 supports the following assembler drivers.
• easm21k.exe (for SHARC processors)
• easmts.exe (for TigerSHARC processors)
• easmblkfn.exe (for Blackfin processors)
This section describes how to develop new programs in the Analog
Devices processor assembly language. It provides information on how to
assemble your programs from the operating system’s command line.
Software developers using the assembler should be familiar with these
topics:
• “Writing Assembly Programs” on page 1-4
• “Using Assembler Support for C Structs” on page 1-21
• “Preprocessing a Program” on page 1-24
• “Using Assembler Feature Macros” on page 1-25
• “Generating Make Dependencies” on page 1-33
• “Reading a Listing File” on page 1-34
1-2 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
• “Enabling Statistical Profiling for Assembly Functions” on
page 1-35
• “Specifying Assembler Options in VisualDSP++” on page 1-170
For information about a processor’s architecture, including the instruction
set used when writing assembly programs, refer to the Hardware Reference
and the Programming Reference for the appropriate processor.
Assembler Overview
The assembler processes data from assembly source (.asm), data (.dat),
and header (.h) files to generate object files in executable and linkable
format (ELF), an industry-standard format for binary object files. The
object file has a .doj extension.
In addition to the object file, the assembler can produce a listing file
(.lst) that shows the correspondence between the binary code and the
source.
Assembler switches are specified from the VisualDSP++ IDDE or from the
command line used to invoke the assembler. These switches allow you to
control the assembly process of source, data, and header files. Use these
switches to enable and configure assembly features, such as search paths,
output file names, and macro preprocessing. For more information, see
“Assembler Command-Line Reference” on page 1-141.
You can also set assembler options via the Assemble page of the Project
Options dialog box in VisualDSP++. For more information, see “Specify-
ing Assembler Options in VisualDSP++” on page 1-170.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-3
Assembler Guide
Writing Assembly Programs
Assembler directives are coded in assembly source files. The directives
allow you to define variables, set up hardware features, and identify program sections for placement within processor memory. The assembler uses
directives for guidance as it translates a source program into object code.
Write assembly language programs using the VisualDSP++ editor or any
editor that produces text files. Do not use a word processor that embeds
special control codes in the text. Use an .asm extension to source file
names to identify them as assembly source files.
Figure 1-1 shows a graphical overview of the assembly process. The figure
shows the preprocessor processing the assembly source (.asm) and header
(.h) files.
Assemble your source files from the VisualDSP++ environment or using
any mechanism, such as a batch file or makefile, that supports invoking an
appropriate assembler driver with a specified command-line command.
By default, the assembler processes an intermediate file to produce a
binary object file (.doj) and an optional listing file (.lst).
Object files produced by the processor assembler may be used as input to
the linker and archiver. You can archive the output of an assembly process
into a library file (.dlb), which can then be linked with other objects into
an executable. Use the linker to combine separately assembled object files
and objects from library files to produce an executable file. For more
information about the linker and archiver, refer to the VisualDSP++ 5.0
Linker and Utilities Manual.
A binary object file (
.doj) and an optional listing (.lst) file are final
results of the successful assembly.
The assembler listing file is a text file read for information on the results
of the assembly process. The listing file also provides information about
the imported C data structures. The listing file tells which imports were
used within the program, followed by a more detailed section. (See the
1-4 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Assembler
Preprocessor
Intermediate
preprocessed
file (.IS)
Assembly source file
(.ASP)
Data initialization file
(.DAT)
Header file
(.H)
Listing file
(.LST)
Object file
(.OBJ)
Figure 1-1. Assembler Input and Output Files
.IMPORT directive on page 1-90.) The file shows the name, total size, and
layout with offset for the members. The information appears at the end of
the listing. You must specify the -l switch (on page 1-159) to produce a
listing file.
The assembly source file may contain preprocessor commands, such as
#include
source program. The preprocessor’s only output, an intermediate source
file (
preprocessor output is a temporary file that is deleted during the assembly
process.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-5
, that cause the preprocessor to include header files (.h) into the
.is), is the assembler’s primary input. In normal operation, the
Assembler Guide
Program Content
Assembly source file statements include assembly instructions, assembler
directives, and preprocessor commands.
Assembly Instructions
Instructions adhere to the processor’s instruction set syntax, which is
documented in the processor’s Programming Reference. Each instruction
line must be terminated by a semicolon (;). On TigerSHARC processors,
each instruction line (which can contain up to 4 instructions) is terminated by an additional semicolon (;;). Figure 1-2 on page 1-8 shows an
example assembly source file.
To mark the location of an instruction, place an address label at the beginning of an instruction line or on the preceding line. End the label with a
colon (:) before beginning the instruction. Your program can then refer to
this memory location using the label instead of an address. The assembler
places no restriction on the number of characters in a label.
Labels are case sensitive. The assembler treats “outer” and “Outer” as
unique labels. For example (in Blackfin processors),
outer: [I1] = R0;
Outer: R1 = 0X1234;
JUMP outer; // jumps back 2 instructions
Assembler Directives
Assembler directives begin with a period (.) and end with a semicolon (;).
The assembler does not differentiate between directives in lowercase or
uppercase.
L
1-6 VisualDSP++ 5.0 Assembler and Preprocessor Manual
This manual prints directives in uppercase to distinguish them
from other assembly statements.
Assembler
For example (Blackfin processors):
.SECTION data1;
.BYTE2 sqrt_coeff[2] = 0x5D1D, 0xA9ED;
For a complete description of the assembler’s directive set, see “Assembler
Directives” on page 1-67.
Preprocessor Commands
Preprocessor commands begin with a pound sign (#) and end with a
carriage return. The pound sign must be the first non-white space
character on the line containing the command. If the command is longer
than one line, use a backslash (\) and a carriage return to continue the
command onto the next line.
Do not put any characters between the backslash and the carriage return.
Unlike assembler directives, preprocessor commands are case sensitive and
must be lowercase. For example,
#include "string.h"
#define MAXIMUM 100
For more information, see “Writing Preprocessor Commands” on
page 2-3. For a list of the preprocessor commands, see “Preprocessor
Command-Line Reference” on page 2-45.
Program Structure
An assembly source file defines code (instructions) and data. It also
organizes the instructions and data to allow the use of the linker description file (
.ldf) to describe how code and data are mapped into the
memory on your target processor. The way you structure your code and
data into memory should follow the memory architecture of the target
processor.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-7
Assembler Guide
Use the
.SECTION directive to organize the code and data in assembly
source files. The .SECTION directive defines a grouping of instructions and
data that occupies contiguous memory addresses in the processor. The
name given in a .SECTION directive corresponds to an input section name
in the linker description file.
Table 1-1, Table 1-2, and Table 1-3 show suggested input section names
for data and code that can be used in your assembly source for various
processors. Using these predefined names in your sources makes it easier
to take advantage of the default .ldf file included in your DSP system.
However, you may also define your own sections. For information on
.ldf files, refer to the VisualDSP++ 5.0 Linker and Utilities Manual.
Table 1-1. Suggested Input Section Names for a SHARC .ldf File
.SECTION Name Description
seg_pmco A section in program memory that holds code
seg_dmda A section in data memory that holds data
seg_pmda A section in program memory that holds data
seg_rth A section in program memory that holds system initialization code
and interrupt service routines
seg_swco A section in short word memory that holds instructions encoded for
execution from short word memory.
NOTE: Applies to the ADSP-2146x processors only.
Table 1-2. Suggested Input Section Names for a TigerSHARC .ldf File
.SECTION Name Description
data1 A section that holds data in memory block M1
data2 A section that holds data in memory block M2 (specified with the
PM memory qualifier)
program A section that holds code
1-8 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-3. Suggested Input Section Names for a Blackfin .ldf File
.SECTION Name Description
data1 A section that holds data
program A section that holds code
constdata A section that holds global data (which is declared as constant) and
literal constants such as strings and array initializers
Use sections in a program to group elements to meet hardware constraints.
For example, the ADSP-BF535 processor has a separate program and data
memory in Level 1 memory only. Level 2 memory and external memory
are not separated into instruction and data memory.
To group the code that resides in off-chip memory, declare a section for
that code and place that section in the selected memory with the linker.
The example assembly program defines three sections. Each section begins
with a
.SECTION directive or end-of-file.
.SECTION directive and ends with the occurrence of the next
Table 1-4 lists the sections in the source program:
Table 1-4. Sections in Source Programs
Section Blackfin SHARC TigerSHARC
Data Section
Variables and buffers are declared and can be
initialized
Program Section
Data, instructions, and possibly other types of
statements are in this section, including statements that are needed for conditional assembly
data1
constdata
seg_rth
program
seg_dmda data1
data2
seg_pmco program
Figure 1-2, Figure 1-3 on page 1-14, and Figure 1-4 on page 1-17
describe assembly code file structure for each processor family. They show
how a program divides into sections that match the memory segmentation
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-9
Assembler Guide
of a DSP system. Notice that an assembly source may contain preprocessor commands (such as
#ifdef
SECTIONS{} commands define the .SECTION placements in the system’s
(for conditional assembly), or #define (to define macros). The
#include to include other files in source code),
physical memory as defined by the linker’s MEMORY{} command. Assembler
directives, such as .VAR (or .BYTE for Blackfin processors), appear within
sections to declare and initialize variables.
Code File Structure for SHARC Processors
Figure 1-2 describes assembly code file structure for SHARC processors.
Looking at Figure 1-2, notice that the .PRECISION and .ROUND_ZERO
directives inform the assembler to store floating-point data with 40-bit
precision and to round a floating-point value to a closer-to-zero value if it
does not fit in the 40-bit format.
LDF for SHARC Processors
Listing 1-1 shows a sample user-defined .ldf file for SHARC processors.
Looking at the file’s SECTIONS{} command, notice that the INPUT_SECTION
commands map to the names of memory sections (such as program, data1,
data2, ctor, heaptab, and so on) used in the example assembly sample
program.
Listing 1-1. LDF Example for SHARC Processors
ARCHITECTURE(ADSP-21062)
SEARCH_DIR( $ADI_DSP\21k\lib )
$LIBRARIES = lib060.dlb, libc.dlb;
$OBJECTS = $COMMAND_LINE_OBJECTS, 060_hdr.doj;
MEMORY {
seg_rth {TYPE(PM RAM) START(0x20000) END(0x20fff) WIDTH(48)}
seg_init{TYPE(PM RAM) START(0x21000) END(0x2100f) WIDTH(48)}
seg_pmco{TYPE(PM RAM) START(0x21010) END(0x24fff) WIDTH(48)}
1-10 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.PRECISION 40;
.ROUND_ZERO;
Data Section
Preprocessor Commands
for Conditional Assembly
Preprocessor Commands
.#include "const.h"
#define PI 3.14159
.SECTION/DM seg_dmda;
.VAR fxd[10] = 1,2,3,4,5,6,7,8,9,0xA;
.VAR rad;
.SECTION/PM seg_pmda;
.VAR flt[5] = PI,PI/2,1.0,2.0,2.0/3.0;
.SECTION/PM seg_pmco;
/* instructions */
function1:
I0 = fxd;
M0 = 1;
I8 = flt;
M8 = 1;
R0 = LENGTH(flt);
LCNTR = R0, DO this_loop UNTIL LCE;
R0 = DM(I0,M0), R1 = PM(I8,M8);
R2 = FIX F1 BY R0;
this_loop:
R3 = R3 + R2;
DM(rad) = R3;
Assembler Label
#ifdef duplicate_write
DM(rad) = R3;
#endif
function1.end:
Assembler Label
Assembler Directives
Code Section
Figure 1-2. Assembly Code File Structure for SHARC Processors
seg_pmda{TYPE(DM RAM) START(0x28000) END(0x28fff) WIDTH(32)}
seg_dmda{TYPE(DM RAM) START(0x29000) END(0x29fff) WIDTH(32)}
seg_stak{TYPE(DM RAM) START(0x2e000) END(0x2ffff) WIDTH(32)}
/* memory declarations for default heap */
seg_heap{TYPE(DM RAM) START(0x2a000) END(0x2bfff) WIDTH(32)}
/* memory declarations for custom heap */
seg_heaq{TYPE(DM RAM) START(0x2c000) END(0x2dfff) WIDTH(32)}
} // End MEMORY
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-11
Assembler Guide
PROCESSOR p0 {
LINK_AGAINST( $COMMAND_LINE_LINK_AGAINST)
OUTPUT( $COMMAND_LINE_OUTPUT_FILE )
SECTIONS {
.seg_rth {
INPUT_SECTIONS( $OBJECTS(seg_rth) $LIBRARIES(seg_rth))
} > seg_rth
.seg_init {
INPUT_SECTIONS( $OBJECTS(seg_init) $LIBRARIES(seg_init))
} > seg_init
.seg_pmco {
INPUT_SECTIONS( $OBJECTS(seg_pmco) $LIBRARIES(seg_pmco))
} > seg_pmco
.seg_pmda {
INPUT_SECTIONS( $OBJECTS(seg_pmda) $LIBRARIES(seg_pmda))
} > seg_pmda
.seg_dmda {
INPUT_SECTIONS( $OBJECTS(seg_dmda) $LIBRARIES(seg_dmda))
} > seg_dmda
.stackseg {
ldf_stack_space = .;
ldf_stack_length = 0x2000;
} > seg_stak
/* section placement for default heap */
.heap {
ldf_heap_space = .;
ldf_heap_end = ldf_heap_space + 0x2000;
ldf_heap_length = ldf_heap_end - ldf_heap_space;
} > seg_heap
/* section placement for additional custom heap */
1-12 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.heaq {
ldf_heaq_space = .;
ldf_heaq_end = ldf_heaq_space + 0x2000;
ldf_heaq_length = ldf_heaq_end - ldf_heaq_space;
} > seg_heaq
} // End SECTIONS
} // End P0
Code File Structure for TigerSHARC Processors
Figure 1-3 describes assembly code file structure for TigerSHARC
processors. Looking at Figure 1-3, notice that an assembly source may
contain preprocessor commands, such as #include (to include other files
in source code), #ifdef (for conditional assembly), or #define (to define
macros).
Assembler directives, such as .VAR, appear within sections to declare and
initialize variables.
LDF for TigerSHARC Processors
Listing 1-2 shows a sample user-defined .ldf file for TigerSHARC
processors. Looking at the file’s SECTIONS{} command, notice that the
INPUT_SECTION commands map to the names of memory sections (such as
program, data1, data2, ctor, heaptab, and so on) used in the example
assembly sample program.
Listing 1-2. Example Linker Description File for TigerSHARC Processors
ARCHITECTURE(ADSP-TS101)
SEARCH_DIR( $ADI_DSP\TS\lib )
$OBJECTS = $COMMAND_LINE_OBJECTS;
/* Internal memory blocks are 0x10000 (64k) */
MEMORY
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-13
Assembler Guide
.SECTION data1;
.VAR buffer1 [0x100] = 'buffer .dat.';
.SECTION data2;
.VAR buffer2;
.SECTION program;
start:
#ifdef XR0_SET_TO_2
xR0=0x2;;
#else
xR0=0x1;;
#endif
J1 = buffer1;;
JL1 = 0;;
J2 = 1;;
LC0 = 0x100;;
this loop: [J+=J2] = XRO;;
IF NLCOE, JUMP this_loop;;
Data Section
Assembly Instructions
Code Section
Assembler Directive
Data Section
Assembler Label
Preprocessor Commands
for Conditional Assembly
Figure 1-3. Assembly Code File Structure for TigerSHARC Processors
{
M0Code { TYPE(RAM) START(0x00000000) END(0x0000FFFF) WIDTH(32)
}
M1Data { TYPE(RAM) START(0x00080000) END(0x0008BFFF) WIDTH(32)
}
M1Heap { TYPE(RAM) START(0x0008C000) END(0x0008C7FF) WIDTH(32)
}
M1Stack { TYPE(RAM) START(0x0008C800) END(0x0008FFFF) WIDTH(32)
}
M2Data { TYPE(RAM) START(0x00100000) END(0x0010BFFF) WIDTH(32)
}
M2Stack { TYPE(RAM) START(0x0010C000) END(0x0010FFFF) WIDTH(32)
}
SDRAM { TYPE(RAM) START(0x04000000) END(0x07FFFFFF) WIDTH(32)
}
1-14 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
MS0 { TYPE(RAM) START(0x08000000) END(0x0BFFFFFF) WIDTH(32)
}
MS1 { TYPE(RAM) START(0x0C000000) END(0x0FFFFFFF) WIDTH(32)
}
}
PROCESSOR p0 /* The processor in the system *
{
OUTPUT($COMMAND_LINE_OUTPUT_FILE)
SECTIONS
{ /* List of sections for processor P0 */
code
{
FILL(0xb3c00000)
INPUT_SECTION_ALIGN(4)
INPUT_SECTIONS( $OBJECTS(program) )
} >M0Code
data1
{
INPUT_SECTIONS( $OBJECTS(data1) )
} >M1Data
data2
{
INPUT_SECTIONS( $OBJECTS(data2) )
} >M2Data
/
/* Provide support for initialization, including C++ static
initialization. This section builds a table of
initialization function pointers. */
ctor
{
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-15
Assembler Guide
INPUT_SECTIONS( $OBJECTS(ctor0) )
INPUT_SECTIONS( $OBJECTS(ctor1) )
INPUT_SECTIONS( $OBJECTS(ctor2) )
INPUT_SECTIONS( $OBJECTS(ctor3) )
INPUT_SECTIONS( $OBJECTS(ctor) )
} >M1Data
/* Table containing heap segment descriptors */
heaptab
{
INPUT_SECTIONS( $OBJECTS(heaptab) )
} >M1Data
/* Allocate stacks for the application */
jstackseg
{
ldf_jstack_limit = .;
ldf_jstack_base = . + MEMORY_SIZEOF(M1Stack);
} >M1Stack
kstackseg
{
ldf_kstack_limit = .;
ldf_kstack_base = . + MEMORY_SIZEOF(M2Stack);
} >M2Stack
/* The default heap occupies its own memory block */
defheapseg
{
ldf_defheap_base = .;
ldf_defheap_size = MEMORY_SIZEOF(M1Heap);
} >M1Heap
}
}
1-16 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.SECTION constdata;
.VAR buffer1 [ 6 ] = "buffer1.dat";
.SECTION data1;
.VAR buffer2[ 0x100];
#ifdef INCLUDE_BUFFER3
.VAR buffer3[ 0x100];
#endif
.SECTION program;
.global my_function;
P0 = R0;
I0 = R1;
P1 = 19;
R0 = 0;
R1 = [P0++];
R2 = [I0++];
LSETUP (begin_loop, end_loop) LC0 = P1;
begin_loop:
R1 *= R2;
R2 = [I0++];
end_loop:
R0= R0 + R1 (NS) || R1 = [P0++] || NOP;
R1 *= R2;
R0 = R0 + R1;
Data Section
Assembly Instructions
Code (program) Section
Assembler Directive
Data Section
Assembler Label
Preprocessor Commands
for Conditional Assembly
Assembler Directive
my_function.end:
Assembler Label
my_function:
Code File Structure for Blackfin Pro cessors
Figure 1-4 describes the Blackfin processor’s assembly code file structure
and shows how a program divides into sections that match the memory
segmentation of Blackfin processors.
Figure 1-4. Assembly Source File Structure for Blackfin Processors
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-17
Assembler Guide
You can use sections in a program to group elements to meet hardware
constraints. For example, the ADSP-BF535 processor has a separate program and data memory in Level 1 memory only. Level 2 memory and
external memory are not separated into instruction and data memory.
LDF for Blackfin Processors
Listing 1-3 on page 1-18 shows a sample user-defined linker description
file (.ldf). Looking at the file’s SECTIONS{} command, notice that the
INPUT_SECTION commands map to sections program, data1, and
constdata.
Listing 1-3. Example Linker Description File for Blackfin Processors
ARCHITECTURE(ADSP-BF535)
SEARCH_DIR($ADI_DSP\Blackfin\lib)
#define LIBS libc.dlb, libdsp.dlb
$LIBRARIES = LIBS, librt535.dlb;
$OBJECTS = $COMMAND_LINE_OBJECTS;
MEMORY /* Define/label system memory */
{ /* List of global Memory Segments */
MEM_PROGRAM { TYPE(RAM) START(0xF0000000) END(0xF002FFFF)
WIDTH(8) }
MEM_HEAP { TYPE(RAM) START(0xF0030000) END(0xF0037FFF)
WIDTH(8) }
MEM_STACK { TYPE(RAM) START(0xF0038000) END(0xF003DFFF)
WIDTH(8) }
MEM_SYSSTACK { TYPE(RAM) START(0xF003E000) END(0xF003FDFF)
WIDTH(8) }
MEM_ARGV { TYPE(RAM) START(0xF003FE00) END(0xF003FFFF)
WIDTH(8) }
}
PROCESSOR p0 /* The processor in the system */
1-18 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
{
OUTPUT($COMMAND_LINE_OUTPUT_FILE)
SECTIONS
{ /* List of sections for processor P0 */
program
{ /* Align all code sections on 2 byte boundary */
INPUT_SECTION_ALIGN(2)
INPUT_SECTIONS( $OBJECTS(program) $LIBRARIES(program))
INPUT_SECTION_ALIGN(1)
INPUT_SECTIONS( $OBJECTS(data1) $LIBRARIES(data1))
INPUT_SECTION_ALIGN(1)
INPUT_SECTIONS(
$OBJECTS(constdata)$LIBRARIES(constdata))
INPUT_SECTION_ALIGN(1)
INPUT_SECTIONS( $OBJECTS(ctor) $LIBRARIES(ctor))
INPUT_SECTION_ALIGN(2)
INPUT_SECTIONS( $OBJECTS(seg_rth))
} >MEM_PROGRAM
stack
{
ldf_stack_space = .;
ldf_stack_end = ldf_stack_space +
MEMORY_SIZEOF(MEM_STACK) - 4;
} >MEM_STACK
sysstack
{
ldf_sysstack_space = .;
ldf_sysstack_end = ldf_sysstack_space +
MEMORY_SIZEOF(MEM_SYSSTACK) - 4;
} >MEM_SYSSTACK
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-19
Assembler Guide
heap
{ /* Allocate a heap for the application */
ldf_heap_space = .;
ldf
_
heap_end = ldf_heap_space + MEMORY_SIZEOF(MEM_HEAP) - 1;
ldf_heap_length = ldf_heap_end - ldf_heap_space;
} >MEM_HEAP
argv
{ /* Allocate argv space for the application */
ldf_argv_space = .;
ldf
_
argv_end = ldf_argv_space + MEMORY_SIZEOF(MEM_ARGV) - 1;
ldf_argv_length = ldf_argv_end - ldf_argv_space;
} >MEM_ARGV
}
}
Program Interfacing Requirements
You can interface your assembly program with a C or C++ program.
The C/C++ compiler supports two methods for mixing C/C++ and
assembly language:
• Embedding assembly code in C or C++ programs
• Linking together C or C++ and assembly routines
To embed (inline) assembly code in your C or C++ program, use the
asm() construct. To link together programs that contain C/C++ and
assembly routines, use assembly interface macros. These macros facilitate
the assembly of mixed routines. For more information about these
methods, see the VisualDSP++ 5.0 C/C++ Compiler and Library Manual
for the appropriate target processor.
1-20 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
When writing a C or C++ program that interfaces with assembly, observe
the same rules that the compiler follows as it produces code to run on the
processor. These rules for compiled code define the compiler’s run-time
environment. Complying with a run-time environment means following
rules for memory usage, register usage, and variable names.
The definition of the run-time environment for the C/C++ compiler is
provided in the VisualDSP++ 5.0 C/C++ Compiler and Library Manual for
the appropriate target processor, which also includes a series of examples
to demonstrate how to mix C/C++ and assembly code.
Using Assembler Support for C Structs
The assembler supports C typedef/struct declarations within assembly
source. These assembler data directives and built-ins provide high-level
programming features with C structs in the assembler.
Data Directives:
.IMPORT (see on page 1-90)
.EXTERN STRUCT (see on page 1-83)
.STRUCT (see on page 1-130)
C Struct in Assembly Built-Ins:
OFFSETOF(struct/typedef,field (see on page 1-63)
SIZEOF(struct/typedef) (see on page 1-63)
Struct References:
struct->field (support nests; see “Struct References” on page 1-64)
For more information on C struct support, refer to the “-flags-compiler”
command-line switch on page 1-154 and to “Reading a Listing File” on
page 1-34.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-21
Assembler Guide
C structs in assembly features accept the full set of legal C symbol names,
including those that are otherwise reserved in the appropriate assembler.
For example,
• In the SHARC assembler,
I1, I2, and I3 are reserved keywords,
but it is legal to reference them in the context of the C struct in
assembly features.
• In the TigerSHARC assembler, J1, J2, and J3 are reserved
keywords, but it is legal to reference them in the context of the C
struct in assembly features.
• In the Blackfin assembler, as an example, “X” and “Z” are reserved
keywords, but it is legal to reference them in the context of the C
struct in assembly features.
The examples below show how to access the parts of the struct defined in
the header file, but they are not complete programs on their own. Refer to
your DSP project files for complete code examples.
Blackfin Example:
.IMPORT "Coordinate.h";
/* typedef struct Coordinate {
int X;
int Y;
int Z;
} Coordinate;*/
.SECTION data1;
.STRUCT Coordinate Coord1 = {
X = 1,
Y = 4,
Z = 7
};
1-22 VisualDSP++ 5.0 Assembler and Preprocessor Manual
.SECTION program;
P0.l = Coord1->X;
P0.h = Coord1->X;
P1.l = Coord1->Y;
P1.h = Coord1->Y;
P2.l = Coord1->Z;
P2.h = Coord1->Z;
P3.l = Coord1+OFFSETOF(Coordinate,Z);
P3.h = Coord1+OFFSETOF(Coordinate,Z);
SHARC Example:
.IMPORT "Samples.h";
/* typedef struct Samples {
int I1;
int I2;
int I3;
} Samples; */
Assembler
.SECTION/DM seg_dmda;
.STRUCT Samples Sample1 ={
I1 = 0x1000,
I2 = 0x2000,
I3 = 0x3000
};
.SECTION/PM seg_pmco;
doubleMe:
/* The code may look confusing, but I2 can be used both
as a register and a struct member name */
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-23
Assembler Guide
B2 = Sample1;
M2 = OFFSETOF(Sample1,I2);
R0 = DM(M2,I2);
R0 = R0+R0;
DM(M2,I2) = R0;
L
that have the same spelling as assembler keywords. This may not
always be possible if your application needs to use an existing set of
C header files.
Preprocessing a Program
The assembler includes a preprocessor that allows the use of C-style
preprocessor commands in your assembly source files. The preprocessor
automatically runs before the assembler unless you use the assembler’s -sp
(skip preprocessor) switch. Table 2-5 on page 2-23 lists preprocessor
commands and provides a brief description of each command.
You can see the command line that the assembler uses to invoke the preprocessor by adding the -v switch (on page 1-167) to the assembler
command line or by selecting the Generate verbose output option on the
Assemble page of the Project Options dialog box. See “Specifying Assem-
bler Options in VisualDSP++” on page 1-170.
Use preprocessor commands to modify assembly code. For example,
you can use the #include command to fill memory, load configuration
registers, or set up processor parameters. You can use the #define command to define constants and aliases for frequently used instruction
sequences. The preprocessor replaces each occurrence of the macro
reference with the corresponding value or series of instructions.
For better code readability, avoid using .STRUCT member names
For example, the
with the number
MAXIMUM macro from #define MAXIMUM 100 is replaced
100 during preprocessing.
1-24 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
For more information on the preprocessor command set, see “Preproces-
sor Command Reference” on page 2-22. For more information on the
preprocessor usage, see “-flags-pp -opt1 [,-opt2...]” on page 1-156.
L
For example,
#define EXTERN ox123
.EXTERN Coordinate; /* EXTERN not affected by macro */
#define MY_REG P0
MY_REG.1 = 14; /* MY_REG.1 is not expanded; */
There is one important difference between the assembler preprocessor and compiler preprocessor. The assembler preprocessor
treats the “.” character as part of an identifier. Thus, .EXTERN is a
single identifier and will not match a preprocessor macro EXTERN.
This behavior can affect how macro expansion is done for some
instructions.
/* "." is part of token */
Using Assembler Feature Macros
The assembler includes the command to invoke preprocessor macros to
define the context, such as the source language, the architecture, and the
specific processor. These feature macros allow programmers to use prepro-
cessor conditional commands to configure the source for assembly based
on the context.
Table 1-5 lists the set of feature macros for Blackfin processors. Table 1-6
on page 1-28 lists the set of feature macros for SHARC processors.
Table 1-7 on page 1-30 lists the set of feature macros for TigerSHARC
processors.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-25
Assembler Guide
Table 1-5. Feature Macros for Blackfin Processors
-D_LANGUAGE_ASM=1 Always present
-D__ADSPBLACKFIN__ =1 Always present
-D__ADSPLPBLACKFIN__ =1 Always present for non-ADSP-BF535 processors
-D__ADSPBF51x__=1 Present when running:
easmblkfn -proc ADSP-BF512
easmblkfn -proc ADSP-BF514
easmblkfn -proc ADSP-BF516
-D__ADSPBF52x__=1 Present when running:
easmblkfn -proc ADSP-BF522
easmblkfn -proc ADSP-BF523
easmblkfn -proc ADSP-BF524
easmblkfn -proc ADSP-BF525
easmblkfn -proc ADSP-BF526
easmblkfn -proc ADSP-BF527
-D__ADSPBF54x__=1 Present when running:
easmblkfn -proc ADSP-BF542
easmblkfn -proc ADSP-BF544
easmblkfn -proc ADSP-BF547
easmblkfn -proc ADSP-BF548
easmblkfn -proc ADSP-BF549
-D__ADSPBF512__=1 Present when running easmblkfn -proc ADSP-BF512
with the ADSP-BF512 processor
-D__ADSPBF514__=1 Present when running easmblkfn -proc ADSP-BF514
with the ADSP-BF514 processor
-D__ADSPBF516__=1 Present when running easmblkfn -proc ADSP-BF516
with the ADSP-BF516 processor
-D__ADSPBF522__=1 Present when running easmblkfn -proc ADSP-BF522
with the ADSP-BF522 processor
-D__ADSPBF523__=1 Present when running easmblkfn -proc ADSP-BF523
with the ADSP-BF523 processor
-D__ADSPBF524__=1 Present when running easmblkfn -proc ADSP-BF524
with the ADSP-BF524 processor
-D__ADSPBF525__=1 Present when running easmblkfn -proc ADSP-BF525
with the ADSP-BF525 processor
1-26 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-5. Feature Macros for Blackfin Processors (Cont’d)
-D__ADSPBF526__=1 Present when running easmblkfn -proc ADSP-BF526
with the ADSP-BF526 processor
-D__ADSPBF527__=1 Present when running easmblkfn -proc ADSP-BF527
with the ADSP-BF527 processor
-D__ADSPBF531__=1
-D__ADSP21531__=1
-D__ADSPBF532__=1
-D__ADSP21532__=1
-D__ADSPBF533__=1
-D__ADSP21533__=1
-D__ADSPBF534__=1 Present when running easmblkfn -proc ADSP-BF534
Present when running easmblkfn -proc ADSP-BF531
with the ADSP-BF531 processor
Present when running easmblkfn -proc ADSP-BF532
with the ADSP-BF532 processor
Present when running easmblkfn -proc ADSP-BF533
with the ADSP-BF533 processor
with the ADSP-BF534 processor
-D__ADSPBF535__=1
-D__ADSP21535__=1
-D__ADSPBF536__=1 Present when running easmblkfn -proc ADSP-BF536
Present when running easmblkfn -proc ADSP-BF535
with the ADSP-BF535 processor
with the ADSP-BF536 processor
-D__ADSPBF537__=1 Present when running easmblkfn -proc ADSP-BF537
with the ADSP-BF537 processor
-D__ADSPBF538__=1 Present when running easmblkfn -proc ADSP-BF538
with the ADSP-BF538 processor
-D__ADSPBF539__=1 Present when running easmblkfn -proc ADSP-BF539
with the ADSP-BF539 processor
-D__ADSPBF542__=1 Present when running easmblkfn -proc ADSP-BF542
with the ADSP-BF542 processor
-D__ADSPBF544__=1 Present when running easmblkfn -proc ADSP-BF544
with the ADSP-BF544 processor
-D__ADSPBF547__=1 Present when running easmblkfn -proc ADSP-BF547
with the ADSP-BF547processor
-D__ADSPBF548__=1 Present when running easmblkfn -proc ADSP-BF548
with the ADSP-BF548 processor
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-27
Assembler Guide
Table 1-5. Feature Macros for Blackfin Processors (Cont’d)
-D__ADSPBF549__=1 Present when running easmblkfn -proc ADSP-BF549
with the ADSP-BF549 processor
-D__ADSPBF561__=1 Present when running easmblkfn -proc ADSP-BF561
with the ADSP-BF561 processor
Table 1-6. Feature Macros for SHARC Processors
-D_LANGUAGE_ASM=1 Always present
-D__ADSP21000__=1 Always present
-D__ADSP21020__=1
-D__2102x__=1
-D__ADSP21060__=1
-D__2106x__=1
-D__ADSP21061__=1
-D__2106x__=1
-D__ADSP21062__=1
-D__2106x__=1
-D__ADSP21065L__=1
-D__2106x__=1
-D__ADSP21160__=1
-D__2116x__=1
-D__ADSP21161__=1
-D__2116x__=1
-D__ADSP21261__=1
-D__2126x__=1
-D__ADSP21262__=1
-D__2126x__=1
-D__ADSP21266__=1
-D__2126x__=1
-D__ADSP21267__=1
-D__2126x__=1
Present when running easm21K -proc ADSP-21020
with the ADSP-21020 processors
Present when running easm21K -proc ADSP-21060
with the ADSP-21060 processors
Present when running easm21K -proc ADSP-21061
with the ADSP-21061 processors
Present when running easm21K -proc ADSP-21062
with the ADSP-21062 processors
Present when running easm21K -proc ADSP-21065L
with the ADSP-21065L processors
Present when running easm21K -proc ADSP-21160
with the ADSP-21160 processors
Present when running easm21K -proc ADSP-21161
with the ADSP-21161 processors
Present when running easm21K -proc ADSP-21261
with the ADSP-21261 processors
Present when running easm21K -proc ADSP-21262
with the ADSP-21262 processors
Present when running easm21K -proc ADSP-21266
with the ADSP-21266 processors
Present when running easm21K -proc ADSP-21267
with the ADSP-21267 processors
1-28 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Table 1-6. Feature Macros for SHARC Processors (Cont’d)
Assembler
-D__ADSP21362__=1
-D__2136x__=1
-D__ADSP21363__=1
-D__2136x__=1
-D__ADSP21364__=1
-D__2136x__=1
-D__ADSP21365__=1
-D__2136x__=1
-D__ADSP21366__=1
-D__2136x__=1
-D__ADSP21367__=1
-D__2136x__=1
-D__ADSP21368__=1
-D__2136x__=1
-D__ADSP21369__=1
-D__2136x__=1
-D__ADSP2137x__=1
-D__2137x__=1
-D__ADSP21371__=1
-D__2137x__=1
-D__ADSP21375__=1
-D__2137x__=1
Present when running easm21K -proc ADSP-21362
with the ADSP-21362 processors
Present when running easm21K -proc ADSP-21363
with the ADSP-21363 processors
Present when running easm21K -proc ADSP-21364
with the ADSP-21364 processors
Present when running easm21K -proc ADSP-21365
with the ADSP-21365 processors
Present when running easm21K -proc ADSP-21366
with the ADSP-21366 processors
Present when running easm21K -proc ADSP-21367
with the ADSP-21367 processors
Present when running easm21K -proc ADSP-21368
with the ADSP-21368 processors
Present when running easm21K -proc ADSP-21369
with the ADSP-21369 processors
Present when running easm21K -proc ADSP-2137x
with the ADSP-2137x processors
Present when running easm21K -proc ADSP-21371
with the ADSP-21371 processors
Present when running easm21K -proc ADSP-21375
with the ADSP-21375 processors
-D__ADSP21462__=1
-D__2146x__=1
-D__214xx__=1
-D__ADSP21465__=1
-D__2146x__=1
-D__214xx__=1
-D__ADSP21467__=1
-D__2146x__=1
-D__214xx__=1
Present when running easm21K -proc ADSP-21462
with the ADSP-21462 processors
Present when running easm21K -proc ADSP-21465
with the ADSP-21465 processors
Present when running easm21K -proc ADSP-21467
with the ADSP-21467 processors
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-29
Assembler Guide
Table 1-6. Feature Macros for SHARC Processors (Cont’d)
-D__ADSP21469__=1
-D__2146x__=1
-D__214xx__=1
-D__NORMAL_WORD_CODE__=1 Present when running
Present when running easm21K -proc ADSP-21469
with the ADSP-21469 processors
easm21K -proc ADSP-21462
easm21K -proc ADSP-21465
easm21K -proc ADSP-21467
easm21K -proc ADSP-21469 and building in normal-word
mode
-D__SHORT_WORD_CODE__=1 Present when running
easm21K -proc ADSP-21462
easm21K -proc ADSP-21465
easm21K -proc ADSP-21467
easm21K -proc ADSP-21469 and building in short-word
mode
Table 1-7. Feature Macros for TigerSHARC Processors
-D_LANGUAGE_ASM =1 Always present
-D__ADSPTS__ =1 Always present
-D__ADSPTS101__ =1 Present when running easmts -proc ADSP-TS101
with the ADSP-TS101 processor
-D__ADSPTS201__ =1 Present when running easmts -proc ADSP-TS201
with the ADSP-TS201 processor
-D__ADSPTS202__ =1 Present when running easmts -proc ADSP-TS202
with the ADSP-TS202 processor
-D__ADSPTS203__ =1 Present when running easmts -proc ADSP-TS203
with the ADSP-TS203 processor
-D__ADSPTS20x__ =1 Present when running
easmts -proc ADSP-TS201 with the ADSP-TS201 processor
easmts -proc ADSP-TS202 with the ADSP-TS202 processor
asmts -proc ADSP-TS203 with the ADSP-TS203 processor
1-30 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
For
.IMPORT headers, the assembler calls the compiler driver with the
appropriate processor option, and the compiler sets the machine constants
accordingly (and defines -D_LANGUAGE_C=1). This macro is present when
used for C compiler calls to specify headers. It replaces -D_LANGUAGE_ASM.
For example,
easm21k -proc adsp-21262 assembly --> cc21K -proc adsp-21262
easmts -proc -ADSP-TS101
easmblkfn -proc ADSP-BF535 assembly --> ccblkfn -proc ADSP-BF535
L
-D__VISUALDSPVERSION__ Predefined Macro
Use the -verbose switch to verify what macro is default-defined.
Refer to Chapter 1 in the VisualDSP++ 5.0 C/C++ Compiler and
Library Manual of the appropriate target processor for more
information.
The macro applies to all Analog Devices processors.
assembly --> ccts -proc ADSP-TS101
L
The -D__VISUALDSPVERSION__ predefined macro provides product version
information to VisualDSP++. The macro allows a preprocessing check to
be placed within code and is used to differentiate between VisualDSP++
releases and updates.
Syntax:
-D__VISUALDSPVERSION__=0xMMmmUUxx
Table 1-8 explains the macro parameters.
The
0xMMmmUUxx information is obtained from the <install_path>\Sys-
tem\VisualDSP.ini
If an unexpected problem occurs while trying to locate VisualDSP.ini or
while extracting information from the
__VISUALDSPVERSION__ macro is not encoded to the VisualDSP++ product
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-31
file. Initially, xx is set to “00”.
VisualDSP.ini file, the
Assembler Guide
Table 1-8. -D__VISUALDSPVERSION__ Decoding of Hex Value
Parameter Description
MM VersionMajor. The major release number; for example, 4 in release 4.5.
mm VersionMinor. The minor release number; for example, 5 in release 4.5.
UU VersionPatch. The number of the release update; for example, 6 in release 4.5,
update 6.
xx Reserved for future use (always 00 initially)
version. In the Error Check example below, the
0xffffffff
string is displayed as part of an error message when the version
-D__VISUALDSPVERSION__
information is unable to be encoded.
Code Example (Legacy ):
#if !defined(__VISUALDSPVERSION__)
#warning Building with VisualDSP++ 4.5 Update 5 or prior. No
__VISUALDSPVERSION__ available.
#endif
Code Example (VisualDSP++ 4.5 Update 6 or Later):
#if __VISUALDSPVERSION__ >= 0x04050600
#warning Building with VisualDSP++ 4.5 Update 6 or later
#endif
Code Example (Error Check):
#if __VISUALDSPVERSION__ == 0xffffffff
#error Unexpected build problems, unknown VisualDSP++ Version
#endif
Code Examples (Assembly):
#if __VISUALDSPVERSION__ == 0x05000000
/* Building with VisualDSP++ 5.0 */
.VAR VersionBuildString[] = ‘Building with VisualDSP++ 5.0’;
1-32 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
#elif __VISUALDSPVERSION__ == 0x04050600
/* Building with VisualDSP++ 4.5, Update 6 */
.VAR VersionBuildString[] = 'Building with VisualDSP++ 4.5 Update
6';
#else
/* Building with unknown VisualDSP++ version */
.VAR VersionBuildString[] = 'Building with unknown VisualDSP++
version?';
#endif
Generating Make Dependencies
The assembler can generate make dependencies for a file, allowing
VisualDSP++ and other makefile-based build environments to determine
when to rebuild an object file due to changes in the input files. The assembly source file and any files identified in the #include commands, .IMPORT
directives, or buffer initializations (in .VAR and .STRUCT directives) constitute the make dependencies for an object file.
When you request make dependencies for the assembly, the assembler
produces the dependencies from buffer initializations. The assembler also
invokes the preprocessor to determine the make dependency from
#include commands, and the compiler to determine the make
dependencies from the .IMPORT headers.
For example,
easmblkfn -proc ADSP-BF533 -MM main.asm
"main.doj": "/VisualDSP/Blackfin/include/defBF532.h"
"main.doj": "/VisualDSP/Blackfin/include/defBF533.h"
"main.doj": "/VisualDSP/Blackfin/include/def_LPBlackfin.h"
"main.doj": "main.asm"
"main.doj": "input_data.dat"
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-33
Assembler Guide
The original source file
...
#include "defBF533.h"
...
.GLOBAL input_frame;
.BYTE input_frame[N] = "input_data.dat"; /* load in 256 values
...
main.asm is as follows:
from a test file */
In this case, defBF533.h includes defBF532.h, which also includes
def_LPBlackfin.h.
Reading a Listing File
A listing file (.lst) is an optional output text file that lists the results of
the assembly process. Listing files provide the following information:
• Address – The first column contains the offset from the .SECTION’s
base address.
• Opcode – The second column contains the hexadecimal opcode
that the assembler generates for the line of assembly source.
• Line – The third column contains the line number in the assembly
source file.
• Assembly Source – The fourth column contains the assembly
source line from the file.
The assembler listing file provides information about the imported C data
structures. It tells which imports were used within the program, followed
by a more detailed section. It shows the name, total size, and layout with
offset for the members. The information appears at the end of the listing.
You must specify the -l filename option (as described on page 1-159)
to produce a listing file.
1-34 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Enabling Statistical Profiling for Assembly Functions
Use the following steps to enable statistical profiling in assembler sources.
1. When using the VisualDSP++ IDDE, use the Assemble page of the
Project Options dialog box (Figure 1-6 on page 1-171) to select
and/or set assembler functional options.
2. Select the Generate debug information option.
3. Mark ending function boundaries with .end labels in the assembler
source. For example:
.SECTION program;
.GLOBAL funk1;
funk1:
...
RTS;
funk1.end:
.GLOBAL funk2;
funk2:
...
RTS;
funk2.end:
If you have global functions without ending labels, the assembler
provides warnings when debug information is generated.
.GLOBAL funk3;
funk3:
...
RTS;
[Warning ea1121] "test.asm":14 funk3: -g assembly with
global function without ending label. Use 'funk3.end' or
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-35
Assembler Guide
'funk3.END' to mark the ending boundary of the function for
debugging information for automated statistical profiling
of assembly functions.
4. Add ending labels or selectively disable the warning by adding the
-Wsuppress 1121 option to the Additional options field on the
Assembly page (refer to “WARNING ea1121: Missing End Labels”
on page 1-157 for more information).
5. Choose Statistical Profiling -> New Profile or Linear Profiling ->
New Profile, as appropriate. Assembler functions automatically
appear in the profiling window along with C functions. Click on
the function name to bring up the source containing the function
definition.
1-36 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Assembler Syntax Reference
When developing a source program in assembly language, include
preprocessor commands and assembler directives to control the program’s
processing and assembly. You must follow the assembler rules and syntax
conventions to define symbols (identifiers) and expressions, and to use
different numeric and comment formats.
Software developers who write assembly programs should be familiar with:
• “Assembler Keywords and Symbols” on page 1-38
• “Assembler Expressions” on page 1-50
• “Assembler Operators” on page 1-51
• “Numeric Formats” on page 1-56
• “Comment Conventions” on page 1-60
• “Conditional Assembly Directives” on page 1-60
• “C Struct Support in Assembly Built-In Functions” on page 1-63
• “Struct References” on page 1-64
• “Assembler Directives” on page 1-67
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-37
Assembler Syntax Reference
Assembler Keywords and Symbols
The assembler supports predefined keywords that include register and
bitfield names, assembly instructions, and assembler directives.
The following tables list assembler keywords for supported processors.
Although the keywords appear in uppercase, the keywords are case
insensitive in the assembler’s syntax. For example, the assembler does not
differentiate between MAX and max.
Table 1-9 lists the assembler keywords for Blackfin processors.
Table 1-10 on page 1-41 lists the keywords for SHARC processors.
Table 1-11 on page 1-44 lists the keywords for TigerSHARC processors.
Table 1-9. Blackfin Processor Assembler Keywords
.ALIGN .ASCII .ASM_ASSERT .ASSERT .BSS
.BYTE .BYTE2 .BYTE4 .DATA .ELIF
.ELSE .ENDIF .ELSE .ENDIF .EXTERN
.FILE .FILE_ATTR .GLOBAL .GLOBL .IF
.INC/BINARY .INCBIN .IMPORT .LEFTMARGIN .LIST
.LIST_DATA .LIST_DATFILE .LIST_DEFTAB .LIST_LOCTAB
.LONG .NEWPAGE .NOLIST .NOLIST_DATA .NOLIST_DATFILE
.NOLIST_WRAPDATA .PAGELENGTH .PAGEWIDTH .PREVIOUS
.SECTION .SET SYMBOL .SYMBOL .SHORT .STRUCT
.TEXT .TYPE .VAR .WEAK
A0 A1 ABORT ABS AC
ALIGN8 ALIGN16 ALIGN24 AMNOP AN
AND ASHIFT ASL ASR ASSIGN
ASTAT AV0 AV1 AZ
B B0B1B2 B3
.
LIST_WRAPDATA
1-38 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-9. Blackfin Processor Assembler Keywords (Cont’d)
BANG BAR BITCLR BITMUX BITPOS
BITSET BITTGL BITTST BIT_XOR_AC BP
BREV BRF BRT BY BYTEOP1P
BYTEOP16M BYTEOP1NS BYTEOP16P BYTEOP2P
BYTEOP3P BYTEPACK BYTEUNPACK BXOR BXORSHIFT
CALL CARET CC CLI CLIP
CO CODE COLON COMMA CSYNC
DATA DEPOSIT DISALGNEXCPT DIVSDEPOSIT DISALGNEXCPT
DIVSDEPOSIT DM DOZE DIVQ DIVS
DOT EMUCAUSE EMUEXCPT EXCAUSE EXCPT
EXPADJ EXTRACT
FEXT FEXTSX FLUSH FLUSHINV FP
FU
GE GF GT
H HI HLT HWERRCAUSE
I0 I1 I2 I3 IDLE
IDLE_REQ IFLUSH IH INTRP IS
ISS2 IU
JUMP JUMP.L JUMP.S
L LB0 LB1 LC0 LC1
LE LENGTH LINK LJUMP LMAX
LMIN LO LOOP LOOP_BEGIN LOOP_END
LPAREN LSETUP LSHIFT LT LT0
LT1 LZ
M M0 M1 M2 M3
MAX MIN MINUS MNOP MUNOP
NEG NO_INIT NOP NOT NS
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-39
Assembler Syntax Reference
Table 1-9. Blackfin Processor Assembler Keywords (Cont’d)
ONES OR OUTC
P0 P1 P2 P3 P4
P5 PACK PC PERCENT PLUS
PM PREFETCH PRNT
R R0 R1 R2 R3
R32R4R5R6 R7
RAISE RBRACE RBRACK RETI RETN
RETS RETX RND RND12 RND20
RNDH RNDL ROL ROR ROT
ROT_L_AC ROT_R_AC RPAREN RSDL RTE
RTI RTN RTS RTX RUNTIME_INIT
R1_COLON0 RETAIN_NAME
S S2RND SAA SAA1H SAA1L
SAA2H SAA2L SAA3H SAA3L SAT
SCO SEARCH SHT_TYPE SIGN SIGNBITS
SLASH SLEEP SKPF SKPT SP
SS SSF SSF_RND_HI SSF_TRUNC SSF_TRUNC_HI
SSF_RND SSF_TRUNC SSYN STI STRUCT
STT_TYPE SU SYSCFG
T TESTSET TFU TH TL
TST
UNLINK UNLNK UNRAISE UU
V VIT_MAX
W W32 WEAK
X XB XH XOR Z
ZERO_INIT
1-40 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-9. Blackfin Processor Assembler Keywords (Cont’d)
_ADI_ _DATE_ _FILE_ _LastSuffix_ _LINE_
_TIME_
Table 1-10. SHARC Processor Assembler Keywords
__ADI__ __DATE__ __FILE__ __LastSuffix__ __LINE__
__NORMAL_WORD_CODE__ __SHORT_WORD_CODE__ __TIME__
.ALIGN .COMPRESS .ELIF .ELSE .ENDIF
.EXTERN .FILE .FILE_ATTR .FORCECOMPRESS .GLOBAL
.IF .IMPORT .LEFTMARGIN .LIST .LIST_DATA
.LIST_DATFILE .LIST_DEFTAB .LIST_LOCTAB .LIST_WRAPDATA .NEWPAGE
.NOCOMPRESS .NOLIST_DATA.NOLIST_DATFILE .NOLIST_WRAPDATA
.PAGELENGTH .PAGEWIDTH .PRECISION .ROUND_MINUS .ROUND_NEAREST
.ROUND_PLUS .ROUND_ZERO .PREVIOUS .SECTION .STRUCT
.VAR .WEAK
ABS ACS ACT ADDRESS AND
ASHIFT ASTAT AV
B0 B1 B2 B3 B4
B5 B6 B7 B8 B9
B10 B11 B12 B13 B14
B15 BB BCLR BF BIT
BITREV BM BSET BTGL BTSTS
BY
CA CACHE CALL CH CI
CJUMP CL CLIP COMP COPYSIGN
COS CURLCNTR
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-41
Assembler Syntax Reference
Table 1-10. SHARC Processor Assembler Keywords (Cont’d)
DADDR DB DEC DEF DIM
DM DMA1E DMA1S DMA2E DMA2S
DMADR DMABANK1 DMABANK2 DMABANK3 DMAWAIT
DO DOVL
EB ECE EF ELSE EMUCLK
EMUCLK2 EMUIDLE EMUN ENDEF EOS
EQ EX EXP EXP2
F0 F1 F2 F3 F4
F5 F6 F7 F8 F9
F10 F11 F12 F13 F14
F15 FADDR FDEP FEXT FILE
FIX FLAGO_IN FLAG1_IN FLAG2_IN FLAG3_IN
FLOAT FLUSH FMERG FOREVER FPACK
FRACTIONAL FTA FTB FTC FUNPACK
GCC_COMPILED GE GT
I0 I1 I2 I3 I4
I5 I6 I7 I8 I9
I10 I11 I12 I13 I14
I15 IDLEI15 IDLE16 IF IMASK
IMASKP INC IRPTL
JUMP
L0 L1 L2 L3 L4
L5 L6 L7 L8 L9
L10 L11 L12 L13 L14
L15 LA LADDR LCE LCNTR
LE LADDR LCE LCNTR LE
L15 LA LADDR LCE LCNTR
1-42 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-10. SHARC Processor Assembler Keywords (Cont’d)
LE LEFTO LEFTZ LENGTH
LINE LN LOAD LOG2 LOGB
LOOP LR LSHIFT LT
M0 M1 M2 M3 M4
M5 M6 M7 M8 M9
M10 M11 M12 M13 M14
M15 MANT MAX MBM MIN
MOD MODE1 MODE2 MODIFY MROB
MROF MR1B MR1F MR2B MR2F
MRB MRF MS MV MROB
MROF
NE NOFO NOFZ NOP NOPSPECIAL
NOT NU NW
OFFSETOF OR
P20 P32 P40 PACK PAGE
PC PCSTK PCSTKP PM PMADR
PMBANK1 PMDAE PMDAS POP POVLO
POVL1 PSA1E PSA1S PSA2E PSA3E
PSA3S PSA4E PSA4S PUSH PX
PX1 PX2 RETAIN_NAME
R0 R1 R2 R3 R4
RF5 R6 R7 R8 R9
R10 R11 R12 R13 R14
R15 READ RECIPS RFRAME RND
ROT RS RSQRTS RTI RTS
SCALB SCL SE SET SF
SIN SIZE SIZEOF SQR SR
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-43
Assembler Syntax Reference
Table 1-10. SHARC Processor Assembler Keywords (Cont’d)
SSF SSFR SSI SSIR ST
STEP STKY STRUCT STS SUF
SUFR SV SW SZ
TAG TCOUNT TF TGL TPERIOD
TRUE TRUNC TST TYPE TRAP
UF UI UNPACK UNTIL UR
USF USFR USI USIR USTAT1
USTAT2 UUF UUFR UUIR UUIR
VAL WITH XOR
Table 1-11. TigerSHARC Processor Assembler Keywords
__ADI__ __DATE__ __FILE__ __LastSuffix__ __LINE__
__TIME__
.ALIGN .ALIGN_CODE .ELIF .ELSE .ENDIF
.EXTERN .FILE .FILE_ATTR .GLOBAL .IF
.IMPORT .LEFTMARGIN .LIST .LIST_DATA .LIST_DATFILE
.LIST_DEFTAB .LIST_LOCTAB .LIST_WRAPDATA .MESSAGE .NOLIST_DATA
.
NOLIST_DATFILE.NOLIST_WRAPDATA .NEWPAGE .PAGELENGTH .PAGEWIDTH
.PREVIOUS .SECTION .SEPARATE_MEM_SEGMENTS .SET
.SECTION .VAR .WEAK
ABS ACS ADDRESS AND ASHIFT
BCLR BFOINC BFOTMP BITEST BITFIFO
BKFPT BR BSET BTBDIS BTBELOCK
BTBEN BTBLOCK BTBINV BTGL BY
C CALL CB CJMP CJMP_CALL
CI CLIP COMP COMPACT COPYSIGN
1-44 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-11. TigerSHARC Processor Assembler Keywords (Cont’d)
DAB DEC DESPREAD D0
ELSE EMUTRAP EXP EXPAND EXTD
FCOMP FDEP FEXT FIX FLOAT
FTEST0 FTEST1 FOR GETBITS IDLE
INC JC JUMP KC
LD0 LD1 LENGTH LINES LOGB
LP LSHIFT LSHIFTR LIBSIM_CALL
MANT MASK MAX MERGE MIN
NEWPAGE NOT NOP NP
OFFSETOF ONES OR
PASS PERMUTE PRECISION PUTBITS
RDS RECIPS RESET RETI ROT
ROTL ROTR ROUND RSQRTS RTI
SCALB SDAB SE SECTION SFO
SF1 SNGL SIZE SIZEOF STRUCT
SUM TMAX TRAP TYPEVAR UNTIL
VMIN VMAX XCORRS XOR XSDAB
YDAB YSDAB
JK Register Group
J0 through J31
K0
through K31
JB0 JB1 JB2 JB3
KB0 KB1 KB2 KB3
JL0 JL1 JL2 JL3
KL0 KL1 KL2 KL3
RF Register Group
FR0 through FR31
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-45
Assembler Syntax Reference
Table 1-11. TigerSHARC Processor Assembler Keywords (Cont’d)
MR3:0 MR3:2 MR1:0
MR0 MR1 MR2 MR3 MR4
PR0 PR1 PR1:0
R0 through R31
XSTAT YSTAT XYSTAT
XR0 through XR31
YR0 through YR31
Accelerator Register Group
TR0 through TR31
THR0 THR1 THR2 THR3
EP Register Group
BMAX BMAXC BUSLK FLGPIN FLGPINCL
FLGPINST SDRCON SYSCON SYSCONCL SYSCONST
SYSCTL SYSTAT SYSTATCL
Misc. Register Group
AUTODMA0 AUTODMA1
BTBCMD BTBDATA
BTB0TG0 through BTB0TG31
BTB1TG0
BTB2TG0 through BTB2TG31
BTB3TG0
BTB0TR0 through BTB0TR31
BTB1TR0
BTB2TR0 through BTB2TR31
BTB3TR0
BTBLRU0
CACMD0 CACMD2 CACMD4 CACMD8 CACMD10
through BTB1TG31
through BTB3TG31
through BTB1TR31
through BTB3TR31
through BTBLRU31
1-46 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-11. TigerSHARC Processor Assembler Keywords (Cont’d)
CACMDALL
CADATA0 CADATA2 CADATA4 CADATA8 CADATA10
CADATAALL
CASTAT0 CASTAT2 CASTAT4 CASTAT8 CASTAT10
CASTATALL
CCAIR0 CCAIR2 CCAIR4 CCAIR8 CCAIR10
CCAIRALL
CCNT0 CCNT1 CJMP CMCTL
DBGE DC4 through DC13
DCD0 DCD1 DCD2 DCD3 DCNT
DCNTCL DCNTST
DCS0 DCS1 DCS2 DCS3
DSTAT DSTATC
EMUCTL EMUDAT EMUIR EMUSTAT
IDCODE ILATCLH ILATCLL ILATH ILATL
ILATSTH ILATSTL IMASKH IMASKL INSTAT
INTEN INTCTL IVBUSLK IVDBG IVHW
IVDMA0 through IVDMA13
IVIRQ0 IVIRQ1 IVIRQ2 IVIRQ3 IVLINK0
IVLINK1 IVLINK2 IVLINK3 IVSW IVTIMER0HP
IVTIMER0LP IVTIMER1HP IVTIMER1LP
LBUFRX0 LBUFRX1 LBUFRX2 LBUFRX3
LBUFTX0 LBUFTX1 LBUFTX2 LBUFTX3
LC0 LC1 KB2 KB3
LCTL0 LCTL1 LCTL2 LCTL3
LRCTL0 LRCTL1 LRCTL2 LRCTL3
LRSTAT0 LRSTAT1 LRSTAT2 LRSTAT3
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-47
Assembler Syntax Reference
Table 1-11. TigerSHARC Processor Assembler Keywords (Cont’d)
LRSTATC0 LRSTATC1 LRSTATC2 LRSTATC3
LSTAT0 LSTAT1 LSTAT2 LSTAT3
LSTATC0 LSTATC1 LSTATC2 LSTATC3
LTCTL0 LTCTL1 LTCTL2 LTCTL3
LTSTAT0 LTSTAT1 LTSTAT2 LTSTAT3
LTSTATC0 LTSTATC1 LTSTATC2 LTSTATC3
MISR0 MISR1 MISR2 MISRCTL
RETI RETIB RETS RTI
OSPID
PMASKH PMASKL PRFM PRFCNT RETAIN_NAME
SERIAL_H SERIAL_L SFREG SQCTL SQCTLST
SQCTLCL SQSTAT
TESTMODES TIMER0L TIMER1L TIMER0H TIMER1H
TMRIN0L TMRIN0H TMRIN1L TMRIN1H TRCB
TRCBMASK TRCBPTR TRCBVAL
VIRPT
WP0CTL WP1CTL WP2CTL WP0STAT WP1STAT
WP2STAT W0H W0L W1H W1L
W2H W2L
Conditions which may be prefixed with X, Y, XY, NX, NY, and XY
AEQ ALE ALT MEQ MLE
MLT SEQ SF1 SF0 SLT
Conditions which may be prefixed with J, K, NJ, and NK
EQ LE LT CBQ CB1
Conditions which may be prefixed with N
ISF0 ISF1 LC0E LC1E BM
FLAG0_IN FLAG1_IN FLAG2_IN FLAG3_IN
1-48 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Extend these sets of keywords with symbols that declare sections,
variables, constants, and address labels. When defining symbols in
assembly source code, follow these conventions:
• Define symbols that are unique within the file in which they are
declared.
If you use a symbol in more than one file, use the
.GLOBAL assembly
directive to export the symbol from the file in which it is defined.
Then use the .EXTERN assembly directive to import the symbol into
other files.
• Begin symbols with alphabetic characters.
Symbols can use alphabetic characters (A—Z and a—z), digits (0—9),
and the special characters “$” and “_” (dollar sign and underscore)
as well as “.” (dot).
Symbols are case sensitive; so input_addr and INPUT_ADDR define
unique variables.
The dot, point, or period “.” as the first character of a symbol
triggers special behavior in the VisualDSP++ environment.
A symbol with a “.” as the first character cannot have a digit as the
second character. Such symbols will not appear in the symbol table,
which is accessible in the debugger. A symbol name in which the
first two characters are dots will not appear even in the symbol
table of the object.
The compiler and run-time libraries prepend “
_” to avoid using
symbols in the user namespace that begin with an alphabetic
character.
• Do not use a reserved keyword to define a symbol.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-49
Assembler Syntax Reference
• Match source and LDF sections’ symbols.
Ensure that
.SECTION name symbols do not conflict with the
linker’s keywords in the .ldf file. The linker uses sections’ name
symbols to place code and data in the processor’s memory.
For details, see the VisualDSP++ 5.0 Linker and Utilities Manual.
Ensure that .SECTION name symbols do not begin with the “.”
(dot).
• Terminate the definition of address label symbols with a colon (:).
• The reserved word list for processors includes some keywords with
commonly used spellings; therefore, ensure correct syntax spelling.
Address label symbols may appear at the beginning of an instruction line
or stand-alone on the preceding line.
The following disassociated lines of code demonstrate symbol usage.
.BYTE2 xoperand; /* xoperand is a 16-bit variable */
.BYTE4 input_array[10]; /* input_array is a 32-bit wide */
/* data buffer with 10 elements */
sub_routine_1: /* sub_routine_1 is a label */
.SECTION kernel; /* kernel is a section name */
Assembler Expressions
The assembler can evaluate simple expressions in source code. The
assembler supports two types of expressions: constant expressions and
symbolic expressions.
1-50 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Constant Expressions
A constant expression is acceptable where a numeric value is expected in
an assembly instruction or in a preprocessor command. Constant expressions contain an arithmetic or logical operation on two or more numeric
constants. For example,
2.9e-5 + 1.29
(128-48)/3
0x55&
0x0f7.6r – 0.8r
For information about fraction type support, refer to “Fractional Type
Support” on page 1-57.
Symbolic Expressions
Symbolic expressions contain symbols, whose values may not be known
until link-time. For example,
data/8
(data_buffer1 + data_buffer2) & 0xF
strtup + 2
data_buffer1 + LENGTH(data_buffer2)*2
Symbols in this type of expression are data variables, data buffers, and
program labels. In the first three examples above, the symbol name represents the address of the symbol. The fourth example combines that
meaning of a symbol with a use of the length operator (see Table 1-13).
Assembler Operators
Table 1-12 lists the assembler’s numeric and bitwise operators used in
constant expressions and address expressions. These operators are listed in
group order from highest precedence to lowest precedence. Operators
with the highest precedence are evaluated first. When two operators have
the same precedence, the assembler evaluates the left-most operator first.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-51
Assembler Syntax Reference
Relational operators are supported only in relational expressions in
conditional assembly, as described in “Conditional Assembly Directives”
on page 1-60.
Table 1-12. Operator Precedence
Operator Usage Description Designation Processors
(expression) expression in parentheses
evaluates first
Parentheses All
~
-
*
/
%
+
-
<<
>>
& Bitwise AND All
| Bitwise inclusive OR All
^ Bitwise exclusive OR TigerSHARC and
&& Logical AND TigerSHARC only
|| Logical OR TigerSHARC only
Ones complement
Unary minus
Multiply
Divide
Modulus
Addition
Subtraction
Shift left
Shift right
Tilde
Minus
Asterisk
Slash
Percentage
Plus
Minus
All
All
All
All
SHARC
If right-shifting a negative value, ones are shifted in from the MSB,
L
which preserves the sign bit.
The assembler also supports special operators. Table 1-13 lists and
describes special operators used in constant and address expressions.
The ADDRESS and LENGTH operators can be used with external symbols—
apply them to symbols that are defined in other sections as
.GLOBAL
symbols.
1-52 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Table 1-13. Special Assembler Operators
Operator Usage Description
ADDRESS(symbol) Address of symbol
Note: Used with SHARC and TigerSHARC assemblers only.
BITPOS(constant) Bit position (Blackfin processors only)
Assembler
HI(expression)
LO(expression)
LENGTH(symbol) Length of symbol in number of elements (in a buffer/array)
symbol Address pointer to symbol
Extracts the most significant 16 bits of expression.
Extracts the least significant 16 bits of expression.
Note: Used with the Blackfin assembler only where
replaces the ADRRESS() operator. The expression in the HI and
LO operators can be either symbolic or constant.
HI/LO
Blackfin Processor Example:
The following example demonstrates how Blackfin assembler operators are
used to load the length and address information into registers.
#define n 20
...
.SECTION data1; /* data section */
.VAR real_data [n]; /* n=number of input sampless */
.SECTION program; /* code section */
P0.L = real_data;
P0.H = real_data;
P1=LENGTH(real_data); /* buffer's length */
LOOP loop1 LC0=P1;
LOOP_BEGIN loop1;
R0=[P0++]; /* get next sample */
...
LOOP_END loop1;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-53
Assembler Syntax Reference
The code fragment above initializes
P0 and P1 to the base address and
length, respectively, of the real_data buffer. The loop is executed 20
times.
The BITPOS() operator takes a bit constant (with one bit set) and returns
the position of the bit. Therefore, BITPOS(0x10) would return 4 and
BITPOS(0x80) would return 7. For example,
#define DLAB 0x80
#define EPS 0x10
R0 = DLAB | EPS (z);
cc = BITSET (R0, BITPOS(DLAB));
TigerSHARC Processor Example:
The following example demonstrates how assembler operators are used to
load the length and address information into registers (when setting up
circular buffers in TigerSHARC processors).
.SECTION data1; /* Data segment */
.VAR real_data[n]; /* n = number of input samples */
...
.SECTION program; /* Code segment */
/* Load the base address of */
the circular buffer */
JB3 = real_data;;
/* Load the index */
J3=real_data;;
/* Load the circular buffer length */
JL3 = LENGTH(real_data);;
/* Set loop counter 0 with buffer length */
LC0 = JL3;;
start:
XR0 = CB [J3 += 1];; /* Read data from the circular buffer */
if NLC0E, jump start;;
1-54 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
The code fragment above initializes
JB3 and JL3 to the base address and
length, respectively, of the real_data circular buffer. The buffer length
value contained in JL3 determines when addressing wraps around the top
of the buffer. For further information on circular buffers, refer to the
Hardware Reference of the target processor.
SHARC Processor Example:
The following code example determines the base address and length of the
real_data circular buffer. The buffer’s length value (contained in L5)
determines when addressing wraps around to the top of the buffer (when
setting up circular buffers in SHARC processors). For further information
on circular buffers, refer to the Hardware Reference of the target processor.
.SECTION/DM seg_dmda; /* data segment */
.VAR real_data[n]; /* n=number of input samples */
...
.SECTION/PM seg_pmco; /* code segment */
B5=real_data; /* buffer base address */
/* I5 loads automatically */
L5=length(real_data); /* buffer’s length */
M6=1; /* post-modify I5 by 1 */
LCNTR=length(real_data)
,DO loopend UNTIL LCE;
/* loop counter=buffer’s length */
F0=DM(I5,M6); /* get next sample */
...
loopend:
...
L
with the legacy @ operator, it is recommended to use LENGTH() in
place of
@.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-55
Although the SHARC assembler accepts the source code written
Assembler Syntax Reference
Numeric Formats
Depending on the processor architectures, the assemblers support binary,
decimal, hexadecimal, floating-point, and fractional numeric formats
(bases) within expressions and assembly instructions. Table 1-14 describes
the notation conventions used by the assembler to distinguish between
numeric formats.
Table 1-14. Numeric Formats
Convention Description
0xnumber The “0x” prefix indicates a hexadecimal number
B#number
b#number
number.number[e {+/-} number] Entry for floating-point number
number No prefix and no decimal point indicates a decimal number
numberr The “r” suffix indicates a fractional number
The “B#” or “b#” prefix indicates a binary number
Due to the support for b# and B# binary notation, the preprocessor
L
stringization functionality is turned off, by default, to avoid
possible undesired stringization.
For more information, refer to the processor’s # (Argument),
-stringize, and the assembler’s -flags-pp -opt1 [,-opt2...] com-
mand-line switches.
Representation of Constants in Blackfin
The Blackfin assembler keeps an internal 32-bit signed representation
of all constant values. Keep this in mind when working with immediate
values. The immediate value is used by the assembler to determine the
instruction length (16 or 32 bit). The assembler selects the smallest
opcode that can accommodate the immediate value.
1-56 VisualDSP++ 5.0 Assembler and Preprocessor Manual
If there is no opcode that can accommodate the value, semantic error
ea5003 is reported.
Examples:
R0 = -64; /* 16-bit instruction: -64 fits into
7-bit immediate value */
R0 = 0xBF; /* 32-bit instruction: 191 fits into 16-bit
immediate value */
R0 = 0xFFBF; /* ERROR:65471 doesn’t fit into 7 or 16-bit
immediate values */
R0 = 0xFFFFFFBF; /* 32-bit instruction: -65 fits into 16 bit
immediate value */
R0 = 0x8000; /* ERROR:32768 doesn’t fit into 7 or 16-bit
immediate values */
Fractional Type Support
Assembler
Fractional (fract) constants are specially marked floating-point constants
to be represented in fixed-point format. A fract constant uses the floating-point representation with a trailing “r”, where r stands for fract.
The legal range is [–1…1). This means the values must be greater than or
equal to –1 and less than 1. Fracts are represented as signed values.
For example,
.VAR myFracts[] = {0.5r, -0.5e-4r, -0.25e-3r, 0.875r};
/* Constants are examples of legal fracts */
.VAR OutOfRangeFract = 1.5r;
/* [Error …] Fract constant '1.5r' is out of range.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-57
Assembler Syntax Reference
Fract constants must be greater than or equal to -1
and less than 1. */
L
(in .BYTE4/R32 or .VAR/R32) to support 32-bit initialization for use
with 1.31 fracts.
In Blackfin processors, fract 1.15 is a default. Use a /R32 qualifier
1.31 Fracts
Fracts supported by Analog Devices processors use 1.31 format, which
means a sign bit and “31 bits of fraction”. This is –1 to +1–2**31.
For example, 1.31 maps the constant 0.5r to 2**31.
The conversion formula used by processors to convert from floating-point
format to fixed-point format uses a scale factor of 31.
For example,
.VAR/R32 myFract = 0.5r;
// Fract output for 0.5r is 0x4000 0000
// sign bit + 31 bits
// 0100 0000 0000 0000 0000 0000 0000 0000
// 4 0 0 0 0 0 0 0 = 0x4000 0000 =
.5r
.VAR/R32 myFract = -1.0r;
// Fract output for -1.0r is 0x8000 0000
// sign bit + 31 bits
// 1000 0000 0000 0000 0000 0000 0000 0000
//8000 0000= 0x8000
0000 = -1.0r
.VAR/R32 myFract = -1.72471041E-03r;
// Fract output for -1.72471041E-03 is 0xFFC77C15
// sign bit + 31 bits
// 1111 1111 1100 0111 0111 1100 0001 0101
//FFC77C 15
1-58 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
1.0r Special Case
1.0r is out-of-the-range fract. Specify 0x7FFF FFFF for the closest
approximation of 1.0r within the 1.31 representation.
Fractional Arithmetic
The assembler provides support for arithmetic expressions using
operations on fractional constants, consistent with the support for other
numeric types in constant expressions, as described in “Assembler Expres-
sions” on page 1-50.
The internal (intermediate) representation for expression evaluation is a
double floating-point value. Fract range checking is deferred until the
expression is evaluated. For example,
#define fromSomewhereElse 0.875r
.SECTION data1;
.VAR localOne = fromSomewhereElse + 0.005r;
// Result .88r is within the legal range
.VAR xyz = 1.5r -0.9r;
// Result .6r is within the legal range
.VAR abc = 1.5r; // Error: 1.5r out of range
Mixed Type Arithmetic
The assembler does not support arithmetic between fracts and integers.
For example,
.SECTION data1;
.VAR myFract = 1 - 0.5r;
[Error ea1998] "fract.asm":2 User Error: Illegal
mixing of types in expression.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-59
Assembler Syntax Reference
Comment Conventions
The assemblers support C and C++ style formats for inserting comments
in assembly sources. The assemblers do not support nested comments.
Table 1-15 lists and describes assembler comment conventions.
Table 1-15. Comment Conventions
Convention Description
/* comment */ A “/* */” string encloses a multiple-line comment
// comment A pair of slashes “//” begin a single-line comment
Conditional Assembly Directives
Conditional assembly directives are used for evaluation of assembly-time
constants using relational expressions. The expressions may include
relational and logical operations. In addition to integer arithmetic, the
operands may be the C structs in the SIZEOF() and OFFSETOF() assembly
built-in functions that return integers.
The conditional assembly directives include:
• .IF constant-relational-expression;
• .ELIF constant-relational-expression;
• .ELSE;
• .ENDIF;
Conditional assembly blocks begin with an .IF directive and end with
.ENDIF directive. Table 1-16 shows examples of conditional directives.
an
Optionally, any number of
.ELIF and .ELSE directive pairs may appear
within a pair of .IF and .ENDIF directives. The conditional directives are
each terminated with a semi-colon “
;”, just like all existing assembler
1-60 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-16. Relational Operators for Conditional Assembly
Operator Purpose Conditional Directive Examples
! Not .IF !0;
> Greater than .IF ( SIZEOF(myStruct) > 16 );
>= Greater than or equal to .IF ( SIZEOF(myStruct) >= 16 );
< Less than .IF ( SIZEOF(myStruct) < 16 );
<= Less than or equal to .IF ( SIZEOF(myStruct) <= 16 );
== Equality .IF ( 8 == SIZEOF(myStruct) );
!= Not equal .IF ( 8 != SIZEOF(myStruct) );
|| Logical OR .IF (2 !=4 ) || (5 == 5);
&& Logical AND .IF (SIZEOF(char) == 2 && SIZEOF(int) ==
4);
directives. Conditional directives do not have to appear alone on a line.
These directives are in addition to the C-style
#endif preprocessing directives.
#if, #elif, #else, and
The .IF, .ELSE, .ELIF, and .ENDIF directives (in any case) are
L
reserved keywords.
The .IF conditional assembly directive must be used to query about C
structs in assembly using the
SIZEOF() and/or OFFSETOF() built-in
functions. These built-ins are evaluated at assembly time, so they cannot
appear in expressions in
#if preprocessor directives.
In addition, the SIZEOF() and OFFSETOF() built-in functions (see “C
Struct Support in Assembly Built-In Functions” on page 1-63) can be
used in relational expressions. Different code sequences can be included
based on the result of the expression.
For example,
SIZEOF(struct/typedef/C_base_type) is permitted.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-61
Assembler Syntax Reference
The assembler supports nested conditional directives. The outer
conditional result propagates to the inner condition, just as it does in C
preprocessing.
Assembler directives are distinct from preprocessor directives, as follows:
• The
# directives are evaluated during preprocessing by the
preprocessor. Therefore, preprocessor #if directives cannot use
assembler built-ins (see “C Struct Support in Assembly Built-In
Functions” on page 1-63).
• The conditional assembly directives are processed by the assembler
in a later pass. Therefore, you are able to write a relational or
logical expression whose value depends on the value of a #define.
For example,
.IF tryit == 2;
<some code>
.ELIF tryit >= 3;
<some more code>
.ELSE;
<some more code>
.ENDIF;
If you have “#define tryit 2”, the code <some code> is assembled,
and
<some more code> is not assembled.
• There are no parallel assembler directives for C-style directives
#define, #include, #ifdef, #if defined(name), #ifndef, and so
on.
1-62 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
C Struct Support in Assembly Built-In Functions
The assemblers support built-in functions that enable you to pass information obtained from the imported C struct layouts. The assemblers
currently support two built-in functions: OFFSETOF() and SIZEOF().
OFFSETOF Built-In Function
The OFFSETOF() built-in function is used to calculate the offset of a
specified member from the beginning of its parent data structure.
OFFSETOF(struct/typedef,memberName);
where:
struct/typedef – a struct VAR or a typedef can be supplied as the first
argument
memberName – a member name within the struct or typedef (second
argument)
L
SIZEOF Built-In Function
The
with an imported C struct or data member. It provides functionality
similar to its C counterpart.
SIZEOF(struct/typedef/C_base_type);
where:
The
A symbolic reference is a name followed by none or several qualifiers
to members.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-63
For SHARC and TigerSHARC processors, OFFSETOF() units are in
words. For Blackfin processors, OFFSETOF() units are in bytes.
SIZEOF() built-in function returns the amount of storage associated
SIZEOF() function takes a symbolic reference as its single argument.
Assembler Syntax Reference
The
SIZEOF() function gives the amount of storage associated with:
• An aggregate type (structure)
• A C base type (int, char, and so on)
• A member of a structure (any type)
For example (Blackfin processor code):
.IMPORT "Celebrity.h";
.EXTERN STRUCT Celebrity StNick;
L3 = SIZEOF(Celebrity); // typedef
L3 = SIZEOF(StNick); // struct var of typedef
Celebrity
L3 = SIZEOF(char); // C built-in type
L3 = SIZEOF(StNick->Town); // member of a struct var
L3 = SIZEOF(Celebrity->Town); // member of a struct typedef
L
priate for its processor. For SHARC and TigerSHARC processors,
units are in words. For Blackfin processors, units are in bytes.
When applied to a structure type or variable, SIZEOF() returns the actual
size, which may include padding bytes inserted for alignment. When
applied to a statically dimensioned array, SIZEOF() returns the size of the
entire array.
Struct References
A reference to a struct VAR provides an absolute address. For a fully
qualified reference to a member, the address is offset to the correct location within the struct. The assembler syntax for struct references is “->”.
The SIZEOF() built-in function returns the size in the units appro-
The following example references the address of
myStruct.
1-64 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Member5 located within
Assembler
myStruct->Member5
If the struct layout changes, there is no need to change the reference.
The assembler recalculates the offset when the source is reassembled with
the updated header.
Nested struct references are supported. For example,
myStruct->nestedRef->AnotherMember
L
are always referenced with “->” (not “.”) because “.” is a legal
character in identifiers in assembly and is not available as a struct
reference.
References within nested structures are permitted. A nested struct
definition can be provided in a single reference in assembly code, and a
nested struct via a pointer type requires more than one instruction.
Use the OFFSETOF() built-in function to avoid hard-coded offsets that may
become invalid if the struct layout changes in the future.
Following are two nested struct examples for .IMPORT "CHeaderFile.h".
Example 1:
Nested Reference Within the Struct Definition with
Appropriate C Declarations
C Code
struct Location {
char Town[16];
char State[16];
};
Unlike struct members in C, struct members in the assembler
struct myStructTag {
int field1;
struct Location NestedOne;
};
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-65
Assembler Syntax Reference
Assembly Code (for Blackfin Processors)
.EXTERN STRUCT myStructTag _myStruct;
P3.L = LO(_myStruct->NestedOne->State);
P3.H = HI(_myStruct->NestedOne->State);
Example 2:
Nested Reference When Nested via a Pointer with
Appropriate C Declarations
When nested via a pointer, myStructTagWithPtr (which has pNestedOne)
uses pointer register offset instructions.
C Code
// from C header
struct Location {
char Town[16];
char State[16];
};
struct myStructTagWithPtr {
int field1;
struct Location *pNestedOne;
};
Assembly Code (for Blackfin Processors)
// in assembly file
.EXTERN STRUCT myStructTagWithPtr _myStructWithPtr;
P1.L = LO(_myStructWithPtr->pNestedOne);
P1.H = HI(_myStructWithPtr->pNestedOne);
P0 = [P1 + OFFSETOF(Location,State)];
1-66 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Assembler Directives
Directives in an assembly source file control the assembly process. Unlike
assembly instructions, directives do not produce opcodes during assembly.
Use the following general syntax for assembler directives
.directive [/qualifiers | arguments];
Each assembler directive starts with a period (
.) and ends with a
semicolon (;). Some directives take qualifiers and arguments. A directive’s
qualifier immediately follows the directive and is separated by a slash (/);
arguments follow qualifiers. Assembler directives can be uppercase or
lowercase; uppercase distinguishes directives from other symbols in your
source code.
Table 1-17 lists all currently supported assembler directives. A description
of each directive appears in the following sections. These directives were
added for GNU compatibility.
Table 1-17. Assembler Directive Summary
Directive Description
.ALIGN
(on page 1-72)
.ALIGN_CODE
(on page 1-74)
.ASCII
(on page 1-76)
.BSS Equivalent to .SECTION/zero_init bsz;
Specifies an alignment requirement for data or code
Specifies an alignment requirement for code.
NOTE: TigerSHARC processors only.
Initializes ASCII strings.
NOTE: Blackfin processors only.
Refer to “.SECTION, Declare a Memory Section” on
page 1-122.
NOTE: Blackfin processors only.
.BYTE
.BYTE2
.BYTE4
(on page 1-77)
Defines and initializes one-, two-, and four-byte data objects,
respectively.
NOTE: Blackfin processors only.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-67
Assembler Syntax Reference
Table 1-17. Assembler Directive Summary (Cont’d)
Directive Description
.COMPRESS
(on page 1-81)
.DATA Equivalent to .SECTION data1;
Starts compression.
NOTE: ADSP-2146x SHARC processors only.
Refer to “.SECTION, Declare a Memory Section” on
page 1-122.
NOTE: Blackfin processors only.
.ELSE
Conditional assembly directive
(on page 1-60)
.ENDIF
Conditional assembly directive
(on page 1-60)
.ENDSEG
(on page 1-128)
Legacy directive. Marks the end of a section.
Used with legacy directive .SEGMENT that begins a section.
NOTE: SHARC processors only.
.EXTERN
Allows reference to a global symbol
(on page 1-81)
.EXTERN STRUCT
(on page 1-83)
.FILE
(on page 1-85)
.FILE_ATTR
Allows reference to a global symbol (struct) that was defined
in another file
Overrides filename given on the command line; used by C
compiler
Creates a attribute in the generated object file
(on page 1-86)
.FORCECOMPRESS
(on page 1-87)
.GLOBAL
Compresses the next instruction.
NOTE: ADSP-2146x SHARC processors only.
Changes a symbol’s scope from local to global
(on page 1-88)
.GLOBL Equivalent to .GLOBAL.
Refer to “.GLOBAL, Make a Symbol Available Globally” on
page 1-88.
NOTE: Blackfin processors only.
.IF
Conditional assembly directive
(on page 1-60)
1-68 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Table 1-17. Assembler Directive Summary (Cont’d)
Directive Description
Assembler
.IMPORT
(on page 1-90)
.INC/BINARY
Provides the assembler with the structure layout (C struct)
information
Includes the content of file at the current location
(on page 1-92)
.INCBIN Equivalent to .INC/BINARY.
Refer to “.INC/BINARY, Include Contents of a File” on
page 1-92.
NOTE: Blackfin processors only.
.LEFTMARGIN
Defines the width of the left margin of a listing
(on page 1-93)
.LIST/.NOLIST
Starts listing of source lines
(on page 1-94)
.LIST_DATA
Starts listing of data opcodes
(on page 1-95)
.LIST_DATFILE
Starts listing of data initialization files
(on page 1-96)
.LIST_DEFTAB
Sets the default tab width for listings
(on page 1-97)
.LIST_LOCTAB
Sets the local tab width for listings
(on page 1-99)
.LIST_WRAPDATA
Starts wrapping opcodes that don’t fit listing column
(on page 1-100)
.LONG
(on page 1-101)
.MESSAGE
(on page 1-102)
.NEWPAGE
Supports four-byte data initializer lists for GNU compatibility.
NOTE: Blackfin processors only.
Alters the severity of an error, warning or informational message generated by the assembler
Inserts a page break in a listing
(on page 1-106)
.NOCOMPRESS
(on page 1-107)
Terminates compression.
NOTE: ADSP-2146x SHARC processors only.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-69
Assembler Syntax Reference
Table 1-17. Assembler Directive Summary (Cont’d)
Directive Description
.NOLIST
(on page 1-94)
.NOLIST_DATA
(on page 1-95)
.NOLIST_DATFILE
(on page 1-96)
.NOLIST_WRAPDATA
(on page 1-100)
.PAGELENGTH
(on page 1-108)
.PAGEWIDTH
(on page 1-109)
.PORT
(on page 1-111)
.PRECISION
(on page 1-112)
.PREVIOUS
(on page 1-114)
.PRIORITY
(on page 1-115)
.REFERENCE
(on page 1-118)
Stops listing of source lines
Stops listing of data opcodes
Stops listing of data initialization files
Stops wrapping opcodes that do not fit listing column
Defines the length of a listing page
Defines the width of a listing page
Legacy directive. Declares a memory-mapped I/O port.
NOTE: SHARC processors only.
Defines the number of significant bits in a floating-point value.
NOTE: SHARC processors only.
Reverts to a previously described
.SECTION
Allows prioritized symbol mapping in the linker
Provides better information in an X-REF file.
Refer to “.REFERENCE, Provide Better Info in an X-REF
File” on page 1-118 for more information.
NOTE: Blackfin processors only.
.RETAIN_NAME
Stops the linker from eliminating a symbol
(on page 1-118)
.ROUND_NEAREST
(on page 1-119)
.ROUND_MINUS
(on page 1-119)
Specifies the Round-to-Nearest mode.
NOTE: SHARC processors only.
Specifies the Round-to-Negative Infinity mode.
NOTE: SHARC processors only.
1-70 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Table 1-17. Assembler Directive Summary (Cont’d)
Directive Description
Assembler
.ROUND_PLUS
(on page 1-119)
.ROUND_ZERO
(on page 1-119)
.SECTION
Specifies the Round-to-Positive Infinity mode.
NOTE: SHARC processors only.
Specifies the Round-to-Zero mode.
NOTE: SHARC processors only.
Marks the beginning of a section
(on page 1-122)
.SEGMENT
(on page 1-128)
.SEPARATE_MEM_SEGMENTS
(on page 1-128)
Legacy directive. Replaced with the .SECTION directive.
NOTE: SHARC processors only.
Specifies that two buffers should be placed into different
memory segments by the linker.
NOTE: TigerSHARC processors only.
.SET
Sets symbolic aliases
(on page 1-129)
.SHORT
(on page 1-129)
.STRUCT
(on page 1-130)
.TEXT Equivalent to .SECTION program;
Supports two-byte data initializer lists for GNU compatibility.
NOTE: Blackfin processors only.
Defines and initializes data objects based on C typedefs from
.IMPORT C header files
Refer to “.SECTION, Declare a Memory Section” on
page 1-122.
NOTE: Blackfin processors only.
.TYPE
Changes the default data type of a symbol; used by C compiler
(on page 1-134)
.VAR
Defines and initializes 32-bit data objects
(on page 1-135)
.WEAK
Creates a weak definition or reference
(on page 1-140)
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-71
Assembler Syntax Reference
.ALIGN, Specify an Address Alignment
The
.ALIGN directive forces the address alignment of an instruction or data
item. The assembler sets the alignment of the section to match the largest
alignment requirement specified in the section and inserts padding at each
alignment location to ensure that the following item has the proper offset
from the start of the section to maintain the requested alignment. The
linker honors the alignment specified by the assembler when placing the
section in memory, thus guaranteeing the integrity of the alignment of
each element aligned with a .ALIGN directive.
You also can use the INPUT_SECTION_ALIGN(#number) LDF command (in
the .ldf file) to force all the following input sections to the specified
alignment. Refer to the VisualDSP++ 5.0 Linker and Utilities Manual for
more information on section alignment.
Syntax:
.ALIGN expression;
where
expression – evaluates to an integer. It specifies an alignment require-
ment; its value must be a power of 2. When aligning a data item or
instruction, the assembler adjusts the address of the current location
counter to the next address that can be divided by the value of
expression, with no remainder. The expression set to 0 or 1 signifies no
address alignment requirement.
The linker stops allocating padding for symbols aligned by 16 or more.
L
1-72 VisualDSP++ 5.0 Assembler and Preprocessor Manual
In the absence of the .ALIGN directive, the default address
alignment is 1.
Assembler
Example:
In the following example, the assembler sets the alignment of the section
to 4 to match the value specified in the second alignment directive. This
satisfies the first alignment directive as well, since any item alignment on
an address multiple of 4 is also aligned on a multiple of 2. If the target is a
byte-addressed processor, such as Blackfin, there is no padding inserted
between “single” and “samples” since
.VAR creates a four-byte word of
storage. If the target is a processor on which the .VAR directive reserves a
one-address unit, such as SHARC, three words of padding follow “single”
in the section produced by the assembler.
...
.ALIGN 1; /* no alignment requirement */
...
.SECTION data1;
.ALIGN 2;
.VAR single; /* aligns the data item on the word boundary,
at the location with the address value that can
be evenly divided by 2 */
.ALIGN 4;
.VAR samples1[100]="data1.dat";
/* aligns the first data item on the double-word
boundary, at the location with the address value
that can be evenly divided by 4; advances other
data items consecutively */
L
as .VAR.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-73
The Blackfin assembler accepts .BYTE, .BYTE2, and .BYTE4 as well
Assembler Syntax Reference
.ALIGN_CODE, Specify an Address Alignment
L
Used with TigerSHARC processors only.
The .ALIGN_CODE directive forces the address alignment of an instruction
within the .SECTION in which it is used. .ALIGN_CODE is similar to the
.ALIGN directive, but whereas .ALIGN causes the code to be padded with
0s, .ALIGN_CODE pads with NOPs. The .ALIGN_CODE directive is used to
align instructions.
Refer to the VisualDSP++ 5.0 Linker and Utilities Manual for more information on section alignment.
Syntax:
.ALIGN_CODE expression;
where
expression – evaluates to an integer. It specifies an alignment require-
ment; its value must be a power of 2. In TigerSHARC processors, the
expression value is usually 4. When aligning a data item or instruction,
the assembler adjusts the address of the current location counter to the
next address that is divisible by the value of the expression. The expression set to 0 or 1 signifies no address alignment requirement.
L
Example:
.ALIGN_CODE 0; /* no alignment requirement */
...
.ALIGN_CODE 1; /* no alignment requirement */
...
.SECTION program;
.ALIGN_CODE 4;
1-74 VisualDSP++ 5.0 Assembler and Preprocessor Manual
In the absence of the .ALIGN_CODE directive, the default address
alignment is 1.
JUMP LABEL;;
/* Jump instruction aligned to four word boundary.
If necessary, padding will be done with NOPs */
Assembler
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-75
Assembler Syntax Reference
.ASCII
L
Used with Blackfin processors only.
The .ASCII directive initializes a data location with one or more characters from a double-quoted ASCII string. This is equivalent to the .BYTE
directive. Note that the syntax differs from the .BYTE directive as follows:
• There is no “=” sign
• The string is enclosed in double-quotes, not single quotes
Syntax:
.ASCII “string” ;
Example:
.SECTION data1;
ASCII_String:
.TYPE ASCII_String,STT_OBJECT;
.ASCII "ABCD";
.ASCII_String.end:
Byte_String:
.TYPE Byte_String,STT_OBJECT;
.Byte = ‘ABCD’;
.Byte_String.end:
1-76 VisualDSP++ 5.0 Assembler and Preprocessor Manual
.BYTE, Declare a Byte Data Variable or Buffer
Assembler
L
Used with Blackfin processors only.
The .BYTE, .BYTE2, and .BYTE4 directives declare and optionally initialize
one-, two-, and four-byte data objects, respectively. Note that the .BYTE4
directive performs the same function as the .VAR directive.
Syntax:
When declaring and/or initializing memory variables or buffer elements,
use one of these forms:
.BYTE varName1[,varName2,…];
.BYTE = initExpression1, initExpression2,…;
.BYTE varName1
.BYTE bufferName[] = initExpression1, initExpression2,…;
.BYTE bufferName[] = "fileName";
.BYTE bufferName[length
.BYTE bufferName[length] = initExpression1, initExpression2,…;
where:
varName – user-defined symbols that name variables
bufferName – user-defined symbols that name buffers
= initExpression,varName2 = initExpression2,…
] = " fileName";
fileName – indicates that the elements of a buffer get their initial values
from the fileName data file. The <fileName> parameter can consist of the
actual name and path specification for the data file. If the initialization file
is in current directory of your operating system, only the
be given inside double quote (
" ") characters. Note that when reading in a
fileName need
data file, the assembler reads in whitespace-separated lists of decimal digits
or hex strings.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-77
Assembler Syntax Reference
If the file name is not found in the current directory, the assembler looks
in the directories in the processor
include path. You may use the -I
switch (see on page 1-158) to add a directory to the processor include
path.
Initializing from files is useful for loading buffers with data, such as filter
coefficients or FFT phase rotation factors that are generated by other
programs. The assembler determines how the values are stored in memory
when it reads the data files.
Ellipsis (…) – represents a comma-delimited list of parameters.
initExpressions parameters – sets initial values for variables and buffer
elements
L
associated buffer in words. The number of initialization elements
defines length of an implicit-size buffer. The brackets [] that
enclose the optional [length] are required. For more information,
see the following .BYTE examples.
In addition, use a /R32 qualifier (.BYTE4/R32) to support 32-bit
initialization for use with 1.31 fracts (see on page 1-57).
The following lines of code demonstrate .BYTE directives:
Buffer1:
.TYPE Buffer1, STT_OBJECT;
.BYTE = 5, 6, 7;
// initialize three 8-bit memory locations
// for data label Buffer1
.Buffer1.end:
.BYTE samples[] = 123, 124, 125, 126, 127;
// declare an implicit-length buffer and initialize it
// with five 1-byte constants
.BYTE4/R32 points[] = 1.01r, 1.02r, 1.03r;
// declare and initialize an implicit-length buffer
The optional [length] parameter defines the length of the
1-78 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
// and initialize it with three 4-byte fract constants
.BYTE2 Ins, Outs, Remains;
// declare three 2-byte variables zero-initialized by
// default
.BYTE4 demo_codes[100] = "inits.dat";
// declare a 100-location buffer and initialize it
// with the contents of the inits.dat file;
.BYTE2 taps=100;
// declare a 2-byte variable and initialize it to 100
.BYTE twiddles[10] = "phase.dat";
// declare a 10-location buffer and load the buffer
// with contents of the phase.dat file
.BYTE4/R32 Fract_Byte4_R32[] = "fr32FormatFract.dat";
When declaring or initializing variables with .BYTE, consider constraints
applied to the .VAR directive. The .VAR directive allocates and optionally
initializes 32-bit data objects. For information about the .VAR directive,
refer to information on page 1-135.
ASCII String Initialization Support
The assembler supports ASCII string initialization. This allows the full use
of the ASCII character set, including digits and special characters.
In Blackfin processors, ASCII initialization can be provided with .BYTE,
.BYTE2, or .VAR directives. The most likely use is the .BYTE directive where
char is represented by one byte versus a .VAR directive in which each
each
char needs four bytes. The characters are stored in the upper byte of
32-bit words. The LSBs are cleared.
String initialization takes one of the following forms:
.BYTE symbolString[length] = ‘initString’, 0;
.BYTE symbolString [] = ’initString’, 0;
Note that the number of initialization characters defines the optional
length of a string (implicit-size initialization).
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-79
Assembler Syntax Reference
Example:
.BYTE k[13] = ‘Hello world!’, 0;
.BYTE k[] = ‘Hello world!’, 0;
The trailing zero character is optional. It simulates ANSI-C string
representation.
1-80 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Loading...