ANALOG DEVICES W3.5 Assembler Manual

W3.5

Assembler and Preprocessor

Manual for ADSP-218x and ADSP-219x DSPs

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

Revision 1.2, October 2003

Part Number:

82-000349-08

Copyright Information

© 2003 Analog Devices, Inc., ALL RIGHTS RESERVED. This docu­ment may not be reproduced in any form without prior, express written
consent from Analog Devices, Inc.

Disclaimer

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

Trademark and Service Mark Notice

The Analog Devices logo, VisualDSP++, and the VisualDSP++ logo are
registered trademarks of Analog Devices, Inc.

All other brand and product names are trademarks or service marks of
their respective owners.

CONTENTS

PREFACE

Purpose ........................................................................................... ix

Intended Audience .......................................................................... ix

Manual Contents ............................................................................. x

What’s New in this Manual .............................................................. x

Technical or Customer Support ....................................................... xi

Supported Processors ....................................................................... xi

Product Information ...................................................................... xii

MyAnalog.com ......................................................................... xii

DSP Product Information ......................................................... xii

Related Documents ................................................................. xiii

Online Technical Documentation ............................................. xiv

From VisualDSP++ .............................................................. xiv

From Windows ..................................................................... xv

From the Web ....................................................................... xv

Printed Manuals ....................................................................... xvi

VisualDSP++ Documentation Set ......................................... xvi

Hardware Manuals ............................................................... xvi

Data Sheets .......................................................................... xvi

VisualDSP++ 3.5 Assembler and Preprocessor Manual iii
for ADSP-218x and ADSP-219x DSPs

CONTENTS

Contacting DSP Publications .................................................. xvii

Notation Conventions .................................................................. xvii

ASSEMBLER

Assembler Guide .......................................................................... 1-2

Assembler Overview ................................................................ 1-3

Writing Assembly Programs ..................................................... 1-3

Program Content ................................................................ 1-6

Program Structure .............................................................. 1-7

Program Interfacing Requirements .................................... 1-12

Using Assembler Support for C Structs .................................. 1-13

Preprocessing a Program ........................................................ 1-14

Using Assembler Feature Macros ........................................... 1-15

Make Dependencies .............................................................. 1-17

Reading a Listing File ............................................................ 1-18

Assembler Syntax Reference ........................................................ 1-19

Assembler Keywords and Symbols ......................................... 1-19

Assembler Expressions ........................................................... 1-27

Assembler Operators ............................................................. 1-28

Numeric Formats .................................................................. 1-30

Fractional Type Support .................................................... 1-31

1.15 Fracts ................................................................... 1-31

1.0r Special Case .......................................................... 1-32

Fractional Arithmetic .................................................... 1-32

Mixed Type Arithmetic ................................................. 1-33

iv VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

CONTENTS

Comment Conventions ......................................................... 1-33

Conditional Assembly Directives ............................................ 1-34

C Struct Support in Assembly Built-in Functions ................... 1-36

OFFSETOF() Built-In ...................................................... 1-36

SIZEOF() Built-In ............................................................ 1-37

-> Struct References ............................................................... 1-38

Assembler Directives .............................................................. 1-40

.ALIGN, Specify an Address Alignment ............................. 1-44

.EXTERN, Refer to a Globally Available Symbol ............... 1-46

.EXTERN STRUCT, Refer to a Struct Defined Elsewhere . 1-47

.FILE, Override the Name of a Source File ........................ 1-49

.GLOBAL, Make a Symbol Globally Available ................... 1-50

.IMPORT, Provide Structure Layout Information .............. 1-51

.LEFTMARGIN, Set the Margin Width of a Listing File .... 1-53

.LIST/.NOLIST, Listing Source Lines and Opcodes ........... 1-54

.LIST_DATA/.NOLIST_DATA, Listing Data Opcodes ..... 1-55

.LIST_DATFILE/.NOLIST_DATFILE, Listing Data Initialization

Files ............................................................................... 1-56

.LIST_DEFTAB, Set the Default Tab Width for Listings ... 1-57

.LIST_LOCTAB, Set the Local Tab Width for Listings ...... 1-58

.LIST_WRAPDATA/.NOLIST_WRAPDATA ................... 1-59

.NEWPAGE, Insert a Page Break in a Listing File .............. 1-60

.PAGELENGTH, Set the Page Length of a Listing File ...... 1-61

.PAGEWIDTH, Set the Page Width of a Listing File ......... 1-62

.PREVIOUS, Revert to the Previously Defined Section ...... 1-63

VisualDSP++ 3.5 Assembler and Preprocessor Manual v
for ADSP-218x and ADSP-219x DSPs

CONTENTS

.REPEAT()/.END_REPEAT, Repeat an Instruction Sequence 1-65

.SECTION, Declare a Memory Section ............................ 1-67

.STRUCT, Create a Struct Variable ................................... 1-69

.TYPE, Change Default Symbol Type ............................... 1-74

.VAR, Declare a Data Variable or Buffer ............................ 1-75

File Initializers .............................................................. 1-78

.VAR and ASCII String Initialization Support ............... 1-78

.VAR/CIRC Qualifier ................................................... 1-79

.VAR/INIT24 Directive ................................................ 1-79

.VCSE Optimization Directives ........................................ 1-80

.WEAK, Support a Weak Symbol Definition and Reference 1-81

Assembler Command-Line Reference .......................................... 1-82

Running the Assembler ......................................................... 1-83

Command-Line Switch Summary and Descriptions ............... 1-85

-Ao filename ..................................................................... 1-87

-c ..................................................................................... 1-87

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

-flags-compiler .................................................................. 1-88

User-Specified Defines Options ..................................... 1-89

Include Options ........................................................... 1-89

-flags-pp -opt1 [,-opt2...] ................................................. 1-90

-g ..................................................................................... 1-90

-h[elp] .............................................................................. 1-91

-i|I directory ..................................................................... 1-91

vi VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

CONTENTS

-l filename ........................................................................ 1-92

-li filename ....................................................................... 1-92

-legacy .............................................................................. 1-92

-M .................................................................................... 1-93

-MM ................................................................................ 1-93

-Mo filename .................................................................... 1-94

-Mt filename ..................................................................... 1-94

-o filename ....................................................................... 1-94

-pp ................................................................................... 1-95

-proc processor .................................................................. 1-95

-si-revision version ............................................................ 1-96

-sp .................................................................................... 1-97

-v[erbose] ......................................................................... 1-97

-version ............................................................................ 1-97

-w ..................................................................................... 1-98

-Wnumber[,number] ......................................................... 1-98

Specifying Assembler Options in VisualDSP++ ....................... 1-99

PREPROCESSOR

Preprocessor Guide ....................................................................... 2-2

Writing Preprocessor Commands ............................................. 2-3

Header Files and #include Command ....................................... 2-4

Writing Macros ....................................................................... 2-6

Using Predefined Macros ......................................................... 2-8

Specifying Preprocessor Options ............................................ 2-10

VisualDSP++ 3.5 Assembler and Preprocessor Manual vii
for ADSP-218x and ADSP-219x DSPs

CONTENTS

Preprocessor Command Reference ............................................... 2-11

Preprocessor Commands and Operators ................................. 2-11

#define ............................................................................. 2-13

Variable Length Argument Definitions .......................... 2-14

#elif ................................................................................. 2-16

#else ................................................................................. 2-17

#endif .............................................................................. 2-18

#error ............................................................................... 2-19

#if .................................................................................... 2-20

#ifdef ............................................................................... 2-21

#ifndef ............................................................................. 2-22

#include ........................................................................... 2-23

#line ................................................................................ 2-25

#pragma ........................................................................... 2-26

#undef ............................................................................. 2-27

#warning .......................................................................... 2-28

# (Argument) ................................................................... 2-29

## (Concatenate) .............................................................. 2-30

? (Generate a Unique Label) .............................................. 2-32

Preprocessor Command-Line Reference ....................................... 2-34

Running the Preprocessor ...................................................... 2-34

Preprocessor Command-Line Switches ................................... 2-35

-cstring ............................................................................. 2-37

-cs! ................................................................................... 2-38

viii VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

CONTENTS

-cs/* .................................................................................. 2-38

-cs// .................................................................................. 2-38

-cs{ ................................................................................... 2-38

-csall ................................................................................. 2-38

-Dmacro[=def] .................................................................. 2-39

-h[elp] .............................................................................. 2-39

-i|I directory ..................................................................... 2-39

Using the -I- Switch ...................................................... 2-40

-M .................................................................................... 2-41

-MM ................................................................................ 2-41

-Mo filename .................................................................... 2-41

-Mt filename ..................................................................... 2-42

-o filename ....................................................................... 2-42

-stringize ........................................................................... 2-42

-tokenize-dot .................................................................... 2-42

-v[erbose] ......................................................................... 2-43

-version ............................................................................ 2-43

-w ..................................................................................... 2-43

-Wnumber ........................................................................ 2-43

-warn ................................................................................ 2-43

ASSEMBLER ENHANCEMENTS AND LEGACY SUPPORT

Legacy Command Switches ........................................................... 3-3

Legacy Directives .......................................................................... 3-4

.CONST, Declare a Constant .................................................. 3-6

VisualDSP++ 3.5 Assembler and Preprocessor Manual ix
for ADSP-218x and ADSP-219x DSPs

CONTENTS

.DMSEG and .PMSEG, Place Data and Code in Memory Sections 3-7

.ENTRY, Make a Program Label Globally Available ................. 3-9

.EXTERNAL, Refer to a Globally Available Symbol ............... 3-10

.INCLUDE, Include Other Source File ................................. 3-11

.INDENT, Indent a Listing File ............................................ 3-13

.INIT, Initialize a Variable or Buffer ...................................... 3-14

.INIT and ASCII String Initialization Support ....................... 3-16

.LOCAL, Create a Unique Version of the Label ...................... 3-17

.MACRO and ENDMACRO, Define a Macro ....................... 3-19

.MODULE and .ENDMOD, Declare a Program Module ...... 3-21

.PORT, Declare a Memory Mapped Port ............................... 3-24

.VAR/ABS, Place a Variable at the Specified Address .............. 3-25

.VAR/CIRC, Declare a Circular Buffer .................................. 3-25

Syntax Conventions .................................................................... 3-28

Modified Operators .............................................................. 3-28

Modified Numeric Conventions ............................................ 3-29

Comment Conventions ......................................................... 3-29

Debugging Capabilities and File Format ...................................... 3-30

ELF File Format .................................................................... 3-30

Debug Information ............................................................... 3-31

UTILITIES

Comment Converter ..................................................................... A-1

INDEX

x VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

PREFACE

Thank you for purchasing Analog Devices development software for digi­tal signal processors (DSPs).

Purpose

The VisualDSP++ 3.5 Assembler and Preprocessor Manual for ADSP-218x
and ADSP-219x DSPs contains information about the assembler program

for ADSP-218x and ADSP-219x DSPs. These are 16-bit, fixed-point pro­cessors from Analog Devices for use in computing, communications, and
consumer applications.

The manual provides information on how to write assembly programs for
ADSP-218x and ADSP-219x DSPs 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 programmers who are familiar
with Analog Devices DSPs. This manual assumes that the audience has a
working knowledge of the appropriate DSP architecture and instruction
set. Programmers who are unfamiliar with Analog Devices DSPs can use
this manual but should supplement it with other texts (such as Hardware
Reference and Instruction Set Reference manuals that describe your target
architecture).

VisualDSP++ 3.5 Assembler and Preprocessor Manual ix
for ADSP-218x and ADSP-219x DSPs

Manual Contents

Manual Contents

The manual consists of:

• Chapter 1, “Assembler”

Provides an overview of the process of writing and building assem­bly 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.

• Chapter 3, “Assembler Enhancements and Legacy Support”

Compares Release 6.1 assembler and preprocessor features to new
features added in latest VisualDSP++ releases.

•Appendix A, “Utilities”

Describes the comment conversion utility that runs from a com­mand line only. This utility provides support for converting legacy
code developed under Release 6.1.

What’s New in this Manual

This edition of the manual supports ADSP-218x and ADSP-219x
processors.

Refer to VisualDSP++ 3.5 Product Bulletin for 16-Bit Processors for infor­mation on all new and updated features and other release information.

x VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

Technical or Customer Support

You can reach DSP Tools Support in the following ways:

• Visit the DSP Development Tools website at

www.analog.com/technology/dsp/developmentTools/index.html

• Email questions to

[e-mail]

• Phone questions to 1-800-ANALOGD

• Contact your ADI local sales office or authorized distributor

• Send questions by mail to:

Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
USA

Preface

Supported Processors

The names “ADSP-218x” and “ADSP-219x” refer to a family of Analog
Devices 16-bit, fixed-point processors. VisualDSP++ currently supports
the following ADSP-218x and ADSP-219x processors:

• ADSP-2191, ADSP-2192-12, ADSP-2195, ADSP-2196,
ADSP-21990, ADSP-21991, and ADSP-21992 DSPs

• ADSP-2181, ADSP-2183, ADSP-2184/84L/84N,
ADSP-2185/85L/85M/85N, ADSP-2186/86L/86M/86N,
ADSP-2187L/84L/87N, ADSP-2188L/88N, and
ADSP-2189M/89N DSPs

VisualDSP++ 3.5 Assembler and Preprocessor Manual xi
for ADSP-218x and ADSP-219x DSPs

Product Information

Product Information

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

Analog Devices is online at www.analog.com. Our website provides infor­mation about a broad range of products—analog integrated circuits,
amplifiers, converters, and digital signal processors.

MyAnalog.com

MyAnalog.com is a free feature of the Analog Devices website that allows

customization of a webpage to display only the latest information on
products you are interested in. You can also choose to receive weekly email
notification containing updates to the webpages that meet your interests.

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

code examples, and more.

Registration:

Visit www.myanalog.com to sign up. Click Register to use MyAnalog.com.
Registration takes about five minutes and serves as means for you to select
the information you want to receive.

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

DSP Product Information

For information on digital signal processors, visit our website at

www.analog.com/dsp, which provides access to technical publications,

datasheets, application notes, product overviews, and product
announcements.

xii VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

Preface

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

• Email questions or requests for information to

[e-mail]

• Fax questions or requests for information to

1-781-461-3010 (North America)
089/76 903-557 (Europe)

• Access the Digital Signal Processing Division’s FTP website at

ftp ftp.analog.com or ftp 137.71.23.21
ftp://ftp.analog.com

Related Documents

For information on product related development software, see the follow­ing publications:

VisualDSP++ 3.5 Getting Started Guide for 16-Bit Processors

VisualDSP++ 3.5 User’s Guide for 16-Bit Processors

VisualDSP++ 3.5 C/C++ Compiler and Library Manual for ADSP-218x DSPs

VisualDSP++ 3.5 C/C++ Compiler and Library Manual for ADSP-219x DSPs

VisualDSP++ 3.5 Linker and Utilities Manual for 16-Bit DSPs

VisualDSP++ 3.5 Loader Manual for 16-Bit Processors

VisualDSP++ 3.5 Product Bulletin for 16-Bit Processors

VisualDSP++ Kernel (VDK) User’s Guide

VisualDSP++ Component Software Engineering User’s Guide

Quick Installation Reference Card

VisualDSP++ 3.5 Assembler and Preprocessor Manual xiii
for ADSP-218x and ADSP-219x DSPs

Product Information

Online Technical Documentation

Online documentation comprises VisualDSP++ Help system and tools
manuals, Dinkum Abridged C++ library and FlexLM network license
manager software documentation. You can easily search across the entire
VisualDSP++ documentation set for any topic of interest. For easy print­ing, supplementary

A description of each documentation file type is as follows.

File Description

.CHM Help system files and VisualDSP++ tools manuals.

.PDF files for the tools manuals are also provided.

.HTM or
.HTML

.PDF VisualDSP++ tools manuals in Portable Documentation Format, one .PDF file for

Dinkum Abridged C++ library and FlexLM network license manager software doc­umentation. Viewing and printing the
net Explorer 4.0 (or higher).

each manual. Viewing and printing the
Adobe Acrobat Reader (4.0 or higher).

.HTML files require a browser, such as Inter-

.PDF files require a PDF reader, such as

If documentation is not installed on your system as part of the software
installation, you can add it from the VisualDSP++ CD-ROM at any time.

Access the online documentation from the VisualDSP++ environment,
Windows Explorer, or Analog Devices website.

From VisualDSP++

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

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

xiv VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

Preface

From Windows

In addition to any shortcuts you may have constructed, there are many
ways to open VisualDSP++ online Help or the supplementary documenta­tion from Windows.

Help system files (

.CHM files) are located in the Help folder, and .PDF files

are located in the Docs folder of your VisualDSP++ installation. The Docs
folder also contains the FlexLM network license manager software
documentation.

Using Windows Explorer

• Double-click any file that is part of the VisualDSP++ documenta­tion set.

• Double-click the vdsp-help.chm file, which is the master Help sys­tem, to access all the other .CHM files.

Using the Windows Start Button

• Access the VisualDSP++ online Help by clicking the Start button
and choosing Programs, Analog Devices, VisualDSP++, and
VisualDSP++ Documentation.

• Access the .PDF files by clicking the Start button and choosing

Programs, Analog Devices, VisualDSP++, Documentation for
Printing, and the name of the book.

From the Web

To download the tools manuals, point your browser at

http://www.analog.com/technology/dsp/developmentTools/gen_purpose.html

Select a DSP family and book title. Download archive (.ZIP) files, one for
each manual. Use any archive management software, such as WinZip, to
decompress downloaded files.

VisualDSP++ 3.5 Assembler and Preprocessor Manual xv
for ADSP-218x and ADSP-219x DSPs

Product Information

Printed Manuals

For general questions regarding literature ordering, call the Literature
Center at 1-800-ANALOGD (1-800-262-5643) and follow the prompts.

VisualDSP++ Documentation Set

VisualDSP++ manuals may be purchased through Analog Devices Cus­tomer Service at 1-781-329-4700; ask for a Customer Service
representative. The manuals can be purchased only as a kit. For additional
information, call 1-603-883-2430.

If you do not have an account with Analog Devices, you will be referred to
Analog Devices distributors. To get information on our distributors, log
onto

http://www.analog.com/salesdir/continent.asp.

Hardware Manuals

Hardware reference and instruction set reference manuals can be ordered
through the Literature Center or downloaded from the Analog Devices
website. The phone number is 1-800-ANALOGD (1-800-262-5643).
The manuals can be ordered by a title or by product number located on
the back cover of each manual.

Data Sheets

All data sheets can be downloaded from the Analog Devices website. As a
general rule, any data sheet with a letter suffix (L, M, N) can be obtained
from the Literature Center at 1-800-ANALOGD (1-800-262-5643) or
downloaded from the website. data sheets without the suffix can be down­loaded from the website only—no hard copies are available. You can ask
for the data sheet by a part name or by product number.

xvi VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

Preface

If you want to have a data sheet faxed to you, the fax number for that
service is 1-800-446-6212. Follow the prompts and a list of data sheet
code numbers will be faxed to you. Call the Literature Center first to find
out if requested data sheets are available.

Contacting DSP Publications

Please send your comments and recommendation on how to improve our
manuals and online Help. You can contact us @

[e-mail]

Notation Conventions

The following table identifies and describes text conventions used in this
manual.

.



Example Description

Close command
(File menu)

{this | that} Alternative required items in syntax descriptions appear within curly

[this | that] Optional items in syntax descriptions appear within brackets and sepa-

[this,…] Optional item lists in syntax descriptions appear within brackets

.SECTION Commands, directives, keywords, and feature names are in text with

filename Non-keyword placeholders appear in text with italic style format.

appear throughout this document.

Tex t in bold style indicates the location of an item within the
VisualDSP++ environment’s menu system. For example, the Close
command appears on the File menu.

brackets and separated by vertical bars; read the example as

that.

rated by vertical bars; read the example as an optional

delimited by commas and terminated with an ellipsis; read the example
as an optional comma-separated list of

letter gothic font.

this or

this or that.

this.

Additional conventions, which apply only to specific chapters, may

VisualDSP++ 3.5 Assembler and Preprocessor Manual xvii
for ADSP-218x and ADSP-219x DSPs

Notation Conventions

Example Description

A note, providing information of special interest or identifying a
related topic. In the online version of this book, the word Note appears
instead of this symbol.

A caution, providing information about critical design or program­ming issues that influence operation of a product. In the online version
of this book, the word Caution appears instead of this symbol.

xviii VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

1 ASSEMBLER

This chapter provides information on how to use the assembler for devel­oping and assembling programs with ADSP-218x and ADSP-219x DSPs.

The chapter contains:

• “Assembler Guide” on page 1-2
Describes the process of developing new programs in the
ADSP-218x and ADSP-219x DSP assembly language.

• “Assembler Syntax Reference” on page 1-19
Provides the assembler rules and conventions of syntax which is
used to define symbols (identifiers), expressions, and to describe
different numeric and comment formats.

• “Assembler Command-Line Reference” on page 1-82
Provides reference information on the assembler’s switches and
conventions.

VisualDSP++ 3.5 Assembler and Preprocessor Manual 1-1
for ADSP-218x and ADSP-219x DSPs

Assembler Guide

Assembler Guide

The easm218x.exe and easm219x.exe assemblers run from the
VisualDSP++ Integrated Debugging and Development Environment
(IDDE) or from an operating system command line. Each assembler pro­cesses assembly source, data, header files, and produces an object file.
Assembler operations depend on two types of controls: assembler direc­tives and assembler switches.

This section describes the process of developing new programs in the
ADSP-218x and ADSP-219x DSPs assembly language. It provides infor­mation on how 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-13

• “Preprocessing a Program” on page 1-14

• “Reading a Listing File” on page 1-18

• “Make Dependencies” on page 1-17

• “Specifying Assembler Options in VisualDSP++” on page 1-99

For information about the DSP architecture, including the DSP instruc­tion set used when writing the assembly programs, see the Hardware
Reference Manual and Instruction Set Manual for an appropriate DSP.

1-2 VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

Assembler

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.DOJ extension.

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++ or in the com­mand 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 Command-Line Refer-

ence” on page 1-82.

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-99).

.H) files to generate object files in Executable and

Writing Assembly Programs

Assembler directives are coded in your assembly source file. The directives
allow you to define variables, set up some hardware features, and identify
program’s sections for placement within DSP 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
names to identify them as assembly source files.

VisualDSP++ 3.5 Assembler and Preprocessor Manual 1-3
for ADSP-218x and ADSP-219x DSPs

.ASM extension to source file

Assembler Guide

Assemble your source files from the VisualDSP++ environment or using
any mechanism, such as a batch file or makefile, that will support invok­ing the assembler driver
command-line command. By default, the assembler processes an input file
to produce a binary object file (.DOJ) and an optional listing file (.LST).

Figure 1-1 shows a graphical overview of the assembly process. The figure

shows the preprocessor processing the assembly source (.ASM) and initial­ization data (.DAT) files.

Object files produced by the ADSP-218x and ADSP-219x DSP assemblers
may be used as input to the linker and archiver. You can archive the out­put 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++ 3.5
Linker and Utilities Manual for ADSP-218x and ADSP-219x DSPs.

easm218x.exe and easm219x.exe with a specified

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. It tells which imports were used within
the program, followed by a more detailed section (see .

on page 1-51). 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.lst option (on page 1-92) to get the
information.



1-4 VisualDSP++ 3.5 Assembler and Preprocessor Manual

VisualDSP++ 3.5 assembler can process your source programs
developed previous VDSP releases including Release 6.1. The
assembly of these programs requires an additional processing steps
described in Chapter 3, “Assembler Enhancements and Legacy

Support” .

for ADSP-218x and ADSP-219x DSPs

IMPORT directive

Assembler

Data initialization file

(.DAT)

Object file

(.DOJ)

Assembly source file

(.ASM, .DSP)

Preprocessor

Intermediate

preprocessed file (.IS)

Assembler

Listing file

Header file

(.H)

(.LST)

Figure 1-1. Assembler Input and Output Files

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

.IS), is the assembler’s primary input.

file (

VisualDSP++ 3.5 Assembler and Preprocessor Manual 1-5
for ADSP-218x and ADSP-219x DSPs

Assembler Guide

Program Content

Assembly source file statements include assembly instructions, assembler
directives, and preprocessor commands.

Assembly Instructions

Instructions adhere to the DSP’s instruction set syntax documented in the
DSP’s Instruction Set manual. Terminate each instruction with a semico­lon (

;). Figure 1-2 on page 1-9 shows an example assembly source file.

To mark the location of an instruction, place an address label at the begin­ning of an instruction line or on the preceding line. End the label with a
colon (:) before beginning the instruction. Your program then refer to this
memory location using the label instead of an absolute 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,

outer: AR = AR-1;
Outer: I1 = AR;
jump outer; //jumps back 2 instructions

Assembler Directives

Directives begin with a period (.) and end with a semicolon (;). The
assembler does not differentiate between directives in lowercase or
uppercase.



For example,

.SECTION/data data1;
.VAR sqrt_coeff[2] = 0x5D1D, 0xA9ED;

For a complete description of the easm218x.exe and easm219x.exe assem­bler’s directive set, see “Assembler Directives” on page 1-40.

1-6 VisualDSP++ 3.5 Assembler and Preprocessor Manual

This manual prints directives in uppercase to distinguish them
from other assembly statements.

for ADSP-218x and ADSP-219x DSPs

Assembler

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 Reference” on page 2-11.

Program Structure

An assembly source file defines code (instructions) and data, and organizes
the instructions and data to allow use of the Linker Description File
(LDF) to describe how code and data are mapped into the memory on
your target DSP. The way you structure your code and data into memory
should follow the memory architecture of the target DSP.

Use the
source files. The

.SECTION directive to organize the code and data in assembly

.SECTION directive defines a grouping of instructions and

data that will occupy contiguous memory addresses in the DSP. The name
given in a section directive corresponds to an input section name in the
Linker Description File.

Suggested input section names that you could use in your assembly source
appear in Table 1-1 on page 1-8. Using these predefined names in your
sources makes it easier to take advantage of the default .

LDF file included

in your DSP system.

VisualDSP++ 3.5 Assembler and Preprocessor Manual 1-7
for ADSP-218x and ADSP-219x DSPs

Assembler Guide

For more information on the .

LDF files, see the VisualDSP++ 3.5 Linker

and Utilities Manual for 16-Bit Processors.

Table 1-1. Suggested Input Section Names

.SECTION Name Description

data1 A section that holds data.

program A section that holds code.

You can use sections in a program to group elements to meet hardware
constraints.

To group the code that reside in off-chip memory, declare a section for
that code and place that section in the selected memory with the linker.

Figure 1-2 on page 1-9 shows how a program divides into sections that

match the memory segmentation of a DSP system.

The example assembly program defines four sections; each section begins
with a .SECTION directive and ends with the occurrence of the next

.SECTION directive or end-of-file. The source program contains two data

and two program sections:

• Data Sections—data1 and constdata. Variables and buffers are
declared and can be initialized.

• Program Sections—

seg_rth and program. Data, instructions, and

statements for conditional assembly are coded.

Looking at Figure 1-2, notice that an assembly source may contain pre-
processor 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.

1-8 VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs

Assembler

Data Section

Data Section

Data Section

Code S ecti on

Assembler
Directive

Co de S ecti on

Assembler
Label and
Instructions

Co de S ecti on

Assembler
Label

Preprocessor
Commands for

Conditional

Assembly

Assembly
Instructions

.SECTION/DATAint_dm1;
.VAR buffer1[0x100] = "text2.txt";

.SECTION/DATA dummy;
.VAR buffer2[0x100];

.SECTION/DATA int_dm3;
.VAR buffer3;

.SECTION/PM seg_1;
.VAR/INIT24 pm_buffer1 = 0x123456;

.SECTION/CODE seg_rth;
JUMP start; RTI;RTI;RTI; // begin execution

RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;
RTI;RTI;RTI;RTI;

.SECTION/CODE kernel;
start:

#ifndef AR_SET_TO_2
AR = 0x0001;
#endif

#ifdef AR_SET_TO_2
AR = 0x0002;
#endif
I1 = buffer1;
L1=0;
M2=1;

CNTR = 0x100;
DO this_loop UNTIL CE;
this_loop: DM(I1,M2) = AR;

Figure 1-2. Assembly Source File Structure

Listing 1-1 shows a sample user-defined Linker Description File. Looking

at the LDF’s SECTIONS{} command, notice that the INPUT_SECTION com­mands map to sections
LDF’s

SECTIONS{} command defines the .SECTION placements in the sys-

sec_code, data1, sec_itab, , and seg_rth. The

tem’s physical memory as defined by the linker’s Memory{} command.

VisualDSP++ 3.5 Assembler and Preprocessor Manual 1-9
for ADSP-218x and ADSP-219x DSPs

Assembler Guide

Listing 1-1. Example Linker Description File

ARCHITECTURE(ADSP-219x)
SEARCH_DIR($ADI_DSP\ADSP-219x\lib)

LIBS libc.dlb, libdsp.dlb
$LIBRARIES = LIBS, librt.dlb
$OBJECTS = $COMMAND_LINE_OBJECTS;
MEMORY
{

seg_reset { TYPE(PM RAM) START(0x000000) END(0x000001F) WIDTH(24) }
seg_itab { TYPE(PM RAM) START(0x000020) END(0x0002ff) WIDTH(24) }
seg_code { TYPE(PM RAM) START(0x000300) END(0x007fff) WIDTH(24) }
seg_data1 { TYPE(DM RAM) START(0x08000) END(0x00ffff) WIDTH(16) }

}
PROCESSOR p0 /* The processor in the system */
{

LINK_AGAINST( $COMMAND_LINE_LINK_AGAINST)
OUTPUT($COMMAND_LINE_OUTPUT_FILE)

SECTIONS
{ /* List of sections for processor P0 */

sec_reset
{

IVreset_addr = .;
INPUT_SECTIONS( $OBJECTS(IVreset))

} > seg_reset

sec_itab
{

intvectoffset = 32;
IVpwrdwn_addr = .;
INPUT_SECTIONS( $OBJECTS(IVpwrdwn))
IVsinglestep_addr = IVpwrdwn_addr + intvectoffset;
. = IVsinglestep_addr;
INPUT_SECTIONS( $OBJECTS(IVsinglestep))
IVstackint_addr = IVsinglestep_addr + intvectoffset;
. = IVstackint_addr;
INPUT_SECTIONS( $OBJECTS(IVstackint))
IVint4_addr = IVstackint_addr + intvectoffset;
. = IVint4_addr;
INPUT_SECTIONS( $OBJECTS(IVint4))
IVint5_addr = IVint4_addr + intvectoffset;
. = IVint5_addr;
INPUT_SECTIONS( $OBJECTS(IVint5))
IVint6_addr = IVint5_addr + intvectoffset;
. = IVint6_addr;
INPUT_SECTIONS( $OBJECTS(IVint6))

1-10 VisualDSP++ 3.5 Assembler and Preprocessor Manual

for ADSP-218x and ADSP-219x DSPs