ANALOG DEVICES W4.5 Assembler Manual

Download

W4.5

Assembler and Preprocessor Manual

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

Revision 2.0, April 2006

Part Number:

82-000420-04

Printed in the USA.

Disclaimer

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

Trademark and Service Mark Notice

The Analog Devices logo, 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

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

Printed Manuals ...................................................................... xxii

VisualDSP++ Documentation Set ........................................ xxii

Hardware Tools Manuals ..................................................... xxii

VisualDSP++ 4.5 Assembler and Preprocessor Manual iii

CONTENTS

Processor Manuals .............................................................. xxii

Data Sheets ........................................................................ xxii

Notation Conventions ................................................................. xxiii

ASSEMBLER

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

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

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

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

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

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

Code File Structure and LDF for TigerSHARC Processors 1-13

Code File Structure and LDF for Blackfin Processors ..... 1-16

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

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

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

Using Assembler Feature Macros ........................................... 1-26

Make Dependencies .............................................................. 1-30

Reading a Listing File ............................................................ 1-31

Statistical Profiling for Assembly Functions ............................ 1-31

Assembler Syntax Reference ........................................................ 1-33

Assembler Keywords and Symbols ......................................... 1-34

Assembler Expressions ........................................................... 1-47

Assembler Operators ............................................................. 1-48

Numeric Formats .................................................................. 1-52

iv VisualDSP++ 4.5 Assembler and Preprocessor Manual

CONTENTS

Fractional Type Support .................................................... 1-53

1.31 Fracts .................................................................... 1-53

1.0r Special Case ........................................................... 1-54

Fractional Arithmetic .................................................... 1-54

Mixed Type Arithmetic ................................................. 1-55

Comment Conventions ......................................................... 1-55

Conditional Assembly Directives ............................................ 1-55

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

OFFSETOF() Built-In Function ....................................... 1-59

SIZEOF() Built-In Function ............................................. 1-59

Struct References ................................................................... 1-60

Assembler Directives .............................................................. 1-63

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

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

.ASCII .............................................................................. 1-72

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

ASCII String Initialization Support ............................... 1-75

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

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

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

.FILE_ATTR, Create an attribute in the object file ............ 1-81

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

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

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

VisualDSP++ 4.5 Assembler and Preprocessor Manual v

CONTENTS

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

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

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

.LIST_DATFILE/.NOLIST_DATFILE, Listing Data Initialization

Files .............................................................................. 1-90

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

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

.LIST_WRAPDATA/.NOLIST_WRAPDATA .................. 1-93

.MESSAGE, Alter the severity of an assembler message ...... 1-94

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

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

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

.PORT, Legacy Directive ................................................. 1-101

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

.PREVIOUS, Revert to the Previously Defined Section ... 1-103 .PRIORITY, Allow Prioritized Symbol Mapping in the Linker ...

1-104

Linker Operation ........................................................ 1-105

.REFERENCE, .............................................................. 1-107

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

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

Common .SECTION Attributes ................................. 1-111

DOUBLE* Qualifiers ................................................. 1-112

TigerSHARC-Specific Qualifiers ................................. 1-113

SHARC-Specific Qualifiers ......................................... 1-114

vi VisualDSP++ 4.5 Assembler and Preprocessor Manual

CONTENTS

Initialization Section Qualifiers ................................... 1-115

.SEGMENT & .ENDSEG, Legacy Directives .................. 1-117

.SEPARATE_MEM_SEGMENTS ................................... 1-117

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

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

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

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

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

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

Assembler Command-Line Reference ......................................... 1-129

Running the Assembler ........................................................ 1-130

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

-align-branch-lines .......................................................... 1-135

-char-size-8 ..................................................................... 1-136

-char-size-32 ................................................................... 1-136

-char-size-any .................................................................. 1-136

-default-branch-np .......................................................... 1-136

-default-branch-p ............................................................ 1-137

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

-double-size-32 ............................................................... 1-137

-double-size-64 ............................................................... 1-138

-double-size-any .............................................................. 1-138

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

-flags-compiler ................................................................ 1-139

VisualDSP++ 4.5 Assembler and Preprocessor Manual vii

CONTENTS

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

-g ................................................................................... 1-141

-h[elp] ............................................................................ 1-142

-i|I directory ................................................................... 1-142

-l filename ...................................................................... 1-143

-li filename ..................................................................... 1-144

-M ................................................................................. 1-144

-MM .............................................................................. 1-144

-Mo filename .................................................................. 1-145

User-Specified Defines Options ................................... 1-139

Include Options ......................................................... 1-140

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

-Mt filename .................................................................. 1-145

-micaswarn ..................................................................... 1-145

-no-source-dependency ................................................... 1-145

-o filename ..................................................................... 1-146

-pp ................................................................................. 1-146

-proc processor ............................................................... 1-146

-save-temps .................................................................... 1-147

-si-revision version .......................................................... 1-147

-sp ................................................................................. 1-148

-stallcheck ...................................................................... 1-148

-v[erbose] ....................................................................... 1-149

-version .......................................................................... 1-149

viii VisualDSP++ 4.5 Assembler and Preprocessor Manual

CONTENTS

-w ................................................................................... 1-149

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

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

-Wno-info ...................................................................... 1-149

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

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

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

-Wwarn-error .................................................................. 1-150

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

PREPROCESSOR

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

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

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

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

Using Predefined Preprocessor Macros ..................................... 2-9

Specifying Preprocessor Options ............................................ 2-13

Preprocessor Command Reference ............................................... 2-14

Preprocessor Commands and Operators ................................. 2-14

#define ............................................................................. 2-16

Variable Length Argument Definitions .......................... 2-17

#elif .................................................................................. 2-19

#else ................................................................................. 2-20

#endif ............................................................................... 2-21

#error ............................................................................... 2-22

VisualDSP++ 4.5 Assembler and Preprocessor Manual ix

CONTENTS

#if .................................................................................... 2-23

#ifdef ............................................................................... 2-24

#ifndef ............................................................................. 2-25

#include ........................................................................... 2-26

#line ................................................................................ 2-28

#pragma ........................................................................... 2-29

#undef ............................................................................. 2-30

#warning .......................................................................... 2-31

# (Argument) ................................................................... 2-32

## (Concatenate) .............................................................. 2-33

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

Preprocessor Command-Line Reference ....................................... 2-36

Running the Preprocessor ...................................................... 2-36

Preprocessor Command-Line Switches ................................... 2-37

-cstring ............................................................................. 2-39

-cs! ................................................................................... 2-40

