Analog Devices, Inc. reserves the right to change this product without
prior notice. Information furnished by Analog Devices is believed to be
accurate and reliable. However, no responsibility is assumed by Analog
Devices for its use; nor for any infringement of patents or other rights of
third parties which may result from its use. No license is granted by implication or otherwise under the patent rights of Analog Devices, Inc.
Trademark and Service Mark Notice
The Analog Devices logo, the CROSSCORE logo, VisualDSP++,
SHARC, TigerSHARC, Blackfin, and EZ-KIT Lite are registered trademarks of Analog Devices, Inc.
All other brand and product names are trademarks or service marks of
their respective owners.
CONTENTS
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 ..................................................................... xvii
MyAnalog.com ........................................................................ xvii
Processor Product Information ................................................ xviii
Related Documents .................................................................. xix
Online Technical Documentation .............................................. xx
Accessing Documentation From VisualDSP++ ....................... xx
Accessing Documentation From Windows ............................ xxi
Accessing Documentation From the Web .............................. xxi
VisualDSP++ 4.5 Assembler and Preprocessor Manualxi
-xiiVisualDSP++ 4.5 Assembler and Preprocessor Manual
PREFACE
Thank you for purchasing Analog Devices, Inc. development software for
digital signal processing (DSP) applications.
Purpose
The VisualDSP++ 4.5 Assembler and Preprocessor Manual contains infor-
mation about the assembler preprocessor utilties for the following Analog
Devices, Inc. processor families—SHARC® (ADSP-21xxx) processors,
TigerSHARC
processors.
®
(ADSP-TSxxx) processors, and Blackfin® (ADSP-BFxxx)
The manual describes how to write assembly programs for these processors
and 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++ 4.5 Assembler and Preprocessor Manualxiii
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 the assembler’s
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
The VisualDSP++ 4.5 Assembler and Preprocessor Manual is a new manual
that documents assembler support for all currently available Analog
Devices’ SHARC, TigerSHARC
“Supported Processors”.
Refer to VisualDSP++ 4.5 Product Release Bulletin for information on all
new and updated VisualDSP++® 4.5 features and other release
information.
xivVisualDSP++ 4.5 Assembler and Preprocessor Manual
and Blackfin processors listed in
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
•Contact your Analog Devices, Inc. local sales office or authorized
distributor
•Send questions by mail to:
Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
USA
VisualDSP++ 4.5 Assembler and Preprocessor Manualxv
Supported Processors
Supported Processors
The following is the list of Analog Devices, Inc. processors supported in
VisualDSP++ 4.5.
TigerSHARC (ADSP-TSxxx) Processors
The name “TigerSHARC” refers to a family of floating-point and
fixed-point [8-bit, 16-bit, and 32-bit] processors. VisualDSP++ currently
supports the following TigerSHARC processors:
ADSP-TS101 ADSP-TS201 ADSP-TS202 ADSP-TS203
SHARC (ADSP-21xxx) Processors
The name “SHARC” refers to a family of high-performance, 32-bit,
floating-point processors that can be used in speech, sound, graphics, and
imaging applications. VisualDSP++ currently supports the following
SHARC processors:
You can obtain product information from the Analog Devices Web site,
from the product CD-ROM, or from the printed publications (manuals).
Analog Devices is online at
mation about a broad range of products—analog integrated circuits,
amplifiers, converters, and digital signal processors.
MyAnalog.com
MyAnalog.com is a free feature of the Analog Devices Web site that allows
customization of a Web page to display only the latest information on
products you are interested in. You can also choose to receive weekly
e-mail notifications containing updates to the Web pages that meet your
interests.
sheets, code examples, and more.
VisualDSP++ 4.5 Assembler and Preprocessor Manualxvii
MyAnalog.com provides access to books, application notes, data
www.analog.com. Our Web site provides infor-
Product Information
Registration
Visit
www.myanalog.com to sign up. Click Register to use MyAnalog.com.
Registration takes about five minutes and serves as a means to select the
information you want to receive.
If you are already a registered user, just log on. Your user name is your
e-mail address.
Processor Product Information
For information on embedded processors and DSPs, visit our Web site at
www.analog.com/processors, which provides access to technical publica-
tions, data sheets, application notes, product overviews, and product
announcements.
You may also obtain additional information about Analog Devices and its
products in any of the following ways.
xviiiVisualDSP++ 4.5 Assembler and Preprocessor Manual
Related Documents
For information on product related development software, see these
publications:
•VisualDSP++ 4.5 Getting Started Guide
•VisualDSP++ 4.5 User’s Guide
•VisualDSP++ 4.5 C/C++ Compiler and Library Manual for SHARC
Processors
•VisualDSP++ 4.5 C/C++ Compiler and Library Manual for
TigerSHARC Processors
•VisualDSP++ 4.5 C/C++ Compiler and Library Manual for Blackfin
Processors
•VisualDSP++ 4.5 Assembler and Preprocessor Manual
Preface
•VisualDSP++ 4.5 Linker and Utilities Manual
•VisualDSP++ 4.5 Loader Manual
•VisualDSP++ 4.5 Product Release Bulletin
•VisualDSP++ Kernel (VDK) User’s Guide
•Device Drivers and System Services Manual for Blackfin Processors
•Quick Installation Reference Card
For hardware information, refer to your processors’s hardware reference,
programming reference, or data sheet. All documentation is available
online. Most documentation is available in printed form.
Visit the Technical Library Web site to access all processor and tools manuals and data sheets:
VisualDSP++ 4.5 Assembler and Preprocessor Manualxix
Product Information
Online Technical Documentation
Online documentation includes the VisualDSP++ Help system, software
tools manuals, hardware tools manuals, processor manuals, Dinkum
Abridged C++ library, and Flexible License Manager (FlexLM) network
license manager software documentation. You can easily search across the
entire VisualDSP++ documentation set for any topic of interest using the
Search function of VisualDSP++ Help system. For easy printing, supplementary
Each documentation file type is described as follows.
File Description
.CHMHelp system files and manuals in Help format
.PDF files of most manuals are also provided.
.HTM or
.HTML
.PDFVisualDSP++ and processor manuals in Portable Documentation Format (PDF).
Dinkum Abridged C++ library and FlexLM network license manager software documentation. Viewing and printing the
Internet Explorer 5.01 (or higher).
Viewing and printing the
Reader (4.5 or higher).
.PDF files requires a PDF reader, such as Adobe Acrobat
.HTML files requires a browser, such as
Access the online documentation from the VisualDSP++ environment,
Windows
®
Explorer, or the Analog Devices Web site.
Accessing Documentation From VisualDSP++
From the VisualDSP++ environment:
•Access VisualDSP++ online Help from the Help menu’s Contents, Search, and Index commands.
•Open online Help from context-sensitive user interface items (toolbar buttons, menu commands, and windows).
xxVisualDSP++ 4.5 Assembler and Preprocessor Manual
Preface
Accessing Documentation From Windows
In addition to any shortcuts you may have constructed, there are many
ways to open VisualDSP++ online Help or the supplementary documentation from Windows.
Help system files (.
CHM) are located in the Help folder of VisualDSP++
environment. The .PDF files are located in the Docs folder of your
VisualDSP++ installation CD-ROM. The Docs folder also contains the
Dinkum Abridged C++ library and the FlexLM network license manager
software documentation.
Using Windows Explorer
•Double-click the vdsp-help.chm file, which is the master Help system, to access all the other .CHM files.
•Open your VisualDSP++ installation CD-ROM and double-click
any file that is part of the VisualDSP++ documentation set.
Using the Windows Start Button
•Access VisualDSP++ online Help by clicking the Start button and
choosing Programs, Analog Devices, VisualDSP++, and
VisualDSP++ Documentation.
Accessing Documentation From the Web
Download manuals in PDF format at the following Web site:
Select a processor family and book title. Download archive (.ZIP) files, one
for each manual. Use any archive management software, such as WinZip,
to decompress downloaded files.
VisualDSP++ 4.5 Assembler and Preprocessor Manualxxi
Product Information
Printed Manuals
For general questions regarding literature ordering, call the Literature
Center at 1-800-ANALOGD (1-800-262-5643) and follow the prompts.
VisualDSP++ Documentation Set
To purchase VisualDSP++ manuals, call 1-603-883-2430. The manuals
may be purchased only as a kit.
If you do not have an account with Analog Devices, you are referred to
Analog Devices distributors. For information on our distributors, log onto
http://www.analog.com/salesdir/continent.asp.
Hardware Tools Manuals
To purchase EZ-KIT Lite® and In-Circuit Emulator (ICE) manuals, call
1-603-883-2430. The manuals may be ordered by title or by product
number located on the back cover of each manual.
Processor Manuals
Hardware reference and instruction set reference manuals may be ordered
through the Literature Center at 1-800-ANALOGD (1-800-262-5643),
or downloaded from the Analog Devices Web site. Manuals may be
ordered by title or by product number located on the back cover of each
manual.
Data Sheets
All data sheets (preliminary and production) may be downloaded from the
Analog Devices Web site. Only production (final) data sheets (Rev. 0, A,
B, C, and so on) can be obtained from the Literature Center at
1-800-ANALOGD (1-800-262-5643); they also can be downloaded from
the Web site.
xxiiVisualDSP++ 4.5 Assembler and Preprocessor Manual
Preface
To have a data sheet faxed to you, call the Analog Devices Faxback System
at 1-800-446-6212. Follow the prompts and a list of data sheet code
numbers will be faxed to you. If the data sheet you want is not listed,
check for it on the Web site.
Notation Conventions
Text conventions used in this manual are identified and described as
follows.
L
ExampleDescription
Close command
(File menu)
{this | that}Alternative required items in syntax descriptions appear within curly
[this | that]Optional items in syntax descriptions appear within brackets and sepa-
[this,…]Optional item lists in syntax descriptions appear within brackets
.SECTIONCommands, directives, keywords, and feature names are in text with
filenameNon-keyword placeholders appear in text with italic style format.
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 this or
that. One or the other is required.
rated by vertical bars; read the example as an optional this or that.
delimited by commas and terminated with an ellipse; read the example
as an optional comma-separated list of
letter gothic font.
this.
Additional conventions, which apply only to specific chapters, may
VisualDSP++ 4.5 Assembler and Preprocessor Manualxxiii
Notation Conventions
ExampleDescription
Note: For correct operation, ...
A Note provides supplementary information on a related topic. In the
L
a
[
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.
Warning: 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.
xxivVisualDSP++ 4.5 Assembler and Preprocessor Manual
1ASSEMBLER
This chapter provides information on how to use the assembler for developing and assembling programs with SHARC (ADSP-21xxx) processors,
TigerSHARC (ADSP-TSxxx) processors, and Blackfin (ADSP-BFxxx)
processors.
The chapter contains:
•“Assembler Guide” on page 1-2
Describes the process of developing new programs in the processor’s assembly language
•“Assembler Syntax Reference” on page 1-33
Provides the assembler rules and conventions of syntax which are
used to define symbols (identifiers), expressions, and to describe
different numeric and comment formats
•“Assembler Command-Line Reference” on page 1-129
Provides reference information on the assembler’s switches and
conventions
L
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-1
The code examples in this manual have been compiled using
VisualDSP++ 4.5. The examples compiled with other versions of
VisualDSP++ may result in build errors or different output
although the highlighted algorithms stand and should continue to
stand in future releases of VisualDSP++.
Assembler Guide
Assembler Guide
In VisualDSP++ 4.5, the assembler drivers for each processor family run
from the VisualDSP++ Integrated Debugging and Development Environment (IDDE) or from an operating system command line. The assembler
processes assembly source, data, header files, and produces an object file.
Assembler operations depend on two types of controls: assembler directives and assembler switches.
VisualDSP++ 4.5 supports the following assembler drivers:
This section describes the process of developing 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:
•“Writing Assembly Programs” on page 1-3
•“Using Assembler Support for C Structs” on page 1-21
•“Preprocessing a Program” on page 1-24
•“Using Assembler Feature Macros” on page 1-26
•“Make Dependencies” on page 1-30
•“Reading a Listing File” on page 1-31
•“Statistical Profiling for Assembly Functions” on page 1-31
•“Specifying Assembler Options in VisualDSP++” on page 1-151
1-2VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
For information about the processor architecture, including the instruction set used when writing the assembly programs, see the hardware
reference manual and instruction set manual for an appropriate processor.
Assembler Overview
The assembler processes data from assembly source (.ASM), data (.DAT),
and include header (
Linkable Format (ELF), an industry-standard format for binary object
files. The object file name has a
In addition to the object file, the assembler can produce a listing file,
which shows the correspondence between the binary code and the source.
Assembler switches are specified from the VisualDSP++ IDDE or in the
command 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. See “Assembler Com-
mand-Line Reference” on page 1-129.
.H) files to generate object files in Executable and
.DOJ extension.
You can also set assembler options via the Assemble tab of the
VisualDSP++ Project Options dialog box (see “Specifying Assembler
Options in VisualDSP++” on page 1-151).
Writing Assembly Programs
Assembler directives are coded in assembly source files. The directives
allow you to define variables, set up some hardware features, and identify
program’s sections for placement within processor memory. The assembler
uses directives for guidance as it translates a source program into object
code.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-3
Assembler Guide
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 on page 1-4 shows a graphical overview of the assembly pro-
cess. The figure shows the preprocessor processing the assembly source
(.ASM) and header (.H) files.
Data initialization file
(.DAT)
Object file
Assembly source file
Preprocessor
preprocessed file (.IS)
(.DOJ)
(.ASM)
Intermediate
Assembler
Header file
(.H)
Listing file
(.LST)
Figure 1-1. Assembler Input and Output Files
1-4VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
Assemble your source files from the VisualDSP++ environment or using
any mechanism, such as a batch file or makefile, that will support invoking an appropriate assembler driver with a specified command-line
command. By default, the assembler processes an input 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 on the linker and archiver, see the VisualDSP++ 4.5 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 files are text files 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
.import directive on page 1-84.) 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 listname switch (on page 1-143) to
get a listing file.
The assembly source file may contain preprocessor commands, such as
#include
, that cause the preprocessor to include header files (.H) into the
source program. The preprocessor’s only output, an intermediate source
file (.IS), is the assembler’s primary input. In normal operation, the preprocessor output is a temporary file that will be deleted during the
assembly process.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-5
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 documented
in the processor’s instruction set manual. 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-10 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),
For a complete description of the assembler’s directive set, see “Assembler
Directives” on page 1-63.
Preprocessor Commands
Preprocessor commands begin with a pound sign (
#) and end with a car-
riage 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-36.
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.
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.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-7
Assembler Guide
Table 1-1, Table 1-2, and Table 1-3 show suggested input section names
for data and code that you could use 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 detailed information on the .LDF files, refer to the VisualDSP++ 4.5 Linker and Utilities Manual..
Table 1-1. Suggested Input Section Names for a SHARC LDF
.SECTION NameDescription
seg_pmcoA section in Program Memory that holds code
seg_dmdaA section in Data Memory that holds data
seg_pmdaA section in Program Memory that holds data
seg_rthA section in Program Memory that holds system initialization code
and interrupt service routines
Table 1-2. Suggested Input Section Names for a TigerSHARC LDF
.SECTION NameDescription
data1A section that holds data in Memory Block M1.
data2A section that holds data in Memory Block M2 (specified with the
PM memory qualifier).
programA section that holds code.
Table 1-3. Suggested Input Section Names for a Blackfin LDF
.SECTION NameDescription
data1A section that holds data.
programA section that holds code.
constdataA section that holds global data which is declared as constant, and
literal constants such as strings and array initializers.
1-8VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
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 the 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.
Use sections in a program to group elements to meet hardware constraints.
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 following sections in the source program:
Table 1-4. Sections in Source Program
SectionSHARCTigerSHARCBlackfin
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
seg_dmdadata1
data2
seg_pmcoprogramseg_rth
data1
constdata
program
Figure 1-2, Figure 1-3 on page 1-13, and Figure 1-4 on page 1-17
describe assembly code file structure for each of processor families. They
shows how a program divides into sections that match the memory segmentation of a DSP system. Notice that an assembly source may contain
preprocessor commands, such as
source code,
ros. The
#ifdef for conditional assembly, or #define to define mac-
SECTIONS{} commands define the .SECTION placements in the
#include to include other files in your
system’s 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.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-9
Assembler Guide
Code File Structure and LDF for SHARC Processors
Figure 1-2 describes assembly code file structure for SHARC processors.
Figure 1-2. Assembly Code File Structure for SHARC Processors
Looking at Figure 1-2, notice that the .PRECISION and .ROUND_ZERO direc-
tives tell 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.
Listing 1-1 shows a sample user-defined LDF for SHARC Processors.
Looking at the LDF’s
INPUT_SECTION commands map to the memory sections’ names (such as
program, data1, data2, ctor, heaptab, etc.) used in the example assembly
SECTIONS{} command, notice that the
sample program.
1-10VisualDSP++ 4.5 Assembler and Preprocessor Manual
1-12VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
Code File Structure and LDF for TigerSHARC Processors
Figure 1-3 describes assembly code file structure for TigerSHARC proces-
sors. Looking at Figure 1-3, notice that an assembly source may contain
preprocessor commands, such as #include to include other files in your
source code, #ifdef for conditional assembly, or #define to define
macros.
Assembler directives, such as .VAR, appear within sections to declare and
initialize variables.
Figure 1-3. Assembly Code File Structure for TigerSHARC Processors
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-13
Assembler Guide
Listing 1-2 shows a sample user-defined LDF for TigerSHARC proces-
sors. Looking at the LDF’s
INPUT_SECTION commands map to the memory sections’ names (such as
program, data1, data2, ctor, heaptab, etc.) used in the example assembly
SECTIONS{} command, notice that the
sample program.
Listing 1-2. Example Linker Description File for TigerSHARC Processors
1-14VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
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
{
Code File Structure and LDF for Blackfin Processo rs
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.
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 the Level 1 memory only. Level 2 memory and
external memory are not separated into instruction and data memory.
Listing 1-3 on page 1-18 shows a sample user-defined Linker Description
File. Looking at the LDF’s SECTIONS{} command, notice that the
INPUT_SECTION commands map to sections program, data1, constdata,
ctor, and seg_rth.
1-16VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
Figure 1-4. Assembly Source File Structure for Blackfin Processors
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-17
Assembler Guide
Listing 1-3. Example Linker Description File for Blackfin Processors
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-19
Assembler Guide
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++ 4.5 C/C++ Compiler and Library Manual for
appropriate target processors.
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++ 4.5 C/C++ Compiler and Library Manual for
appropriate target processors, which also includes a series of examples to
demonstrate how to mix C/C++ and assembly code.
1-20VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
Using Assembler Support for C Structs
The assembler supports C typedef/struct declarations within assembly
source. These are the assembler data directives and built-ins that provide
high-level programming features with C structs in the assembler:
•Data Directives:
.IMPORT(see on page 1-84)
.EXTERN STRUCT(see on page 1-78)
.STRUCT(see on page 1-118)
•C Struct in Assembly Built-ins:
OFFSETOF(struct/typedef,field) (see on page 1-59)
SIZEOF(struct/typedef) (see on page 1-59)
•Struct References:
struct->field (nesting supported) (see “Struct Refer-
ences” on page 1-60)
For more information on C struct support, refer to the “-flags-compiler”
command-line switch on page 1-139 and to “Reading a Listing File” on
page 1-31.
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 use reserved keywords , but it is legal to reference them in the context of the C
struct in assembly features.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-21
Assembler Guide
•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.
doubleMe:
// The code may look confusing, but I2 can be used both
// as a register and a struct member name
B2 = Sample1;
M2 = OFFSETOF(Sample1,I2);
R0 = DM(M2,I2);
R0 = R0+R0;
DM(M2,I2) = R0;
Assembler
L
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.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-23
For better code readability, avoid .STRUCT member names that have
Assembler Guide
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-14 lists preprocessor commands and provides a brief description of each command.
You can see the command line the assembler uses to invoke the preprocessor by adding the “-v[erbose]” switch (on page 1-149) to the assembler
command line or by selecting Generate verbose output on the Assemble
tab (property page) of the Project Options dialog box, accessible from the
Project menu. See “Specifying Assembler Options in VisualDSP++” on
page 1-151.
Preprocessor commands are useful for modifying assembly code. For
example, you can use the #include command to fill memory, load configuration registers, and set up processor parameters. You can use the
#define
instruction sequences. The preprocessor replaces each occurrence of the
macro reference with the corresponding value or series of instructions.
command to define constants and aliases for frequently used
For example, the macro MAXIMUM in the example on page 1-7 is replaced
with the number 100 during preprocessing.
For more information on the preprocessor command set, see “Preproces-
sor Command Reference” on page 2-14. For more information on
preprocessor usage, see “-flags-pp -opt1 [,-opt2...]” on page 1-140
Note that there is one important difference between the assembler preprocessor and compiler preprocessor. The assembler preprocessor treats the
character “.” as part of an identifier. Thus, “
and will not match a preprocessor macro “
.EXTERN” is a single identifier
EXTERN”.
This behavior can affect how macro expansion is done for some
instructions.
1-24VisualDSP++ 4.5 Assembler and Preprocessor Manual
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;
// “.” is part of token
Assembler
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-25
Assembler Guide
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 the programmer to use
preprocessor conditional commands to configure the source for assembly
based on the context.
Table 1-5 provides the set of feature macros for SHARC processors.
Table 1-5. Feature Macros for SHARC Processors
-D_LANGUAGE_ASM=1Always 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
Present when running easm21K -proc ADSP-21020
with ADSP-21020 processors
Present when running easm21K -proc ADSP-21060
with ADSP-21060 processors
Present when running easm21K -proc ADSP-21061
with ADSP-21061 processors
Present when running easm21K -proc ADSP-21062
with ADSP-21062 processors
Present when running easm21K -proc ADSP-21065L
with ADSP-21065L processors
Present when running easm21K -proc ADSP-21160
with ADSP-21160 processors
Present when running easm21K -proc ADSP-21161
with ADSP-21161 processors
Present when running easm21K -proc ADSP-21261
with ADSP-21261 processors
Present when running easm21K -proc ADSP-21262
with ADSP-21262 processors
1-26VisualDSP++ 4.5 Assembler and Preprocessor Manual
Table 1-5. Feature Macros for SHARC Processors (Cont’d)
Assembler
-D__ADSP21266__=1
-D__2126x__=1
-D__ADSP21267__=1
-D__2126x__=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__2136x__=1
-D__ADSP21371__=1
-D__2136x__=1
Present when running easm21K -proc ADSP-21266
with ADSP-21266 processors
Present when running easm21K -proc ADSP-21267
with ADSP-21267 processors
Present when running easm21K -proc ADSP-21363
with ADSP-21363 processors
Present when running easm21K -proc ADSP-21364
with ADSP-21364 processors
Present when running easm21K -proc ADSP-21365
with ADSP-21365 processors
Present when running easm21K -proc ADSP-21366
with ADSP-21366 processors
Present when running easm21K -proc ADSP-21367
with ADSP-21367 processors
Present when running easm21K -proc ADSP-21368
with ADSP-21368 processors
Present when running easm21K -proc ADSP-21369
with ADSP-21369 processors
Present when running easm21K -proc ADSP-2137x
with ADSP-2137x processors
Present when running easm21K -proc ADSP-21371
with ADSP-21371 processors
-D__ADSP21375__=1
-D__2136x__=1
Present when running easm21K -proc ADSP-21375
with ADSP-21375 processors
Table 1-6 provides the set of feature macros for TigerSHARC processors.
Table 1-6. Feature Macros for TigerSHARC Processors
-D_LANGUAGE_ASM =1Always present
-D__ADSPTS__ =1 Always present
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-27
Assembler Guide
Table 1-6. Feature Macros for TigerSHARC Processors (Cont’d)
-D__ADSPTS101__ =1Present when running easmts -proc ADSP-TS101
with ADSP-TS101 processor
-D__ADSPTS201__ =1Present when running easmts -proc ADSP-TS201
with ADSP-TS201 processor
-D__ADSPTS202__ =1Present when running easmts -proc ADSP-TS202
with ADSP-TS202 processor
-D__ADSPTS203__ =1Present when running easmts -proc ADSP-TS203
with ADSP-TS203 processor
-D__ADSPTS20x__ =1Present when running easmts -proc ADSP-TS201 with
ADSP-TS201 processor, easmts -proc ADSP-TS202 with
ADSP-TS202 processor, or
easmts -proc ADSP-TS203 with
ADSP-TS203 processor.
Table 1-7 provides the set of feature macros for Blackfin processors.
Table 1-7. Feature Macros for Blackfin Processors
-D_LANGUAGE_ASM=1Always present
-D__ADSPBLACKFIN__ =1 Always present
-D__ADSPLPBLACKFIN__
=1
-D__ADSPBF531__=1
-D__ADSP21531__=1
-D__ADSPBF532__=1
-D__ADSP21532__=1
-D__ADSPBF533__=1
-D__ADSP21533__=1
-D__ADSPBF534__=1Present when running easmblkfn -proc ADSP-BF534
Always present for non-ADSP-BF535 processors
Present when running easmblkfn -proc ADSP-BF531
with ADSP-BF531 processor.
Present when running easmblkfn -proc ADSP-BF532
with ADSP-BF532 processor.
Present when running easmblkfn -proc ADSP-BF533
with ADSP-BF533 processor.
with ADSP-BF534 processor.
-D__ADSPBF535__=1
-D__ADSP21535__=1
-D__ADSPBF536__=1Present when running easmblkfn -proc ADSP-BF536
Present when running easmblkfn -proc ADSP-BF535
with ADSP-BF535 processor.
with ADSP-BF536 processor.
1-28VisualDSP++ 4.5 Assembler and Preprocessor Manual
Table 1-7. Feature Macros for Blackfin Processors (Cont’d)
-D__ADSPBF537__=1Present when running easmblkfn -proc ADSP-BF537
with ADSP-BF537 processor.
-D__ADSPBF538__=1Present when running easmblkfn -proc ADSP-BF538
with ADSP-BF538 processor.
-D__ADSPBF539__=1Present when running easmblkfn -proc ADSP-BF539
with ADSP-BF539 processor.
-D__ADSPBF561__=1Present when running easmblkfn -proc ADSP-BF561
with ADSP-BF561 processor.
-D__AD6531__=1Present when running easmblkfn -proc AD6531
with AD6531 processor.
-D__AD6532__=1Present when running easmblkfn -proc AD6532
with AD6532 processor.
-D__AD6900__=1Present when running easmblkfn -proc AD6900
with AD6900 processor.
Assembler
-D__AD6901__=1Present when running easmblkfn -proc AD6901
with AD6901 processor.
-D__AD6902__=1Present when running easmblkfn -proc AD6902
with AD6902 processor.
-D__AD6903__=1Present when running easmblkfn -proc AD6903
with AD6903 processor.
For the .IMPORT headers, the assembler calls the compiler driver with the
appropriate processor option and the compiler sets the machine constants
accordingly (and defines
used for C compiler calls to specify headers. It replaces
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-29
Assembler Guide
L
Refer to Chapter 1 in the VisualDSP++ 4.5 C/C++ Compiler and
Library Manual of the appropriate target processors for more
information.
Make Dependencies
The assembler can generate “make dependencies” for a file to allow the
VisualDSP++ and other makefile-based build environments to determine
when to rebuild an object file due to changes in the input files. The assembler source file and any files mentioned in the #include commands,
.IMPORT directives, or buffer initializations (in .VAR and .STRUCT directives)
constitute the “make dependencies” for an object file.
When the user requests 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 dependen-
cies from the .IMPORT headers.
For example,
Use the -verbose option to verify what macro is default-defined.
1-30VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
In this case,
def_LPBlackfin.h.
defBF533.h includes defBF532.h which includes
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 listname option (as shown on page 1-143) to get
a listing file.
Statistical Profiling for Assembly Functions
Use the following steps to enable the Statistical Profiling in assembler
sources.
1. When using the VisualDSP++ IDDE, use the Assemble option
from the Project Options dialog box (Figure 1-8) to select and/or
set assembler functional options.
2. Select Assemble - Generate Debug Information.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-31
Assembler Guide
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
'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 Assembler Additional Options
field in the Assembly tab (refer to “WARNING ea1121: Missing
End Labels” on page 1-141 for more information).
5. Select Statistical Profiling - New Profile or Linear Profiling -New Profile options 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-32VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
Assembler Syntax Reference
When you develop 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 conventions of syntax 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-34
•“Assembler Expressions” on page 1-47
•“Assembler Operators” on page 1-48
•“Numeric Formats” on page 1-52
•“Comment Conventions” on page 1-55
•“Conditional Assembly Directives” on page 1-55
•“C Struct Support in Assembly Built-In Functions” on page 1-59
•“Struct References” on page 1-60
•“Assembler Directives” on page 1-63
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-33
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 the assembler keywords for supported processors.
Although the keywords in the listings 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-8 lists the assembler keywords for SHARC processors.
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
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-45
Assembler Syntax Reference
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 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 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 times prepend “_” to avoid using symbols in
the user name space that begin with an alphabetic character.
•Do not use a reserved keyword to define a symbol.
•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 processor’s memory. For more
details, see the VisualDSP++ 4.5 Linker and Utilities Manual .
Ensure that .SECTION name symbols do not begin with the “.”
(dot).
1-46VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
•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 and symbolic.
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&0x0f
7.6r – 0.8r
For information about fraction type support, refer to “Fractional Type
Support” on page 1-53.
Symbolic Expressions
Symbolic expressions contain symbols, whose values may not be known
until link time. For example,
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-47
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 combines that meaning of a symbol
with a use of the length operator (see Table 1-12).
Assembler Operators
Table 1-11 lists the assembler’s numeric and bitwise operators used in
constant expressions and address expressions. These operators are listed in
group order from highest to lowest precedence. Operators with highest
precedence are evaluated first. When two operators have the same precedence, the assembler evaluates the left-most operator first. Relational
operators are only supported in relational expressions in conditional
assembly, as described in “Conditional Assembly Directives” on
page 1-55.
Table 1-11. Operator Precedence
OperatorUsage DescriptionDesignation
(expression)expression in parentheses evaluates first
~
-
*
/
%
+
-
<<
>>
&Bitwise AND (preprocessor only)
Ones complement
Unary minus
Multiply
Divide
Modulus
Addition
Subtraction
Shift left
Shift right
Tilde
Minus
Asterisk
Slash
Percentage
Plus
Minus
1-48VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
Table 1-11. Operator Precedence (Cont’d)
OperatorUsage DescriptionDesignation
|
^
&&
||
Bitwise inclusive OR
Bitwise exclusive OR (preprocessor only)
Logical AND
Logical OR
The assembler also supports special operators. Table 1-12 lists and
describes these operators used in constant and address expressions.
Table 1-12. Special Assembler Operators
OperatorUsage Description
ADDRESS(symbol)Address of symbol
Note: Used with SHARC and TigerSHARC assemblers only.
BITPOS(constant)Bit position (Blackfin processors ONLY)
HI(expression)
LO(expression)
LENGTH(symbol)Length of symbol in number of elements (in a buffer/array)
symbolAddress 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
and “LO” operators can be either symbolic or constant.
ADRRESS() operator. The expression in the “HI”
HI/LO
The “address of” and “length of” operators can be used with external symbols—apply it to symbols that are defined in other sections as .GLOBAL
symbols.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-49
Assembler Syntax Reference
Blackfin Processor Example
The following code example demonstrates how the 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 sample
.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;
This code fragment initializes p0 and p1 to the base address and length,
respectively, of the buffer real_data. 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
The following example demonstrates how the 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
1-50VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
…
.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 circular buffer
if NLC0E, jump start;;
This code fragment initializes JB3 and JL3 to the base address and length,
respectively, of the circular buffer real_data. 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 manual of the target processor.
SHARC Processor Example
The following code example determines the base address and length of the
circular buffer real_data. 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 manual of the target
processor.
.SECTION/DM seg_dmda;// data segment
.VAR real_data[n];// n=number of input samples
…
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-51
Assembler Syntax Reference
,DO loopend UNTIL LCE;
F0=DM(I5,M6);// get next sample
…
loopend: …
// loop counter=buffer’s length
L
with the legacy @ operator, it is recommend to use LENGTH() in
place of @.
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-13 describes
the conventions of notation the assembler uses to distinguish between
numeric formats.
Table 1-13. Numeric Formats
ConventionDescription
0xnumber “0x” prefix indicates a hexadecimal number
Although the SHARC assembler accepts the source code written
B#number
b#number
number.number[e {+/-} number]Entry for floating-point number
numberNo prefix and no decimal point indicates a decimal number
“
B#” or “b#” prefix indicates a binary number
r “r” suffix indicates a fractional number
number
Due to the support for b# and B# binary notation, the preprocessor
L
stringization functionality has been turned off by default to avoid
possible undesired stringization.
For more information, refer to “# (Argument)” on page 2-32 and
1-52VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
the preprocessor’s “-stringize” command-line switch
(on page 2-44), and to the assembler’s “-flags-pp -opt1 [,-opt2...]”
command-line switch (on page 1-140).
Fractional Type Support
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 –1 and less than 1. Fracts are represented as signed values.
/* [Error ...] Fract constant '1.5r' is out of range.
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 the Analog Devices’ processors use 1.31 format,
meaning 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 the
floating-point to fixed-point
format
uses a scale factor of 31.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-53
Assembler Syntax Reference
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
//
.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
//
.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.0r Special Case
40000000
80000000= 0x8000 0000 = -1.0r
= 0x4000 0000 = .5r
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-47.
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,
1-54VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
// 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.
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-14 lists and describes assembler comment
conventions.
Table 1-14. Comment Conventions
ConventionDescription
/* comment */ A “/* */” string encloses a multiple-line comment
// commentA 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 assembly built-in functions SIZEOF()
and OFFSETOF() that return integers.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-55
Assembler Syntax Reference
The conditional assembly directives are:
•
.IF constant-relational-expression;
•.ELIFconstant-relational-expression;
•.ELSE;
•.ENDIF;
All conditional assembly blocks begin with an .IF directive and end with
an .ENDIF directive. Table 1-15 shows examples of conditional directives.
Table 1-15. Relational Operators for Conditional Assembly
within the .IF and .ENDIF. The conditional directives are each terminated
with a semi-colon “
;” just like all existing assembler directives. Condi-
tional directives do not have to appear alone on a line. These directives are
in addition to the C-style preprocessing directives
#endif.
#if, #elif, #else, and
The .IF, .ELSE, .ELIF and .ENDIF directives (in any case) are
L
reserved keywords.
1-56VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
The
.IF conditional assembly directives 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 the #if preprocessor directives.
In addition, the SIZEOF() and OFFSETOF() built-in functions (see
“C Struct Support in Assembly Built-In Functions” on page 1-59) can be
used in relational expressions. Different code sequences can be included
based on the result of the expression.
For example, a SIZEOF(struct/typedef/C base type) is permitted.
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:
•The # directives are evaluated during preprocessing by the preprocessor. Therefore, preprocessor’s #if directives cannot use the
assembler built-ins (see “C Struct Support in Assembly Built-In
Functions” on page 1-59).
•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;
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-57
Assembler Syntax Reference
If you have “
#define tryit 2”, then the code <some code> will be
assembled, <some more code> will not be.
•There are no parallel assembler directives for C-style directives
#define, #include, #ifdef, #if defined(name), #ifndef, and so
on.
1-58VisualDSP++ 4.5 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() Built-In Function
The
OFFSETOF() built-in function is used to calculate the offset of a speci-
fied member from the beginning of its parent data structure.
OFFSETOF( struct/typedef, memberName)
where:
struct/typedef – struct VAR or a typedef can be supplied as the
first argument
OFFSETOF() and SIZEOF().
memberName – a member name within the struct or typedef (sec-
ond argument)
For SHARC and TigerSHARC processors, OFFSETOF() units are in
L
words. For Blackfin processors, OFFSETOF() units are in bytes.
SIZEOF() Built-In Function
SIZEOF() built-in function returns the amount of storage associated
The
with an imported C struct or data member. It provides functionality similar to its C counterpart.
SIZEOF(struct/typedef/C base type);
where:
SIZEOF() built-in function takes a symbolic reference as its single
argument. A symbolic reference is a name followed by none or several qualifiers to members.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-59
Assembler Syntax Reference
The
SIZEOF() built-in function gives the amount of storage associ-
ated 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
The SIZEOF() built-in function returns the size in the units appro-
within the struct. The assembler syntax for
For example,
myStruct->Member5
struct references is “->”.
1-60VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
references the address of
Member5 located within myStruct. 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
Unlike struct members in C, struct members in the assembler are
L
always referenced with “->” (and not “.”) because “.” is a legal character in identifiers in assembly and 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 while a nested
struct via a pointer type requires more than one instruction. Make use of
the OFFSETOF() built-in to avoid hard-coded offsets that could 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];
};
struct myStructTag {
int field1;
struct Location NestedOne;
};
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-61
1-62VisualDSP++ 4.5 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-16 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-16. Assembler Directive Summary
DirectiveDescription
.ALIGN
(see on page 1-68)
.ALIGN_CODE
(see on page 1-70)
.ASCII
(see on page 1-72)
.BYTE| .BYTE2| .BYTE4
(see on page 1-73)
.ELSE
(see on page 1-55)
.ENDIF
(see on page 1-55)
Specifies an alignment requirement for data or code
Specifies an alignment requirement for code.
NOTE: TigerSHARC processors ONLY.
Refer to “.GLOBAL, Make a Symbol Globally Available” on
page 1-82 for more information.
.INCBIN Includes binary files directly for section output.
.INCBIN is equivalent to .INC/BINARY (see on page 1-86).
.LONG EXPRESSION-LISTSupports four-byte data initializer lists.
.SHORT EXPRESSION-LISTSupports two-byte data initializer lists.
.TEXTEquivalent to .SECTION program;
Refer to “.SECTION, Declare a Memory Section” on
page 1-111 for more information.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-67
Assembler Syntax Reference
.ALIGN, Specify an Address Alignment
The
.ALIGN directive forces the address alignment of an instruction or
data item. Use it to ensure section alignments in the .LDF file. You may
use .ALIGN to ensure the alignment of the first element of a section, therefore providing the alignment of the object section (“INPUT SECTION” to the
linker). You may also use the INPUT_SECTION_ALIGN(#number) linker command in the .LDF file to force all the following input sections to the
specified alignment.
Refer to the VisualDSP++ 4.5 Linker and Utilities Manual for more information on section alignment.
Syntax:
.ALIGN expression;
where
expression – evaluates to an integer. It specifies an alignment
requirement; 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.
In the absence of the .ALIGN directive, the default address align-
1-68VisualDSP++ 4.5 Assembler and Preprocessor Manual
/* 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 */
Assembler
L
The Blackfin assembler uses .BYTE instead of .VAR.
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-69
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 it is used. It 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 when aligning
instructions.
Refer to Chapter 2 “Linker” in the VisualDSP++ 4.5 Linker and Utilities Manual for more information on section alignment.
Syntax:
.ALIGN_CODE expression;
where
expression – evaluates to an integer. It specifies an alignment
requirement; 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;
1-70VisualDSP++ 4.5 Assembler and Preprocessor Manual
In the absence of the .ALIGN_CODE directive, the default address
alignment is 1.
…
.ALIGN_CODE 4;
JUMP LABEL;;
/* Jump instruction aligned to four word boundary.
If necessary, padding will be done with NOPs */
Assembler
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-71
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-72VisualDSP++ 4.5 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-, or four-byte data objects. 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:
•varName – user-defined symbols that name variables
] = ”fileName“;
bufferName – user-defined symbols that name buffers
•
•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 filename need be given inside double quotes.
If the file name is not found in the current directory, rhe assembler
will look in the directories in the processor include path. You may
VisualDSP++ 4.5 Assembler and Preprocessor Manual1-73
Assembler Syntax Reference
use the
-I switch (see on page 1-142) to add an 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 – set initial values for variables and
buffer elements.
The optional [length] parameter defines the length of the associ-
L
ated 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.
Use a /R32 qualifier (.BYTE4/R32) to support 32-bit initialization
L
for use with 1.31 fracts (see on page 1-53).
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
// and initialize it with three 4-byte fract constants
.BYTE2 Ins, Outs, Remains;
1-74VisualDSP++ 4.5 Assembler and Preprocessor Manual
Assembler
//
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
When declaring or initializing variables with .BYTE, take under consideration 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-123.
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
each char is represented by one byte versus a .VAR directive where 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: