ANALOG DEVICES W5.0 Assembler Manual

a

W5.0

Assembler and Preprocessor Manual

Revision 3.2, March 2009

Part Number:

82-000420-04

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

Copyright Information

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

Printed in the USA.

Disclaimer

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

Trademark and Service Mark Notice

The Analog Devices logo, VisualDSP++, Blackfin, SHARC, and Tiger­SHARC are registered trademarks of Analog Devices, Inc.

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

CONTENTS

PREFACE

Purpose ......................................................................................... xiii

Intended Audience ........................................................................ xiii

Manual Contents ........................................................................... xiv

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

Technical or Customer Support ....................................................... xv

Supported Processors ...................................................................... xvi

Product Information ...................................................................... xvi

Analog Devices Web Site .......................................................... xvi

VisualDSP++ Online Documentation ...................................... xvii

Technical Library CD ............................................................. xviii

Notation Conventions .................................................................. xviii

ASSEMBLER

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

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

Writing Assembly Programs ..................................................... 1-4

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

Assembly Instructions ..................................................... 1-6

VisualDSP++ 5.0 Assembler and Preprocessor Manual iii

CONTENTS

Assembler Directives ....................................................... 1-6

Preprocessor Commands ................................................. 1-7

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

Code File Structure for SHARC Processors .................... 1-10

LDF for SHARC Processors .......................................... 1-10

Code File Structure for TigerSHARC Processors ............ 1-13

LDF for TigerSHARC Processors .................................. 1-13

Code File Structure for Blackfin Processors .................... 1-17

LDF for Blackfin Processors .......................................... 1-18

Program Interfacing Requirements .................................... 1-20

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

Preprocessing a Program ........................................................ 1-24

Using Assembler Feature Macros ........................................... 1-25

-D__VISUALDSPVERSION__ Predefined Macro ............ 1-31

Generating Make Dependencies ............................................ 1-33

Reading a Listing File ............................................................ 1-34

Enabling Statistical Profiling for Assembly Functions ............. 1-35

Assembler Syntax Reference ........................................................ 1-37

Assembler Keywords and Symbols ......................................... 1-38

Assembler Expressions ........................................................... 1-50

Assembler Operators ............................................................. 1-51

Numeric Formats .................................................................. 1-56

Representation of Constants in Blackfin ............................ 1-56

Fractional Type Support .................................................... 1-57

iv VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

1.31 Fracts .................................................................... 1-58

1.0r Special Case ........................................................... 1-59

Fractional Arithmetic .................................................... 1-59

Mixed Type Arithmetic ................................................. 1-59

Comment Conventions ......................................................... 1-60

Conditional Assembly Directives ............................................ 1-60

C Struct Support in Assembly Built-In Functions ................... 1-63

OFFSETOF Built-In Function .......................................... 1-63

SIZEOF Built-In Function ................................................ 1-63

Struct References ................................................................... 1-64

Assembler Directives .............................................................. 1-67

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

.ALIGN_CODE, Specify an Address Alignment ................ 1-74

.ASCII .............................................................................. 1-76

.BYTE, Declare a Byte Data Variable or Buffer .................. 1-77

ASCII String Initialization Support ............................... 1-79

.COMPRESS, Start Compression ...................................... 1-81

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

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

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

.FILE_ATTR, Create an Attribute in the Object File ......... 1-86

.FORCECOMPRESS, Compress the Next Instruction ....... 1-87

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

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual v

CONTENTS

.INC/BINARY, Include Contents of a File ........................ 1-92

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

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

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

.LIST_DATFILE/.NOLIST_DATFILE, Listing Data

Initialization Files ........................................................ 1-96

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

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

.LIST_WRAPDATA/.NOLIST_WRAPDATA ................ 1-100

.LONG, Defines and initializes 4-byte data objects .......... 1-101

.MESSAGE, Alter the Severity of an Assembler Message .. 1-102

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

.NOCOMPRESS, Terminate Compression ..................... 1-107

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

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

.PORT, Legacy Directive ................................................. 1-111

.PRECISION, Select Floating-Point Precision ................. 1-112

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

.PRIORITY, Allow Prioritized Symbol Mapping in Linker 1-115

Linker Operation ........................................................ 1-116