-cs/* ................................................................................. 2-40

-cs// ................................................................................. 2-40

-cs{ ................................................................................... 2-40

-csall ................................................................................ 2-41

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

-h[elp] .............................................................................. 2-41

-i ...................................................................................... 2-41

-i|I directory ..................................................................... 2-42

x VisualDSP++ 4.5 Assembler and Preprocessor Manual

CONTENTS

Using the -I- Switch ...................................................... 2-43

-M .................................................................................... 2-43

-MM ................................................................................ 2-44

-Mo filename .................................................................... 2-44

-Mt filename ..................................................................... 2-44

-o filename ....................................................................... 2-44

-stringize ........................................................................... 2-44

-tokenize-dot .................................................................... 2-45

-Uname ............................................................................ 2-45

-v[erbose] ......................................................................... 2-45

-version ............................................................................ 2-46

-w ..................................................................................... 2-46

-Wnumber ........................................................................ 2-46

-warn ................................................................................ 2-46

INDEX

VisualDSP++ 4.5 Assembler and Preprocessor Manual xi

-xii VisualDSP++ 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 Manual xiii

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.

xiv VisualDSP++ 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

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

• E-mail tools questions to

processor.tools.support@analog.com

• E-mail processor questions to

processor.support@analog.com (World wide support) processor.europe@analog.com (Europe support) processor.china@analog.com (China support)

• Phone questions to 1-800-ANALOGD

Preface

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

• Send questions by mail to:

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

VisualDSP++ 4.5 Assembler and Preprocessor Manual xv

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:

ADSP-21020 ADSP-21060 ADSP-21061 ADSP-21062 ADSP-21065L ADSP-21160 ADSP-21161 ADSP-21261 ADSP-21262 ADSP-21266 ADSP-21267 ADSP-21363 ADSP-21364 ADSP-21365 ADSP-21366 ADSP-21367 ADSP-21368 ADSP-21369 ADSP-21371 ADSP-21375

xvi VisualDSP++ 4.5 Assembler and Preprocessor Manual

Preface

Blackfin (ADSP-BFxxx) Processors

The name “Blackfin” refers to a family of 16-bit, embedded processors. VisualDSP++ currently supports the following Blackfin processors:

ADSP-BF531 ADSP-BF532 AD6901 ADSP-BF533 ADSP-BF534 AD6902 ADSP-BF535 ADSP-BF536 ADSP-BF541 ADSP-BF537 ADSP-BF538 ADSP-BF542 ADSP-BF539 ADSP-BF561 ADSP-BF544 AD6903 AD6531 ADSP-BF549 AD6901 AD6902

Product Information

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 Manual xvii

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.

• E-mail questions or requests for information to

processor.support@analog.com (World wide support) processor.europe@analog.com (Europe support) processor.china@analog.com (China support)

• Fax questions or requests for information to

1-781-461-3010 (North America) +49-89-76903-157 (Europe)

• Access the FTP Web site at

ftp ftp.analog.com (or ftp 137.71.25.69) ftp://ftp.analog.com

xviii VisualDSP++ 4.5 Assembler and Preprocessor Manual

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

.CHM Help system files and manuals in Help format

.PDF files of most manuals are also provided.

.HTM or .HTML

.PDF VisualDSP++ 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).

xx VisualDSP++ 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:

http://www.analog.com/processors/resources/technicalLibrary/manuals

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 Manual xxi

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.

xxii VisualDSP++ 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.

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.

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 Manual xxiii

Notation Conventions

Example Description

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.

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.

xxiv VisualDSP++ 4.5 Assembler and Preprocessor Manual

1 ASSEMBLER

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

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-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

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:

• For SHARC processors – easm21k.exe assembler driver

• For TigerSHARC processors – easmts.exe assembler driver

• For Blackfin processors – easmblkfn.exe assembler driver

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-2 VisualDSP++ 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 Manual 1-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-4 VisualDSP++ 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 Manual 1-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),

outer: [I1] = R0; Outer: R1 = 0X1234; 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 (in Blackfin processors),

1-6 VisualDSP++ 4.5 Assembler and Preprocessor Manual

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

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

Assembler

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 Manual 1-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 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

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

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

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

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

1-8 VisualDSP++ 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

Section SHARC TigerSHARC Blackfin

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_dmda data1

data2

seg_pmco program seg_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 Manual 1-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-10 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

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)} seg_pmda{TYPE(DM RAM) START(0x28000) END(0x28fff) WIDTH(32)} seg_dmda{TYPE(DM RAM) START(0x29000) END(0x29fff) WIDTH(32)} seg_stak{TYPE(DM RAM) START(0x2e000) END(0x2ffff) WIDTH(32)}

/* memory declarations for default heap */

seg_heap{TYPE(DM RAM) START(0x2a000) END(0x2bfff) WIDTH(32)}

/* memory declarations for custom heap */ seg_heaq{TYPE(DM RAM) START(0x2c000) END(0x2dfff) WIDTH(32)} } // End MEMORY

PROCESSOR p0 {

LINK_AGAINST( $COMMAND_LINE_LINK_AGAINST) OUTPUT( $COMMAND_LINE_OUTPUT_FILE )

SECTIONS {

.seg_rth {

INPUT_SECTIONS( $OBJECTS(seg_rth) $LIBRARIES(seg_rth)) } > seg_rth .seg_init {

INPUT_SECTIONS( $OBJECTS(seg_init) $LIBRARIES(seg_init)) } > seg_init .seg_pmco {

INPUT_SECTIONS( $OBJECTS(seg_pmco) $LIBRARIES(seg_pmco)) } > seg_pmco .seg_pmda {

INPUT_SECTIONS( $OBJECTS(seg_pmda) $LIBRARIES(seg_pmda)) } > seg_pmda .seg_dmda {

INPUT_SECTIONS( $OBJECTS(seg_dmda) $LIBRARIES(seg_dmda)) } > seg_dmda

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-11

Assembler Guide

.stackseg {

ldf_stack_space = .; ldf_stack_length = 0x2000;

} > seg_stak

/* section placement for default heap */ .heap {

ldf_heap_space = .; ldf_heap_end = ldf_heap_space + 0x2000; ldf_heap_length = ldf_heap_end - ldf_heap_space;

} > seg_heap

/* section placement for additional custom heap */ .heaq {

ldf_heaq_space = .; ldf_heaq_end = ldf_heaq_space + 0x2000; ldf_heaq_length = ldf_heaq_end - ldf_heaq_space;

} > seg_heaq

} // End SECTIONS

} // End P0

1-12 VisualDSP++ 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 Manual 1-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

ARCHITECTURE(ADSP-TS101) SEARCH_DIR( $ADI_DSP\TS\lib ) $OBJECTS = $COMMAND_LINE_OBJECTS;

// Internal memory blocks are 0x10000 (64k)

MEMORY {

M0Code { TYPE(RAM) START(0x00000000) END(0x0000FFFF) WIDTH(32) } M1Data { TYPE(RAM) START(0x00080000) END(0x0008BFFF) WIDTH(32) } M1Heap { TYPE(RAM) START(0x0008C000) END(0x0008C7FF) WIDTH(32) } M1Stack { TYPE(RAM) START(0x0008C800) END(0x0008FFFF) WIDTH(32) } M2Data { TYPE(RAM) START(0x00100000) END(0x0010BFFF) WIDTH(32) } M2Stack { TYPE(RAM) START(0x0010C000) END(0x0010FFFF) WIDTH(32) } SDRAM { TYPE(RAM) START(0x04000000) END(0x07FFFFFF) WIDTH(32) } MS0 { TYPE(RAM) START(0x08000000) END(0x0BFFFFFF) WIDTH(32) } MS1 { TYPE(RAM) START(0x0C000000) END(0x0FFFFFFF) WIDTH(32) }

}

PROCESSOR p0 /* The processor in the system * {

OUTPUT($COMMAND_LINE_OUTPUT_FILE)

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

code {

FILL(0xb3c00000) INPUT_SECTION_ALIGN(4) INPUT_SECTIONS( $OBJECTS(program) )

} >M0Code

1-14 VisualDSP++ 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 {

INPUT_SECTIONS( $OBJECTS(ctor0) ) INPUT_SECTIONS( $OBJECTS(ctor1) ) INPUT_SECTIONS( $OBJECTS(ctor2) ) INPUT_SECTIONS( $OBJECTS(ctor3) ) INPUT_SECTIONS( $OBJECTS(ctor) )

} >M1Data

// Table containing heap segment descriptors heaptab {

INPUT_SECTIONS( $OBJECTS(heaptab) )

} >M1Data

// Allocate stacks for the application. jstackseg {

ldf_jstack_limit = .; ldf_jstack_base = . + MEMORY_SIZEOF(M1Stack);

} >M1Stack

kstackseg {

ldf_kstack_limit = .; ldf_kstack_base = . + MEMORY_SIZEOF(M2Stack);

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-15

Assembler Guide

} >M2Stack

// The default heap occupies its own memory block. defheapseg {

ldf_defheap_base = .; ldf_defheap_size = MEMORY_SIZEOF(M1Heap);

} >M1Heap

}

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.

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-16 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Figure 1-4. Assembly Source File Structure for Blackfin Processors

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-17

Assembler Guide

Listing 1-3. Example Linker Description File for Blackfin Processors

ARCHITECTURE(ADSP-BF535) SEARCH_DIR($ADI_DSP\Blackfin\lib) #define LIBS libc.dlb, libdsp.dlb $LIBRARIES = LIBS, librt535.dlb; $OBJECTS = $COMMAND_LINE_OBJECTS;

MEMORY /* Define/label system memory */ { /* List of global Memory Segments */ MEM_PROGRAM { TYPE(RAM) START(0xF0000000) END(0xF002FFFF) WIDTH(8) } MEM_HEAP { TYPE(RAM) START(0xF0030000) END(0xF0037FFF) WIDTH(8) } MEM_STACK { TYPE(RAM) START(0xF0038000) END(0xF003DFFF) WIDTH(8) } MEM_SYSSTACK { TYPE(RAM) START(0xF003E000) END(0xF003FDFF) WIDTH(8) } MEM_ARGV { TYPE(RAM) START(0xF003FE00) END(0xF003FFFF) WIDTH(8) } }

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

OUTPUT($COMMAND_LINE_OUTPUT_FILE)

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

program { // Align all code sections on 2 byte boundary

INPUT_SECTION_ALIGN(2)

INPUT_SECTIONS( $OBJECTS(program) $LIBRARIES(program))

INPUT_SECTION_ALIGN(1)

INPUT_SECTIONS( $OBJECTS(data1) $LIBRARIES(data1))

INPUT_SECTION_ALIGN(1)

INPUT_SECTIONS(

INPUT_SECTION_ALIGN(1)

INPUT_SECTIONS( $OBJECTS(ctor) $LIBRARIES(ctor))

INPUT_SECTION_ALIGN(2)

INPUT_SECTIONS( $OBJECTS(seg_rth))

} >MEM_PROGRAM

stack

$OBJECTS(constdata)$LIBRARIES(constdata))

1-18 VisualDSP++ 4.5 Assembler and Preprocessor Manual

sysstack

heap

- 1;

Assembler

{

ldf_stack_space = .; ldf_stack_end = ldf_stack_space +

MEMORY_SIZEOF(MEM_STACK) - 4;

} >MEM_STACK

{

ldf_sysstack_space = .; ldf_sysstack_end = ldf_sysstack_space +

MEMORY_SIZEOF(MEM_SYSSTACK) - 4;

} >MEM_SYSSTACK

{ // Allocate a heap for the application

ldf_heap_space = .; ldf_heap_end = ldf_heap_space + MEMORY_SIZEOF(MEM_HEAP)

ldf_heap_length = ldf_heap_end - ldf_heap_space;

} >MEM_HEAP

argv

{ // Allocate argv space for the application

ldf_argv_space = .; ldf_argv_end = ldf_argv_space + MEMORY_SIZEOF(MEM_ARGV)

- 1; ldf_argv_length = ldf_argv_end - ldf_argv_space;

} >MEM_ARGV

}

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-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-20 VisualDSP++ 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 Manual 1-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.

Blackfin Example

.IMPORT "Coordinate.h";

// typedef struct Coordinate { // int X; // int Y; // int Z; // } Coordinate;

.SECTION data1;

.STRUCT Coordinate Coord1 = {

X = 1, Y = 4, Z = 7 };

.SECTION program;

P0.l = Coord1->X; P0.h = Coord1->X;

P1.l = Coord1->Y; P1.h = Coord1->Y;

P2.l = Coord1->Z; P2.h = Coord1->Z;

P3.l = Coord1+OFFSETOF(Coordinate,Z); P3.h = Coord1+OFFSETOF(Coordinate,Z);

1-22 VisualDSP++ 4.5 Assembler and Preprocessor Manual

SHARC Example

.IMPORT "Samples.h";

// typedef struct Samples { // int I1; // int I2; // int I3; // }Samples;

.SECTION/DM seg_dmda;

.STRUCT Samples Sample1 ={

I1 = 0x1000, I2 = 0x2000, I3 = 0x3000 };

.SECTION/PM seg_pmco;

doubleMe: // The code may look confusing, but I2 can be used both // as a register and a struct member name B2 = Sample1; M2 = OFFSETOF(Sample1,I2); R0 = DM(M2,I2); R0 = R0+R0; DM(M2,I2) = R0;

Assembler

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 Manual 1-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-24 VisualDSP++ 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 Manual 1-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=1 Always present

-D__ADSP21000__=1 Always present

-D__ADSP21020__=1

-D__2102x__=1

-D__ADSP21060__=1

-D__2106x__=1

-D__ADSP21061__=1

-D__2106x__=1

-D__ADSP21062__=1

-D__2106x__=1

-D__ADSP21065L__=1

-D__2106x__=1

-D__ADSP21160__=1

-D__2116x__=1

-D__ADSP21161__=1

-D__2116x__=1

-D__ADSP21261__=1

-D__2126x__=1

-D__ADSP21262__=1

-D__2126x__=1

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-26 VisualDSP++ 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 =1 Always present

-D__ADSPTS__ =1 Always present

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-27

Assembler Guide

Table 1-6. Feature Macros for TigerSHARC Processors (Cont’d)

-D__ADSPTS101__ =1 Present when running easmts -proc ADSP-TS101

with ADSP-TS101 processor

-D__ADSPTS201__ =1 Present when running easmts -proc ADSP-TS201

with ADSP-TS201 processor

-D__ADSPTS202__ =1 Present when running easmts -proc ADSP-TS202

with ADSP-TS202 processor

-D__ADSPTS203__ =1 Present when running easmts -proc ADSP-TS203

with ADSP-TS203 processor

-D__ADSPTS20x__ =1 Present 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=1 Always 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__=1 Present 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__=1 Present when running easmblkfn -proc ADSP-BF536

Present when running easmblkfn -proc ADSP-BF535 with ADSP-BF535 processor.

with ADSP-BF536 processor.

1-28 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Table 1-7. Feature Macros for Blackfin Processors (Cont’d)

-D__ADSPBF537__=1 Present when running easmblkfn -proc ADSP-BF537

with ADSP-BF537 processor.

-D__ADSPBF538__=1 Present when running easmblkfn -proc ADSP-BF538

with ADSP-BF538 processor.

-D__ADSPBF539__=1 Present when running easmblkfn -proc ADSP-BF539

with ADSP-BF539 processor.

-D__ADSPBF561__=1 Present when running easmblkfn -proc ADSP-BF561

with ADSP-BF561 processor.

-D__AD6531__=1 Present when running easmblkfn -proc AD6531

with AD6531 processor.

-D__AD6532__=1 Present when running easmblkfn -proc AD6532

with AD6532 processor.

-D__AD6900__=1 Present when running easmblkfn -proc AD6900

with AD6900 processor.

Assembler

-D__AD6901__=1 Present when running easmblkfn -proc AD6901

with AD6901 processor.

-D__AD6902__=1 Present when running easmblkfn -proc AD6902

with AD6902 processor.

-D__AD6903__=1 Present 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

-D_LANGUAGE_C=1). This macro is present when

-D_LANGUAGE_ASM.

For example,

easm21k -proc adsp-21262 assembly --> cc21K -proc adsp-21262 easmts -proc -ADSP-TS101 easmblkfn -proc ADSP-BF535

ADSP-BF535

assembly --> ccts -proc ADSP-TS101

assembly --> ccblkfn -proc

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-29

Assembler Guide

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.

easmblkfn -proc ADSP-BF533 -MM main.asm

"main.doj": "/VisualDSP/Blackfin/include/defBF532.h" "main.doj": "/VisualDSP/Blackfin/include/defBF533.h" "main.doj": "/VisualDSP/Blackfin/include/def_LPBlackfin.h" "main.doj": "main.asm" "main.doj": "input_data.dat"

The original source file main.asm is as follows:

... #include "defBF533.h" ... .GLOBAL input_frame; .BYTE input_frame[N] = "input_data.dat"; // load in 256 values

// from a test file

...

1-30 VisualDSP++ 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 Manual 1-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-32 VisualDSP++ 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 Manual 1-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.

Table 1-8. SHARC Processor Assembler Keywords

__ADI__ __DATE__ __FILE__ __LastSuffix__ __LINE__

__TIME__

.ALIGN .ELIF .ELSE .ENDIF .EXTERN

.FILE .FILE_ATTR .GLOBAL .IF .IMPORT

.LEFTMARGIN .LIST .LIST_DATA .LIST_DATFILE .LIST_DEFTAB

.LIST_LOCTAB

NOLIST_WRAPDATA

.ROUND_NEAREST

.STRUCT .VAR .WEAK

ABS ACS ACT ADDRESS AND

ASHIFT ASTAT AV

B0 B1 B2 B3 B4

B5 B6 B7 B8 B9

B10 B11 B12 B13 B14

B15 BB BCLR BF BIT

.LIST_WRAPDATA

.PAGELENGTH .PAGEWIDTH .PRECISION .ROUND_MINUS

.ROUND_PLUS .ROUND_ZERO .PREVIOUS .SECTION

.NEWPAGE .NOLIST_DATA

.NOLIST_DATFILE

1-34 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-8. SHARC Processor Assembler Keywords (Cont’d)

BITREV BM BSET BTGL BTSTS

CA CACHE CALL CH CI

CJUMP CL CLIP COMP COPYSIGN

COS CURLCNTR

DADDR DB DEC DEF DIM

DMA1E DMA1S DMA2E DMA2S DMADR

DMABANK1 DMABANK2 DMABANK3 DMAWAIT DO

DOVL

EB ECE EF ELSE EMUCLK

EMUCLK2 EMUIDLE EMUN ENDEF EOS

EQ EX EXP EXP2

F0 F1 F2 F3 F4

F5 F6 F7 F8 F9

F10 F11 F12 F13 F14

F15 FADDR FDEP FEXT FILE

FIX FLAGO_IN FLAG1_IN FLAG2_IN FLAG3_IN

FLOAT FLUSH FMERG FOREVER FPACK

FRACTIONAL FTA FTB FTC FUNPACK

GCC_COMPILED GE GT

I0 I1 I2 I3 I4

I5 I6 I7 I8 I9

I10 I11 I12 I13 I14

I15 IDLEI15 IDLE16 IF IMASK

IMASKP INC IRPTL

JUMP

L0 L1 L2 L3 L4

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-35

Assembler Syntax Reference

Table 1-8. SHARC Processor Assembler Keywords (Cont’d)

L5 L6 L7 L8 L9

L10 L11 L12 L13 L14

L15 LA LADDR LCE LCNTR

LE LADDR LCE LCNTR LE

L15 LA LADDR LCE LCNTR

LE LEFTO LEFTZ LENGTH

LINE LN LOAD LOG2 LOGB

LOOP LR LSHIFT LT

M0 M1 M2 M3 M4

M5 M6 M7 M8 M9

M10 M11 M12 M13 M14

M15 MANT MAX MBM MIN

MOD MODE1 MODE2 MODIFY MROB

MROF MR1B MR1F MR2B MR2F

MRB MRF MS MV MROB

MROF

NE NOFO NOFZ NOP NOPSPECIAL

NOT NU

OFFSETOF OR

P20 P32 P40 PACK PAGE

PC PCSTK PCSTKP PM PMADR

PMBANK1 PMDAE PMDAS POP POVLO

POVL1 PSA1E PSA1S PSA2E PSA3E

PSA3S PSA4E PSA4S PUSH PX

PX1 PX2

R0 R1 R2 R3 R4

RF5 R6 R7 R8 R9

1-36 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-8. SHARC Processor Assembler Keywords (Cont’d)

R10 R11 R12 R13 R14

R15 READ RECIPS RFRAME RND

ROT RS RSQRTS RTI RTS

SCALB SCL SE SET SF

SIN SIZE SIZEOF SQR SR

SSF SSFR SSI SSIR ST

STEP STKY STRUCT STS SUF

SUFR SV SZ

TAG TCOUNT TF TGL TPERIOD

TRUE TRUNC TST TYPE TRAP

UF UI UNPACK UNTIL UR

USF USFR USI USIR USTAT1

USTAT2 UUF UUFR UUIR UUIR

VAL

WITH

XOR

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-37

Assembler Syntax Reference

Table 1-9 lists the assembler keywords for TigerSHARC processors.

Table 1-9. TigerSHARC Processor Assembler Keywords

__ADI__ __DATE__ __FILE__ __LastSuffix__ __LINE__

__TIME__

.ALIGN .ALIGN_CODE .ELIF .ELSE .ENDIF

.EXTERN .FILE .FILE_ATTR .GLOBAL .IF

.IMPORT .LEFTMARGIN .LIST .LIST_DATA .LIST_DATFILE

.LIST_DEFTAB .LIST_LOCTAB

.NOLIST_DATFILE.NOLIST_WRAPDATA

.NOLIST_WRAPDATA

.SEPARATE_MEM_ SEGMENTS

ABS ACS ADDRESS AND ASHIFT

BCLR BFOINC BFOTMP BITEST BITFIFO

BKFPT BR BSET BTBDIS BTBELOCK

BTBEN BTBLOCK BTBINV BTGL BY

C CALL CB CJMP CJMP_CALL

CI CLIP COMP COMPACT COPYSIGN

DAB DEC DESPREAD D0

ELSE EMUTRAP EXP EXPAND EXTD

FCOMP FDEP FEXT FIX FLOAT

FTEST0 FTEST1 FOR

GETBITS

IDLE INC

.PAGELENGTH .PAGEWIDTH .PREVIOUS .SECTION

.SET .STRUCT .VAR .WEAK

.LIST_WRAPDATA

.NEWPAGE .NOLIST_DATA

.MESSAGE .NOLIST_DATA

.NOLIST_DATFILE

JC JUMP

1-38 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-9. TigerSHARC Processor Assembler Keywords (Cont’d)

LD0 LD1 LENGTH LINES LOGB

LP LSHIFT LSHIFTR LIBSIM_CALL

MANT MASK MAX MERGE MIN

NEWPAGE NOT NOP NP

OFFSETOF ONES OR

PASS PERMUTE PRECISION PUTBITS

RDS RECIPS RESET RETI ROT

ROTL ROTR ROUND RSQRTS RTI

SCALB SDAB SE SECTION SFO

SF1 SNGL SIZE SIZEOF STRUCT

SUM

TMAX TRAP TYPEVAR UNTIL

VMIN VMAX

XCORRS XOR XSDAB

YDAB YSDAB

// JK Register Group

J0 through J31

K0 through K31

JB0 JB1 JB2 JB3

KB0 KB1 KB2 KB3

JL0 JL1 JL2 JL3

KL0 KL1 KL2 KL3

// RF Register Group

FR0 through FR31

MR3:0 MR3:2 MR1:0

MR0 MR1 MR2 MR3 MR4

PR0 PR1 PR1:0

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-39

Assembler Syntax Reference

Table 1-9. TigerSHARC Processor Assembler Keywords (Cont’d)

R0 through R31

XSTAT YSTAT XYSTAT

XR0 through XR31

YR0 through YR31

// Accelerator Register Group

TR0 through TR31

THR0 THR1 THR2 THR3

// EP Register Group

BMAX BMAXC BUSLK FLGPIN FLGPINCL

FLGPINST SDRCON SYSCON SYSCONCL SYSCONST

SYSCTL SYSTAT SYSTATCL

// Misc. Register Group

AUTODMA0 AUTODMA1

BTBCMD BTBDATA

BTB0TG0 through BTB0TG31

BTB1TG0 through BTB1TG31

BTB2TG0 through BTB2TG31

BTB3TG0 through BTB3TG31

BTB0TR0 through BTB0TR31

BTB1TR0 through BTB1TR31

BTB2TR0 through BTB2TR31

BTB3TR0 through BTB3TR31

BTBLRU0 through BTBLRU31

CACMD0 CACMD2 CACMD4 CACMD8 CACMD10

CACMDALL

CADATA0 CADATA2 CADATA4 CADATA8 CADATA10

CADATAALL

1-40 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-9. TigerSHARC Processor Assembler Keywords (Cont’d)

CASTAT0 CASTAT2 CASTAT4 CASTAT8 CASTAT10

CASTATALL

CCAIR0 CCAIR2 CCAIR4 CCAIR8 CCAIR10

CCAIRALL

CCNT0 CCNT1 CJMP CMCTL

DBGE DC4 through DC13

DCD0 DCD1 DCD2 DCD3 DCNT

DCNTCL DCNTST

DCS0 DCS1 DCS2 DCS3

DSTAT DSTATC

EMUCTL EMUDAT EMUIR EMUSTAT

IDCODE ILATCLH ILATCLL ILATH ILATL

ILATSTH ILATSTL IMASKH IMASKL INSTAT

INTEN INTCTL IVBUSLK IVDBG IVHW

IVDMA0 through IVDMA13

IVIRQ0 IVIRQ1 IVIRQ2 IVIRQ3 IVLINK0

IVLINK1 IVLINK2 IVLINK3 IVSW IVTIMER0HP

IVTIMER0LP IVTIMER1HP IVTIMER1LP

LBUFRX0 LBUFRX1 LBUFRX2 LBUFRX3

LBUFTX0 LBUFTX1 LBUFTX2 LBUFTX3

LC0 LC1 KB2 KB3

LCTL0 LCTL1 LCTL2 LCTL3

LRCTL0 LRCTL1 LRCTL2 LRCTL3

LRSTAT0 LRSTAT1 LRSTAT2 LRSTAT3

LRSTATC0 LRSTATC1 LRSTATC2 LRSTATC3

LSTAT0 LSTAT1 LSTAT2 LSTAT3

LSTATC0 LSTATC1 LSTATC2 LSTATC3

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-41

Assembler Syntax Reference

Table 1-9. TigerSHARC Processor Assembler Keywords (Cont’d)

LTCTL0 LTCTL1 LTCTL2 LTCTL3

LTSTAT0 LTSTAT1 LTSTAT2 LTSTAT3

LTSTATC0 LTSTATC1 LTSTATC2 LTSTATC3

MISR0 MISR1 MISR2 MISRCTL

RETI RETIB RETS RTI

OSPID

PMASKH PMASKL PRFM PRFCNT

SERIAL_H SERIAL_L SFREG SQCTL SQCTLST

SQCTLCL SQSTAT

TESTMODES TIMER0L TIMER1L TIMER0H TIMER1H

TMRIN0L TMRIN0H TMRIN1L TMRIN1H TRCB

TRCBMASK TRCBPTR TRCBVAL

VIRPT

WP0CTL WP1CTL WP2CTL WP0STAT WP1STAT

WP2STAT W0H W0L W1H W1L

W2H W2L

// Conditions which may be prefixed with X, Y, XY, NX, NY, XY

AEQ ALE ALT MEQ MLE

MLT SEQ SF1 SF0 SLT

// Conditions which may be prefixed with J, K, NJ, NK

EQ LE LT CBQ CB1

// Conditions which may be prefixed with N

ISF0 ISF1 LC0E LC1E BM

FLAG0_IN FLAG1_IN FLAG2_IN FLAG3_IN

1-42 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-10 lists the assembler keywords for Blackfin processors.

Table 1-10. Blackfin Processor Assembler Keywords

.ALIGN .ASCII .ASM_ASSERT .ASSERT .BSS

.BYTE .BYTE2 .BYTE4 .DATA .ELIF

.ELSE .ENDIF .ELSE .ENDIF .EXTERN

.FILE .FILE_ATTR .GLOBAL .GLOBL

.IF .INC/BINARY .INCBIN .IMPORT

.LEFTMARGIN .LIST .LIST_DATA .LIST_DATFILE .LIST_DEFTAB

.LIST_LOCTAB .

.NEWPAGE .NOLIST .NOLIST_DATA

.PAGELENGTH .PAGEWIDTH .PREVIOUS .SECTION .SET SYMBOL

SHORT

EXPRESSION-LIST

.WEAK

A0 A1 ABORT ABS AC

ALIGN8 ALIGN16 ALIGN24 AMNOP AN

AND ASHIFT ASL ASR ASSIGN

ASTAT AV0 AV1 AZ

B B0B1B2 B3

BANG BAR BITCLR BITMUX BITPOS

BITSET BITTGL BITTST BIT_XOR_AC BP

BREV BRF BRT BY BYTEOP1P

BYTEOP16M BYTEOP1NS BYTEOP16P BYTEOP2M BYTEOP2P

BYTEOP3P BYTEPACK BYTEUNPACK BXOR BXORSHIFT

CALL CARET CC CLI CLIP

CO CODE COLON COMMA CSYNC

LIST_WRAPDATA.LONG

EXPRESSION-LIST

.NOLIST_DATFILE.NOLIST_WRAPDATA

.SYMBOL

.STRUCT .TEXT .TYPE .VAR

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-43

Assembler Syntax Reference

Table 1-10. Blackfin Processor Assembler Keywords (Cont’d)

DATA

DEPOSIT DISALGNEXCPT DIVSDEPOSIT

DOZE DIVQ DIVS DOT EMUCAUSE

EMUEXCPT EXCAUSE EXCPT EXPADJ EXTRACT

FEXT FEXTSX FLUSH FLUSHINV FP

FU GE GF GT

H HI HLT HWERRCAUSE

I0 I1 I2 I3 IDLE

IDLE_REQ IFLUSH IH INTRP IS

ISS2 IU JUMP JUMP.L JUMP.S

L LB0 LB1 LC0 LC1

LE LENGTH LINK LJUMP LMAX

LMIN LO LOOP LOOP_BEGIN LOOP_END

LPAREN LSETUP LSHIFT LT LT0

LT1 LZ

M M0 M1 M2 M3

MAX MIN MINUS MNOP MUNOP

NEG NO_INIT NOP NOT NS

ONES OR OUTC

P0 P1 P2 P3 P4

P5 PACK PC PRNT PERCENT

PLUS PREFETCH

R R0 R1 R2 R3

R32R4R5R6 R7

RAISE RBRACE RBRACK RETI RETN

RETS RETX RND RND12 RND20

RNDH RNDL ROL ROR ROT

1-44 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-10. Blackfin Processor Assembler Keywords (Cont’d)

ROT_L_AC ROT_R_AC RPAREN RSDL RTE

RTI RTN RTS RTX RUNTIME_INIT

R1_COLON0

S S2RND SAA SAA1H SAA1L

SAA2H SAA2L SAA3H SAA3L SAT

SCO SEARCH SHT_TYPE SIGN SIGNBITS

SLASH SLEEP SKPF SKPT SP

SS SSF SSF_RND_HI SSF_TRUNC SSF_TRUNC_HI

SSF_RND SSF_TRUNC SSYN STI STRUCT

STT_TYPE SU SYSCFG

T TESTSET TFU TH TL

TST UNLINK UNLNK UNRAISE UU

V VIT_MAX

W W32 WEAK

X XB XH XOR Z

ZERO_INIT

_ADI_ _DATE_ _FILE_ _LastSuffix_ _LINE_

_TIME_

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 Manual 1-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-46 VisualDSP++ 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 Manual 1-47

Assembler Syntax Reference

data/8 (data_buffer1 + data_buffer2) & 0xF strtup + 2 data_buffer1 + LENGTH(data_buffer2)*2

Symbols in this type of expression are data variables, data buffers, and program labels. In the first three examples above, the symbol name represents the address of the symbol. The fourth 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

Operator Usage Description Designation

(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-48 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-11. Operator Precedence (Cont’d)

Operator Usage Description Designation

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

Operator Usage 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)

symbol Address pointer to symbol

Extracts the most significant 16 bits of expression. Extracts the least significant 16 bits of expression.

Note: Used with the Blackfin assembler ONLY where replaces the 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 Manual 1-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

bitpos(0x80) would return 7. For example,

#define DLAB 0x80 #define EPS 0x10 r0 = DLAB | EPS (z); cc = bitset (r0, BITPOS(DLAB));

TigerSHARC Processor Example

The following example demonstrates how 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-50 VisualDSP++ 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 …

.SECTION/PM seg_pmco; // code segment

B5=real_data; // buffer base address

// I5 loads automatically L5=length(real_data); // buffer’s length M6=1; // post-modify I5 by 1 LCNTR=length(real_data)

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-51

Assembler Syntax Reference

,DO loopend UNTIL LCE;

F0=DM(I5,M6); // get next sample … loopend: …

// loop counter=buffer’s length

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

Convention Description

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

number No 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

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-52 VisualDSP++ 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.

For example,

.VAR myFracts[] = {0.5r, -0.5e-4r, -0.25e-3r, 0.875r};

/* Constants are examples of legal fracts */

.VAR OutOfRangeFract = 1.5r;

/* [Error ...] Fract constant '1.5r' is out of range. Fract constants must be greater than or equal to -1 and less than 1. */

(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 Manual 1-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

4000 0000

8 0 0 0 0 0 0 0 = 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,

#define fromSomewhereElse 0.875r .SECTION data1; .VAR localOne = fromSomewhereElse + 0.005r;

// Result .88r is within the legal range

.VAR xyz = 1.5r -0.9r;

1-54 VisualDSP++ 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

Convention Description

/* comment */ A “/* */” string encloses a multiple-line comment

// comment A pair of slashes “//” begin a single-line comment

Conditional Assembly Directives

Conditional assembly directives are used for evaluation of assembly-time constants using relational expressions. The expressions may include relational and logical operations. In addition to integer arithmetic, the operands may be the C structs in assembly built-in functions SIZEOF() and OFFSETOF() that return integers.

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-55

Assembler Syntax Reference

The conditional assembly directives are:

•

.IF constant-relational-expression;

• .ELIF constant-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

Relational Operators Conditional Directive Examples

not ! .if !0;

greater than > .if ( sizeof(myStruct) > 16 );

greater than equal >= .if ( sizeof(myStruct) >= 16 );

less than < .if ( sizeof(myStruct) < 16 );

less than equal <= .if ( sizeof(myStruct) <= 16 );

equality == .if ( 8 == sizeof(myStruct) );

not equal != .if ( 8 != sizeof(myStruct) );

logical or || .if (2 !=4 ) || (5 == 5);

logical and && .if (sizeof(char) == 2 && sizeof(int) == 4);

Optionally, any number of

.ELIF and a final .ELSE directive may appear

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

reserved keywords.

1-56 VisualDSP++ 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 Manual 1-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-58 VisualDSP++ 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

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 Manual 1-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

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-60 VisualDSP++ 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

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 Manual 1-61

Assembler Syntax Reference

Assembly Code (for Blackfin processors)

.EXTERN STRUCT myStructTag _myStruct; P3.l = LO(_myStruct->NestedOne->State);

P3.h = HI(_myStruct->NestedOne->State);

Example 2: Nested Reference When Nested via a Pointer with Appropriate C Declarations

When nested via a pointer myStructTagWithPtr, which has pNestedOne, uses pointer register offset instructions.

C Code

// from C header struct Location {

char Town[16]; char State[16];

};

struct myStructTagWithPtr {

int field1; struct Location *pNestedOne;

};

Assembly Code (for Blackfin processors)

// in assembly file .EXTERN STRUCT myStructTagWithPtr _myStructWithPtr;

P1.l = LO(_myStructWithPtr->pNestedOne); P1.h = HI(_myStructWithPtr->pNestedOne); P0 = [P1 + OFFSETOF(Location,State)];

1-62 VisualDSP++ 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

Directive Description

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

Initializes ASCII strings NOTE: Blackfin processors ONLY.

Defines and initializes one-, two-, and four-byte data objects, respectively. NOTE: Blackfin processors ONLY.

Conditional assembly directive

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-63

Assembler Syntax Reference

Table 1-16. Assembler Directive Summary (Cont’d)

Directive Description

.ENDSEG

(see on page 1-117)

.EXTERN

(see on page 1-77)

.EXTERN STRUCT

(see on page 1-78)

.FILE

(see on page 1-80)

.FILE_ATTR

(see on page 1-81)

.GLOBAL

(see on page 1-82)

.IF

(see on page 1-55)

.IMPORT

(see on page 1-84)

.INC/BINARY

(see on page 1-86)

.LEFTMARGIN

(see on page 1-87)

Legacy directive. Marks the end of a section. Used with legacy directive .SEGMENT that begins a section. NOTE: SHARC processors ONLY.

Allows reference to a global symbol

Allows reference to a global symbol (struct) that was defined in another file

Overrides filename given on the command line. Used by C compiler

Creates a attribute in the generated object file.

Changes a symbol’s scope from local to global

Conditional assembly directive

Provides the assembler with the structure layout (C struct) information

Includes the content of file at the current location. NOTE: Blackfin processors ONLY

Defines the width of the left margin of a listing

.LIST

Starts listing of source lines

(see on page 1-88)

.LIST_DATA (

see on page 1-89)

.LIST_DATFILE

Starts listing of data opcodes

Starts listing of data initialization files

(see on page 1-90)

.LIST_DEFTAB

Sets the default tab width for listings

(see on page 1-91)

.LIST_LOCTAB

Sets the local tab width for listings

(see on page 1-92)

1-64 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Table 1-16. Assembler Directive Summary (Cont’d)

Directive Description

Assembler

.LIST_WRAPDATA

(see on page 1-93)

.MESSAGE

(see on page 1-94)

.NEWPAGE

(see on page 1-98)

.NOLIST

(see on page 1-88)

.NOLIST_DATA

(see on page 1-89)

.NOLIST_DATFILE

(see on page 1-90)

.NOLIST_WRAPDATA

(see on page 1-93)

.PAGELENGTH

(see on page 1-99)

.PAGEWIDTH

(see on page 1-100)

.PORT