.REFERENCE, Provide Better Info in an X-REF File ...... 1-118

.RETAIN_NAME, Stop Linker from Eliminating Symbol 1-118

.ROUND_, Select Floating-Point Rounding .................... 1-119

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

Common .SECTION Attributes ................................. 1-122

vi VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

DOUBLE* Qualifiers .................................................. 1-123

TigerSHARC-Specific Qualifiers .................................. 1-124

SHARC-Specific Qualifiers .......................................... 1-125

Initialization Section Qualifiers ................................... 1-126

.SEGMENT and .ENDSEG, Legacy Directives ............... 1-128

.SEPARATE_MEM_SEGMENTS ................................... 1-128

.SET, Set a Symbolic Alias ............................................... 1-129

.SHORT, Defines and initializes 2-byte data objects ......... 1-129

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

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

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

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

.WEAK, Support Weak Symbol Definition and Reference 1-140

Assembler Command-Line Reference ......................................... 1-141

Running the Assembler ........................................................ 1-142

Assembler Command-Line Switch Descriptions .................... 1-144

-align-branch-lines .......................................................... 1-149

-anomaly-detect [id1[,id2...]] .......................................... 1-149

-anomaly-warn {id1[,id2]|all|none} .................................. 1-149

-anomaly-workaround [id] .............................................. 1-150

-char-size-8 ..................................................................... 1-151

-char-size-32 ................................................................... 1-151

-char-size-any .................................................................. 1-151

-default-branch-np .......................................................... 1-151

VisualDSP++ 5.0 Assembler and Preprocessor Manual vii

CONTENTS

-default-branch-p ........................................................... 1-152

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

-double-size-32 ............................................................... 1-152

-double-size-64 ............................................................... 1-153

-double-size-any ............................................................. 1-153

-expand-symbolic-links ................................................... 1-153

-expand-windows-shortcuts ............................................. 1-154

-file-attr attr[=val] .......................................................... 1-154

-flags-compiler ................................................................ 1-154

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

User-Specified Defines Options ................................... 1-155

Include Options ......................................................... 1-155

-g ................................................................................... 1-156

WARNING ea1121: Missing End Labels ..................... 1-157

-h[elp] ............................................................................ 1-158

-i .................................................................................... 1-158

-l filename ...................................................................... 1-159

-li filename ..................................................................... 1-159

-M ................................................................................. 1-160

-MM .............................................................................. 1-160

-Mo filename .................................................................. 1-161

-Mt filename .................................................................. 1-161

-micaswarn ..................................................................... 1-161

-no-source-dependency ................................................... 1-161

viii VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

-no-anomaly-detect [id1[,id2...]] ..................................... 1-162

-no-anomaly-workaround [id1[,id2...]] ............................ 1-162

-no-expand-symbolic-links .............................................. 1-162

-no-expand-windows-shortcuts ........................................ 1-163

-no-temp-data-file ........................................................... 1-163

-normal-word-code or -nwc ............................................. 1-163

-o filename ..................................................................... 1-164

-pp ................................................................................. 1-164

-proc processor ................................................................ 1-164

-save-temps ..................................................................... 1-165

-short-word-code or -swc ................................................. 1-165

-si-revision version .......................................................... 1-165

-sp .................................................................................. 1-166

-stallcheck ....................................................................... 1-166

-swc-exclude name1[,name2] ........................................... 1-167

-v[erbose] ....................................................................... 1-167

-version .......................................................................... 1-167

-w ................................................................................... 1-167

-Werror number[,number] .............................................. 1-168

-Winfo number[,number] ............................................... 1-168

-Wno-info ...................................................................... 1-168

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

-Wsuppress number[,number] ......................................... 1-169

-Wwarn number[,number] .............................................. 1-169

VisualDSP++ 5.0 Assembler and Preprocessor Manual ix

CONTENTS

-Wwarn-error ................................................................. 1-169

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

PREPROCESSOR

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

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

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

System Header Files ............................................................ 2-5

User Header Files ............................................................... 2-5

Sequence of Tokens ............................................................ 2-6

Include Path Search ............................................................ 2-7

Writing Macros ....................................................................... 2-7

Macro Definition and Usage Guidelines .............................. 2-9

Examples of Multi-Line Code Macros with Arguments ...... 2-12

Debugging Macros ........................................................... 2-13

Using Predefined Preprocessor Macros ................................... 2-15

-D__VISUALDSPVERSION____ Predefined Macro (Preprocessor)
2-21

Specifying Preprocessor Options ............................................ 2-21

Preprocessor Command Reference ............................................... 2-22

Preprocessor Commands and Operators ................................. 2-22

#define ............................................................................. 2-24

Variable-Length Argument Definitions .......................... 2-25

#elif ................................................................................. 2-27

#else ................................................................................. 2-28

x VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

#endif ............................................................................... 2-29

#error ............................................................................... 2-30

#if .................................................................................... 2-31

#ifdef ................................................................................ 2-32

#ifndef .............................................................................. 2-33

#include ........................................................................... 2-34

#line ................................................................................. 2-36

#pragma ........................................................................... 2-37

#undef .............................................................................. 2-38

#warning .......................................................................... 2-39

# (Argument) .................................................................... 2-40

## (Concatenate) .............................................................. 2-42

? (Generate a unique label) ................................................ 2-43

Preprocessor Command-Line Reference ....................................... 2-45

Running the Preprocessor ...................................................... 2-45

Preprocessor Command-Line Switches ................................... 2-46

-cpredef ............................................................................ 2-48

-cs! ................................................................................... 2-49

-cs/* .................................................................................. 2-49

-cs// .................................................................................. 2-50

-cs{ ................................................................................... 2-50

-csall ................................................................................. 2-50

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

-h[elp] .............................................................................. 2-50

VisualDSP++ 5.0 Assembler and Preprocessor Manual xi

CONTENTS

-i ...................................................................................... 2-51

-i ...................................................................................... 2-51

-I- .................................................................................... 2-52

-M ................................................................................... 2-53

-MM ................................................................................ 2-53

-Mo filename .................................................................... 2-53

-Mt filename .................................................................... 2-54

-o filename ....................................................................... 2-54

-stringize .......................................................................... 2-54

-tokenize-dot .................................................................... 2-54

-Uname ............................................................................ 2-55

-v[erbose] ......................................................................... 2-55

-version ............................................................................ 2-55

-w .................................................................................... 2-55

-Wnumber ....................................................................... 2-56

-warn ............................................................................... 2-56

INDEX

xii VisualDSP++ 5.0 Assembler and Preprocessor Manual

PREFACE

Thank you for purchasing Analog Devices, Inc. development software for
digital signal processing (DSP) applications.

Purpose

The VisualDSP++ 5.0 Assembler and Preprocessor Manual contains infor-
mation about the assembler and preprocessor utilities for the following
Analog Devices, Inc. processor families—Blackfin® (ADSP-BFxxx),
SHARC® (ADSP-21xxx), and TigerSHARC® (ADSP-TSxxx) processors.

The manual describes how to write assembly programs for these processors
and provides reference information about related development software.
It also provides information on new and legacy syntax for assembler and
preprocessor directives and comments, as well as command-line switches.

Intended Audience

The primary audience for this manual is a programmer who is familiar
with Analog Devices processors. This manual assumes that the audience
has a working knowledge of the appropriate processor architecture and
instruction set. Programmers who are unfamiliar with Analog Devices
processors can use this manual, but should supplement it with other texts
(such as the appropriate hardware reference and programming reference
manuals) that describe your target architecture.

VisualDSP++ 5.0 Assembler and Preprocessor Manual xiii

Manual Contents

Manual Contents

The manual consists of:

• Chapter 1, “Assembler”
Provides an overview of the process of writing and building
assembly programs. It also provides information about assembler
switches, expressions, keywords, and directives.

• Chapter 2, “Preprocessor”
Provides procedures for using preprocessor commands within
assembly source files as well as the preprocessor’s command-line
interface options and command sets.

What’s New in this Manual

This revision of the VisualDSP++ 5.0 Assembler and Preprocessor Manual
documents assembler and preprocessor functionality that is new to Visu­alDSP++® 5.0 and updates (up to update 6), including support for new
ADSP-2146x SHARC processors.

In addition, modifications and corrections based on errata reports against
the previous revision of the manual have been made.

xiv VisualDSP++ 5.0 Assembler and Preprocessor Manual

Technical or Customer Support

You can reach Analog Devices, Inc. Customer Support in the following
ways:

• Visit the Embedded Processing and DSP products Web site at

http://www.analog.com/processors/technical_support

• E-mail tools questions to

[e-mail]

• E-mail processor questions to

[e-mail] (World wide support)
[e-mail] (Europe support)
[e-mail] (China support)

• Phone questions to 1-800-ANALOGD

Preface

• Contact your Analog Devices, Inc. local sales office or authorized
distributor

• Send questions by mail to:

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual xv

Supported Processors

Supported Processors

The assembler and preprocessor of VisualDSP++ 5.0 supports the follow­ing Analog Devices, Inc. processors.

• Blackfin (ADSP-BFxxx)

• SHARC (ADSP-21xxx)

• TigerSHARC (ADSP-TSxxx)

The majority of the information in this manual applies to all processors.
For a complete list of processors supported by VisualDSP++ 5.0, refer to
the online Help.

Product Information

Product information can be obtained from the Analog Devices Web site,
VisualDSP++ online Help system, and a technical library CD.

Analog Devices Web Site

The Analog Devices Web site, www.analog.com, provides information
about a broad range of products—analog integrated circuits, amplifiers,
converters, and digital signal processors.

To access a complete technical library for each processor family, go to

http://www.analog.com/processors/technical_library. The manuals

selection opens a list of current manuals related to the product as well as a
link to the previous revisions of the manuals. When locating your manual
title, note a possible errata check mark next to the title that leads to the
current correction report against the manual.

xvi VisualDSP++ 5.0 Assembler and Preprocessor Manual

Preface

Also note,

MyAnalog.com is a free feature of the Analog Devices Web site

that allows customization of a Web page to display only the latest infor­mation about products you are interested in. You can choose to receive
weekly e-mail notifications containing updates to the Web pages that meet
your interests, including documentation errata against all manuals. MyAn-

alog.com

provides access to books, application notes, data sheets, code

examples, and more.

Visit MyAnalog.com to sign up. If you are a registered user, just log on.
Your user name is your e-mail address.

VisualDSP++ Online Documentation

Online documentation comprises the VisualDSP++ Help system, software
tools manuals, hardware tools manuals, processor manuals, Dinkum
Abridged C++ library, and FLEXnet License Tools documentation. You
can search easily across the entire VisualDSP++ documentation set for any
topic of interest.

For easy printing, supplementary Portable Documentation Format (.pdf)
files for all manuals are provided on the VisualDSP++ installation CD.

Each documentation file type is described as follows.

File Description

.chm Help system files and manuals in Microsoft help format

.htm or
.html

.pdf VisualDSP++ and processor manuals in PDF format. Viewing and printing the

Dinkum Abridged C++ library and FLEXnet license tools software
documentation. Viewing and printing the .html files requires a browser, such as
Internet Explorer 6.0 (or higher).

.pdf files requires a PDF reader, such as Adobe Acrobat Reader (4.0 or higher).

VisualDSP++ 5.0 Assembler and Preprocessor Manual xvii

Notation Conventions

Technical Library CD

The technical library CD contains seminar materials, product highlights,
a selection guide, and documentation files of processor manuals, Visu­alDSP++ software manuals, and hardware tools manuals for the following
processor families: Blackfin, SHARC, TigerSHARC, ADSP-218x, and
ADSP-219x.

To order the technical library CD, go to http://www.analog.com/proces-

sors/technical_library

processor, click the request CD check mark, and fill out the order form.

Data sheets, which can be downloaded from the Analog Devices Web site,
change rapidly, and therefore are not included on the technical library
CD. Technical manuals change periodically. Check the Web site for the
latest manual revisions and associated documentation errata.

, navigate to the manuals page for your

Notation Conventions

Text conventions used in this manual are identified and described as
follows.

L

Example Description

Close command
(File menu)

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

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

xviii VisualDSP++ 5.0 Assembler and Preprocessor Manual

Additional conventions, which apply only to specific chapters, may
appear throughout this document.

Titles in in bold style reference sections indicate the location of an item
within the VisualDSP++ environment’s menu system (for example, the
Close command appears on the File menu).

brackets and separated by vertical bars; read the example as

that. One or the other is required.

rated by vertical bars; read the example as an optional

this or

this or that.

Preface

L

a

[

Example Description

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

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

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

letter gothic font.

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

Note: For correct operation, ...
A Note provides supplementary information on a related topic. In the
online version of this book, the word Note appears instead of this
symbol.

Caution: Incorrect device operation may result if ...
Caution: Device damage may result if ...

A Caution identifies conditions or inappropriate usage of the product
that could lead to undesirable results or product damage. In the online
version of this book, the word Caution appears instead of this symbol.

Warn in g: Injury to device users may result if ...
A Warning identifies conditions or inappropriate usage of the product
that could lead to conditions that are potentially hazardous for devices
users. In the online version of this book, the word Wa rning appears
instead of this symbol.

this.

VisualDSP++ 5.0 Assembler and Preprocessor Manual xix

Notation Conventions

xx VisualDSP++ 5.0 Assembler and Preprocessor Manual

1 ASSEMBLER

This chapter provides information on how to use the assembler to develop
and assemble programs for SHARC (ADSP-21xxx), TigerSHARC
(ADSP-TSxxx), and Blackfin (ADSP-BFxxx) processors.

The chapter contains the following sections:

• “Assembler Guide” on page 1-2
Describes how to develop new programs using the processor’s
assembly language

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

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

L

VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-1

The code examples in this manual have been compiled using
VisualDSP++ 5.0 The examples compiled with other versions of
VisualDSP++ may result in build errors or different output
although the highlighted algorithms stand and should continue to
stand in future releases of VisualDSP++.

Assembler Guide

Assembler Guide

In VisualDSP++ 5.0, you can run the assembler drivers for each processor
family from the VisualDSP++ integrated debugging and development
environment (IDDE) or from an operating system command line The
assembler processes assembly source, data, and header files to produce an
object file. Assembler operations depend on two types of controls:
assembler directives and assembler switches.

VisualDSP++ 5.0 supports the following assembler drivers.

• easm21k.exe (for SHARC processors)

• easmts.exe (for TigerSHARC processors)

• easmblkfn.exe (for Blackfin processors)

This section describes how to develop new programs in the Analog
Devices processor assembly language. It provides information on how to
assemble your programs from the operating system’s command line.

Software developers using the assembler should be familiar with these
topics:

• “Writing Assembly Programs” on page 1-4

• “Using Assembler Support for C Structs” on page 1-21

• “Preprocessing a Program” on page 1-24

• “Using Assembler Feature Macros” on page 1-25

• “Generating Make Dependencies” on page 1-33

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

1-2 VisualDSP++ 5.0 Assembler and Preprocessor Manual

Assembler

• “Enabling Statistical Profiling for Assembly Functions” on

page 1-35

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

For information about a processor’s architecture, including the instruction
set used when writing assembly programs, refer to the Hardware Reference
and the Programming Reference for the appropriate processor.

Assembler Overview

The assembler processes data from assembly source (.asm), data (.dat),
and header (.h) files to generate object files in executable and linkable
format (ELF), an industry-standard format for binary object files. The
object file has a .doj extension.

In addition to the object file, the assembler can produce a listing file
(.lst) that shows the correspondence between the binary code and the
source.

Assembler switches are specified from the VisualDSP++ IDDE or from the
command line used to invoke the assembler. These switches allow you to
control the assembly process of source, data, and header files. Use these
switches to enable and configure assembly features, such as search paths,
output file names, and macro preprocessing. For more information, see

“Assembler Command-Line Reference” on page 1-141.

You can also set assembler options via the Assemble page of the Project
Options dialog box in VisualDSP++. For more information, see “Specify-

ing Assembler Options in VisualDSP++” on page 1-170.

VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-3

Assembler Guide

Writing Assembly Programs

Assembler directives are coded in assembly source files. The directives
allow you to define variables, set up hardware features, and identify pro­gram sections for placement within processor memory. The assembler uses
directives for guidance as it translates a source program into object code.

Write assembly language programs using the VisualDSP++ editor or any
editor that produces text files. Do not use a word processor that embeds
special control codes in the text. Use an .asm extension to source file
names to identify them as assembly source files.

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

shows the preprocessor processing the assembly source (.asm) and header
(.h) files.

Assemble your source files from the VisualDSP++ environment or using
any mechanism, such as a batch file or makefile, that supports invoking an
appropriate assembler driver with a specified command-line command.
By default, the assembler processes an intermediate file to produce a
binary object file (.doj) and an optional listing file (.lst).

Object files produced by the processor assembler may be used as input to
the linker and archiver. You can archive the output of an assembly process
into a library file (.dlb), which can then be linked with other objects into
an executable. Use the linker to combine separately assembled object files
and objects from library files to produce an executable file. For more
information about the linker and archiver, refer to the VisualDSP++ 5.0
Linker and Utilities Manual.

A binary object file (

.doj) and an optional listing (.lst) file are final

results of the successful assembly.

The assembler listing file is a text file read for information on the results
of the assembly process. The listing file also provides information about
the imported C data structures. The listing file tells which imports were
used within the program, followed by a more detailed section. (See the

1-4 VisualDSP++ 5.0 Assembler and Preprocessor Manual

Assembler

Assembler

Preprocessor

Intermediate

preprocessed

file (.IS)

Assembly source file

(.ASP)

Data initialization file

(.DAT)

Header file

(.H)

Listing file

(.LST)

Object file

(.OBJ)

Figure 1-1. Assembler Input and Output Files

.IMPORT directive on page 1-90.) The file shows the name, total size, and

layout with offset for the members. The information appears at the end of
the listing. You must specify the -l switch (on page 1-159) to produce a
listing file.

The assembly source file may contain preprocessor commands, such as

#include

source program. The preprocessor’s only output, an intermediate source
file (
preprocessor output is a temporary file that is deleted during the assembly
process.

VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-5

, that cause the preprocessor to include header files (.h) into the

.is), is the assembler’s primary input. In normal operation, the

Assembler Guide

Program Content

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

Assembly Instructions

Instructions adhere to the processor’s instruction set syntax, which is
documented in the processor’s Programming Reference. Each instruction
line must be terminated by a semicolon (;). On TigerSHARC processors,
each instruction line (which can contain up to 4 instructions) is termi­nated by an additional semicolon (;;). Figure 1-2 on page 1-8 shows an
example assembly source file.

To mark the location of an instruction, place an address label at the begin­ning of an instruction line or on the preceding line. End the label with a
colon (:) before beginning the instruction. Your program can then refer to
this memory location using the label instead of an address. The assembler
places no restriction on the number of characters in a label.

Labels are case sensitive. The assembler treats “outer” and “Outer” as
unique labels. For example (in Blackfin processors),

outer: [I1] = R0;
Outer: R1 = 0X1234;
JUMP outer; // jumps back 2 instructions

Assembler Directives

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

L

1-6 VisualDSP++ 5.0 Assembler and Preprocessor Manual

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

Assembler

For example (Blackfin processors):

.SECTION data1;
.BYTE2 sqrt_coeff[2] = 0x5D1D, 0xA9ED;

For a complete description of the assembler’s directive set, see “Assembler

Directives” on page 1-67.

Preprocessor Commands

Preprocessor commands begin with a pound sign (#) and end with a
carriage return. The pound sign must be the first non-white space
character on the line containing the command. If the command is longer
than one line, use a backslash (\) and a carriage return to continue the
command onto the next line.

Do not put any characters between the backslash and the carriage return.
Unlike assembler directives, preprocessor commands are case sensitive and
must be lowercase. For example,

#include "string.h"
#define MAXIMUM 100

For more information, see “Writing Preprocessor Commands” on

page 2-3. For a list of the preprocessor commands, see “Preprocessor
Command-Line Reference” on page 2-45.

Program Structure

An assembly source file defines code (instructions) and data. It also
organizes the instructions and data to allow the use of the linker descrip­tion file (

.ldf) to describe how code and data are mapped into the

memory on your target processor. The way you structure your code and
data into memory should follow the memory architecture of the target
processor.

VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-7

Assembler Guide

Use the

.SECTION directive to organize the code and data in assembly

source files. The .SECTION directive defines a grouping of instructions and
data that occupies contiguous memory addresses in the processor. The
name given in a .SECTION directive corresponds to an input section name
in the linker description file.

Table 1-1, Table 1-2, and Table 1-3 show suggested input section names

for data and code that can be used in your assembly source for various
processors. Using these predefined names in your sources makes it easier
to take advantage of the default .ldf file included in your DSP system.
However, you may also define your own sections. For information on

.ldf files, refer to the VisualDSP++ 5.0 Linker and Utilities Manual.

Table 1-1. Suggested Input Section Names for a SHARC .ldf File

.SECTION Name Description

seg_pmco A section in program memory that holds code

seg_dmda A section in data memory that holds data

seg_pmda A section in program memory that holds data

seg_rth A section in program memory that holds system initialization code

and interrupt service routines

seg_swco A section in short word memory that holds instructions encoded for

execution from short word memory.
NOTE: Applies to the ADSP-2146x processors only.

Table 1-2. Suggested Input Section Names for a TigerSHARC .ldf File

.SECTION Name Description

data1 A section that holds data in memory block M1

data2 A section that holds data in memory block M2 (specified with the

PM memory qualifier)

program A section that holds code

1-8 VisualDSP++ 5.0 Assembler and Preprocessor Manual

Assembler

Table 1-3. Suggested Input Section Names for a Blackfin .ldf File

.SECTION Name Description

data1 A section that holds data

program A section that holds code

constdata A section that holds global data (which is declared as constant) and

literal constants such as strings and array initializers

Use sections in a program to group elements to meet hardware constraints.
For example, the ADSP-BF535 processor has a separate program and data
memory in Level 1 memory only. Level 2 memory and external memory
are not separated into instruction and data memory.

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

The example assembly program defines three sections. Each section begins
with a

.SECTION directive or end-of-file.

.SECTION directive and ends with the occurrence of the next

Table 1-4 lists the sections in the source program:

Table 1-4. Sections in Source Programs

Section Blackfin SHARC TigerSHARC

Data Section

Variables and buffers are declared and can be
initialized

Program Section

Data, instructions, and possibly other types of
statements are in this section, including state­ments that are needed for conditional assembly

data1
constdata

seg_rth
program

seg_dmda data1

data2

seg_pmco program

Figure 1-2, Figure 1-3 on page 1-14, and Figure 1-4 on page 1-17

describe assembly code file structure for each processor family. They show
how a program divides into sections that match the memory segmentation

VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-9

Assembler Guide

of a DSP system. Notice that an assembly source may contain preproces­sor commands (such as

#ifdef
SECTIONS{} commands define the .SECTION placements in the system’s

(for conditional assembly), or #define (to define macros). The

#include to include other files in source code),

physical memory as defined by the linker’s MEMORY{} command. Assembler
directives, such as .VAR (or .BYTE for Blackfin processors), appear within
sections to declare and initialize variables.

Code File Structure for SHARC Processors

Figure 1-2 describes assembly code file structure for SHARC processors.

Looking at Figure 1-2, notice that the .PRECISION and .ROUND_ZERO
directives inform the assembler to store floating-point data with 40-bit
precision and to round a floating-point value to a closer-to-zero value if it
does not fit in the 40-bit format.

LDF for SHARC Processors

Listing 1-1 shows a sample user-defined .ldf file for SHARC processors.

Looking at the file’s SECTIONS{} command, notice that the INPUT_SECTION
commands map to the names of memory sections (such as program, data1,

data2, ctor, heaptab, and so on) used in the example assembly sample

program.

Listing 1-1. LDF Example for SHARC Processors

ARCHITECTURE(ADSP-21062)
SEARCH_DIR( $ADI_DSP\21k\lib )
$LIBRARIES = lib060.dlb, libc.dlb;
$OBJECTS = $COMMAND_LINE_OBJECTS, 060_hdr.doj;

MEMORY {

seg_rth {TYPE(PM RAM) START(0x20000) END(0x20fff) WIDTH(48)}
seg_init{TYPE(PM RAM) START(0x21000) END(0x2100f) WIDTH(48)}
seg_pmco{TYPE(PM RAM) START(0x21010) END(0x24fff) WIDTH(48)}

1-10 VisualDSP++ 5.0 Assembler and Preprocessor Manual