(see on page 1-101)

.PRECISION

(see on page 1-102)

Starts wrapping opcodes that don’t fit listing column

Alters the severity of an error, warning or informational message generated by the assembler

Inserts a page break in a listing

Stops listing of source lines

Stops listing of data opcodes

Stops listing of data initialization files

Stops wrapping opcodes that do not fit listing column

Defines the length of a listing page

Defines the width of a listing page

Legacy directive. Declares a memory-mapped I/O port. NOTE: SHARC processors ONLY.

Defines the number of significant bits in a floating-point value. NOTE: SHARC processors ONLY.

.PREVIOUS

Reverts to a previously described

.SECTION

(see on page 1-103)

.PRIORITY

Allows prioritized symbol mapping in the linker

(see on page 1-104)

.REFERENCE

(see on page 1-107)

.ROUND_NEAREST

(see on page 1-108)

???. NOTE: Blackfin processors ONLY.

Specifies the Round-to-Nearest mode. NOTE: SHARC processors ONLY.

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-65

Assembler Syntax Reference

Table 1-16. Assembler Directive Summary (Cont’d)

Directive Description

.ROUND_MINUS

(see on page 1-108)

.ROUND_PLUS

(see on page 1-108)

.ROUND_ZERO

(see on page 1-108)

.SECTION

(see on page 1-111)

.SEGMENT

(see on page 1-117)

.SEPARATE_MEM_SEGMENTS

(see on page 1-117)

.SET

(see on page 1-118

.STRUCT

(see on page 1-118)

.TYPE

(see on page 1-122)

.VAR

(see on page 1-123)

Specifies the Round-to-Negative Infinity mode. NOTE: SHARC processors ONLY.

Specifies the Round-to-Positive Infinity mode. NOTE: SHARC processors ONLY.

Specifies the Round-to-Zero mode. NOTE: SHARC processors ONLY.

Marks the beginning of a section

Legacy directive. Replaced with the .SECTION directive. NOTE: SHARC processors ONLY.

Specifies two buffers that should be placed into different memory segments by the linker. NOTE: TigerSHARC processors ONLY.

Sets symbolic aliases.

Defines and initializes data objects based on C typedefs from

IMPORT C header files

Changes the default data type of a symbol; used by C compiler

Defines and initializes 32-bit data objects

.WEAK

(see on page 1-128)

Creates a weak definition or reference

Table 1-17 lists assembler directives supported only on Blackfin

processors.

1-66 VisualDSP++ 4.5 Assembler and Preprocessor Manual

Assembler

Table 1-17. VisualDSP++ 4.5 Blackfin-Only Assembler Directives

Directive Description

.BSS Equivalent to .SECTION/zero_init bsz;

Refer to “.SECTION, Declare a Memory Section” on

page 1-111 for more information.

.DATA Equivalent to .SECTION data1;

Refer to “.SECTION, Declare a Memory Section” on

page 1-111 for more information.

.GLOBL Equivalent to .GLOBAL.

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-LIST Supports four-byte data initializer lists.

.SHORT EXPRESSION-LIST Supports two-byte data initializer lists.

.TEXT Equivalent to .SECTION program;

Refer to “.SECTION, Declare a Memory Section” on

page 1-111 for more information.

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-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-

ment is 1.

Example

… .ALIGN 1; // no alignment requirement … .SECTION data1; .ALIGN 2; .VAR single;

1-68 VisualDSP++ 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

The Blackfin assembler uses .BYTE instead of .VAR.

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-69

Assembler Syntax Reference

.ALIGN_CODE, Specify an Address Alignment

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.

Example

.ALIGN_CODE 0; /* no alignment requirement */ … .ALIGN_CODE 1; /* no alignment requirement */

.SECTION program;

1-70 VisualDSP++ 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 Manual 1-71

Assembler Syntax Reference

.ASCII

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-72 VisualDSP++ 4.5 Assembler and Preprocessor Manual

.BYTE, Declare a Byte Data Variable or Buffer

Assembler

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:

.BYTE varName1[,varName2,…]; .BYTE = initExpression1, initExpression2,…; .BYTE varName1,varName2,... = initExpression1, initExpression2,…; .BYTE bufferName[] = initExpression1, initExpression2,…; .BYTE bufferName[] = “fileName"; .BYTE bufferName[length .BYTE bufferName1[length] [,bufferName2[length],…]; .BYTE bufferName[length] = initExpression1, initExpression2,…;

where

• 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 Manual 1-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-

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

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-74 VisualDSP++ 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

.BYTE4/R32 Fract_Byte4_R32[] = "fr32FormatFract.dat";

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:

.BYTE symbolString[length] = ‘initString’, 0; .BYTE symbolString [] = ’initString’, 0;

Note that the number of initialization characters defines the optional

length of a string (implicit-size initialization).

Example:

.BYTE k[13] = ‘Hello world!’, 0; .BYTE k[] = ‘Hello world!’, 0;

VisualDSP++ 4.5 Assembler and Preprocessor Manual 1-75

Assembler Syntax Reference

The trailing zero character is optional. It simulates ANSI-C string representation.

1-76 VisualDSP++ 4.5 Assembler and Preprocessor Manual

ANALOG DEVICES W4.5 Assembler Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

CONTENTS

PREFACE

PREFACE

Purpose

Intended Audience

Manual Contents

What’s New in this Manual

Technical or Customer Support

Supported Processors

Product Information

MyAnalog.com

Processor Product Information

Related Documents

Online Technical Documentation

Accessing Documentation From VisualDSP++

Accessing Documentation From Windows

Accessing Documentation From the Web

Printed Manuals

VisualDSP++ Documentation Set

Hardware Tools Manuals

Processor Manuals

Data Sheets

Notation Conventions

1 ASSEMBLER

Assembler Guide

Assembler Overview

Writing Assembly Programs

Program Content

Program Structure

Program Interfacing Requirements

Using Assembler Support for C Structs

Preprocessing a Program

Using Assembler Feature Macros

Make Dependencies

Reading a Listing File

Statistical Profiling for Assembly Functions

Assembler Syntax Reference

Assembler Keywords and Symbols

Assembler Expressions

Assembler Operators

Numeric Formats

Fractional Type Support

Comment Conventions

Conditional Assembly Directives

C Struct Support in Assembly Built-In Functions

OFFSETOF() Built-In Function

SIZEOF() Built-In Function

Struct References

Assembler Directives

.ALIGN, Specify an Address Alignment

.ALIGN_CODE, Specify an Address Alignment

.ASCII

.BYTE, Declare a Byte Data Variable or Buffer