Analog Devices assembler, preprocessor Assembler and Preprocessor Manual

W5.0

Assembler and Preprocessor Manual

Analog Devices, Inc.

One Technology Way

Norwood, Mass. 02062-9106

Revision 3.0, August 2007

Part Number:

82-000420-04 a

Copyright Information

©2007 Analog Devices, Inc., ALL RIGHTS RESERVED. This document may not be reproduced in any form without prior, express written consent from Analog Devices, Inc.

Printed in the USA.

Disclaimer

Analog Devices, Inc. reserves the right to change this product without prior notice. Information furnished by Analog Devices is believed to be accurate and reliable. However, no responsibility is assumed by Analog

Devices for its use; nor for any infringement of patents or other rights of third parties which may result from its use. No license is granted by implication or otherwise under the patent rights of Analog Devices, Inc.

Trademark and Service Mark Notice

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

Accessing Documentation From Windows ............................ xxi

Accessing Documentation From the Web ............................. xxii

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

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

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

Processor Manuals ............................................................. xxiii

VisualDSP++ 5.0 Assembler and Preprocessor Manual iii

CONTENTS

Data Sheets ....................................................................... xxiii

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

ASSEMBLER

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

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

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

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

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

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

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

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

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

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

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

LDF for TigerSHARC Processors .................................. 1-14

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

LDF for Blackfin Processors .......................................... 1-16

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

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

Preprocessing a Program ........................................................ 1-23

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

-D__VISUALDSPVERSION__ Predefined Macro (Assembler) 1-29

Make Dependencies .............................................................. 1-31

Reading a Listing File ............................................................ 1-32

iv VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

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

Assembler Syntax Reference ......................................................... 1-35

Assembler Keywords and Symbols .......................................... 1-36

Assembler Expressions ........................................................... 1-49

Assembler Operators .............................................................. 1-50

Numeric Formats .................................................................. 1-55

Fractional Type Support .................................................... 1-55

1.31 Fracts .................................................................... 1-56

1.0r Special Case ........................................................... 1-57

Fractional Arithmetic .................................................... 1-57

Mixed Type Arithmetic ................................................. 1-58

Comment Conventions ......................................................... 1-58

Conditional Assembly Directives ............................................ 1-58

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

OFFSETOF Built-In Function .......................................... 1-62

SIZEOF Built-In Function ................................................ 1-62

Struct References ................................................................... 1-63

Assembler Directives .............................................................. 1-66

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

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

.ASCII .............................................................................. 1-75

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

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

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual v

CONTENTS

vi

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

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

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

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

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

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

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

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

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

.LIST_DATFILE/.NOLIST_DATFILE, Listing Data Initialization

Files .............................................................................. 1-94

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

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

.LIST_WRAPDATA/.NOLIST_WRAPDATA .................. 1-98

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

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

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

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

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

.PORT, Legacy Directive ................................................. 1-108

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

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

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

Linker Operation ........................................................ 1-113

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

.RETAIN_NAME, Stop Linker from Eliminating Symbol 1-116

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

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

Common .SECTION Attributes ................................. 1-120

DOUBLE* Qualifiers .................................................. 1-121

TigerSHARC-Specific Qualifiers .................................. 1-122

SHARC-Specific Qualifiers .......................................... 1-123

Initialization Section Qualifiers ................................... 1-123

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

.SEPARATE_MEM_SEGMENTS ................................... 1-126

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

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

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

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

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

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

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

Assembler Command-Line Reference ......................................... 1-139

Running the Assembler ........................................................ 1-140

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

-align-branch-lines .......................................................... 1-146

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

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

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual vii

CONTENTS

viii

-char-size-8 ..................................................................... 1-148

-char-size-32 ................................................................... 1-148

-char-size-any ................................................................. 1-149

-default-branch-np ......................................................... 1-149

-default-branch-p ........................................................... 1-149

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

-double-size-32 ............................................................... 1-150

-double-size-64 ............................................................... 1-150

-double-size-any ............................................................. 1-151

-expand-symbolic-links ................................................... 1-151

-expand-windows-shortcuts ............................................. 1-151

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

-flags-compiler ................................................................ 1-151

User-Specified Defines Options ................................... 1-152

Include Options ......................................................... 1-153

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

-g ................................................................................... 1-154

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

-h[elp] ............................................................................ 1-155

-i .................................................................................... 1-156

-l filename ...................................................................... 1-157

-li filename ..................................................................... 1-157

-M ................................................................................. 1-157

-MM .............................................................................. 1-158


CONTENTS

-Mo filename .................................................................. 1-158

-Mt filename ................................................................... 1-158

-micaswarn ..................................................................... 1-159

-no-source-dependency ................................................... 1-159

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

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

-no-expand-symbolic-links .............................................. 1-160

-no-expand-windows-shortcuts ........................................ 1-160

-no-temp-data-file ........................................................... 1-160

-o filename ..................................................................... 1-161

-pp ................................................................................. 1-161

-proc processor ................................................................ 1-161

-save-temps ..................................................................... 1-162

-si-revision version .......................................................... 1-162

-sp .................................................................................. 1-163

-stallcheck ....................................................................... 1-163

-v[erbose] ....................................................................... 1-163

-version .......................................................................... 1-164

-w ................................................................................... 1-164

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

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

-Wno-info ...................................................................... 1-165

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

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual ix

CONTENTS

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

-Wwarn-error ................................................................. 1-165

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

PREPROCESSOR

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

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

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

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

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

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

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

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

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

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

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

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

-D__VISUALDSPVERSION____ Predefined Macro (Preprocessor)

2-19

Specifying Preprocessor Options ............................................ 2-20

Preprocessor Command Reference ............................................... 2-20

Preprocessor Commands and Operators ................................. 2-21

#define ............................................................................. 2-23

Variable-Length Argument Definitions .......................... 2-24

#elif ................................................................................. 2-26

x VisualDSP++ 5.0 Assembler and Preprocessor Manual

CONTENTS

#else ................................................................................. 2-27

#endif ............................................................................... 2-28

#error ............................................................................... 2-29

#if .................................................................................... 2-30

#ifdef ................................................................................ 2-31

#ifndef .............................................................................. 2-32

#include ........................................................................... 2-33

#line ................................................................................. 2-35

#pragma ........................................................................... 2-36

#undef .............................................................................. 2-37

#warning .......................................................................... 2-38

# (Argument) .................................................................... 2-39

## (Concatenate) .............................................................. 2-41

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

Preprocessor Command-Line Reference ....................................... 2-44

Running the Preprocessor ...................................................... 2-44

Preprocessor Command-Line Switches ................................... 2-45

-cstring ............................................................................. 2-47

-cs! ................................................................................... 2-48

-cs/* .................................................................................. 2-48

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

-cs{ ................................................................................... 2-49

-csall ................................................................................. 2-49

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual xi

CONTENTS

-h[elp] .............................................................................. 2-49

-i ...................................................................................... 2-50

-i ...................................................................................... 2-50

-I- .................................................................................... 2-51

-M ................................................................................... 2-52

-MM ................................................................................ 2-52

-Mo filename .................................................................... 2-52

-Mt filename .................................................................... 2-53

-o filename ....................................................................... 2-53

-stringize .......................................................................... 2-53

-tokenize-dot .................................................................... 2-53

-Uname ............................................................................ 2-54

-v[erbose] ......................................................................... 2-54

-version ............................................................................ 2-54

-w .................................................................................... 2-54

-Wnumber ....................................................................... 2-55

-warn ............................................................................... 2-55

INDEX

xii VisualDSP++ 5.0 Assembler and Preprocessor Manual

Preface

PREFACE

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

Purpose

The VisualDSP++ 5.0 Assembler and Preprocessor Manual contains information about the assembler preprocessor utilties for the following Analog

Devices, Inc. processor families—SHARC® (ADSP-21xxx) processors,

TigerSHARC® (ADSP-TSxxx) processors, and Blackfin® (ADSP-BFxxx) processors.

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

VisualDSP++ 5.0 Assembler and Preprocessor Manual xiii

Manual Contents

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.

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++ 5.0 Assembler and Preprocessor Manual documents assembler support for all currently available Analog Devices’ SHARC,

TigerSHARC and Blackfin processors listed in

“Supported Processors” .

Refer to VisualDSP++ 5.0 Product Release Bulletin for information on all new and updated VisualDSP++® 5.0 features and other release information.

xiv VisualDSP++ 5.0 Assembler and Preprocessor Manual

Preface

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 [email protected]

• E-mail processor questions to [email protected] (World wide support) [email protected] (Europe support) [email protected] (China support)

• Phone questions to 1-800-ANALOGD

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

• Send questions by mail to:

Analog Devices, Inc.

One Technology Way

P.O. Box 9106

Norwood, MA 02062-9106

USA

VisualDSP++ 5.0 Assembler and Preprocessor Manual xv

Supported Processors

Supported Processors

The following is the list of Analog Devices, Inc. processors supported in

VisualDSP++ 5.0.

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-21065L

ADSP-21262

ADSP-21363

ADSP-21367

ADSP-21375

ADSP-21060

ADSP-21160

ADSP-21266

ADSP-21364

ADSP-21368

ADSP-21061

ADSP-21161

ADSP-21267

ADSP-21365

ADSP-21369

ADSP-21062

ADSP-21261

ADSP-21362

ADSP-21366

ADSP-21371 xvi VisualDSP++ 5.0 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-BF533

ADSP-BF561

ADSP-BF536

ADSP-BF538

ADSP-BF522

ADSP-BF527

ADSP-BF544

ADSP-BF549

ADSP-BF532

ADSP-BF535

ADSP-BF534

ADSP-BF537

ADSP-BF539

ADSP-BF525

ADSP-BF542

ADSP-BF548

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 www.analog.com

. Our Web site provides information 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.

MyAnalog.com

provides access to books, application notes, data sheets, code examples, and more.

VisualDSP++ 5.0 Assembler and Preprocessor Manual xvii


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 publications, 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 [email protected] (World wide support) [email protected] (Europe support) [email protected] (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++ 5.0 Assembler and Preprocessor Manual

Preface

Related Documents

For information on product related development software, see these publications:

• VisualDSP++ Getting Started Guide

• VisualDSP++ User’s Guide

• VisualDSP++ Run-Time Library Manual for SHARC Processors

• VisualDSP++ C/C++ Compiler Manual for SHARC Processors

• VisualDSP++ C/C++ Compiler and Library Manual for

TigerSHARC Processors

• VisualDSP++ C/C++ Compiler and Library Manual for Blackfin

Processors

• VisualDSP++ Assembler and Preprocessor Manual

• VisualDSP++ Linker and Utilities Manual

• VisualDSP++ Loader Manual

• VisualDSP++ Licensing Guide

• VisualDSP++ Product Release Bulletin

• VisualDSP++ Kernel (VDK) User’s Guide

• Device Drivers and System Services Manual for Blackfin Processors

• Quick Installation Reference Card

For hardware information, refer to your processors’s hardware reference, programming reference, or data sheet. All documentation is available online. Most documentation is available in printed form.

VisualDSP++ 5.0 Assembler and Preprocessor Manual xix


Visit the Technical Library Web site to access all processor and tools manuals and data sheets: http://www.analog.com/processors/technicalSupport/technicalLibrary

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

.PDF

files of most manuals are also provided.

Each documentation file type is described as follows.

File Description

.CHM

Help system files and manuals in Help format

.HTM

or

.HTML

.PDF

Dinkum Abridged C++ library and FlexLM network license manager software documentation. Viewing and printing the

.HTML

files requires a browser, such as

Internet Explorer 6.0 (or higher).

VisualDSP++ and processor manuals in Portable Documentation Format (PDF).

Viewing and printing the

.PDF

files requires a PDF reader, such as Adobe Acrobat

Reader (5.0 or higher).

Access the online documentation from the VisualDSP++ environment,

Windows® Explorer, or the Analog Devices Web site. xx VisualDSP++ 5.0 Assembler and Preprocessor Manual

Preface

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

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.

VisualDSP++ 5.0 Assembler and Preprocessor Manual xxi


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.

Printed Manuals

For general questions regarding literature ordering, call the Literature

Center at 1-800-ANALOGD (1-800-262-5643) and follow the prompts.

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.

xxii VisualDSP++ 5.0 Assembler and Preprocessor Manual

Preface

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.

To have a data sheet faxed to you, call the Analog Devices Faxback System at 1-800-446-6212. Follow the prompts and a list of data sheet code numbers will be faxed to you. If the data sheet you want is not listed, check for it on the Web site.

Notation Conventions

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

L

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

Example

Close command

(File menu)

{this | that}

[this | that]

[this,…]

Description

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

Alternative required items in syntax descriptions appear within curly brackets and separated by vertical bars; read the example as this

or that

. One or the other is required.

Optional items in syntax descriptions appear within brackets and separated by vertical bars; read the example as an optional this or

that

.

Optional item lists in syntax descriptions appear within brackets delimited by commas and terminated with an ellipse; read the example as an optional comma-separated list of this

.

VisualDSP++ 5.0 Assembler and Preprocessor Manual xxiii

Notation Conventions

Example

.

SECTION

filename

L a

[

Description

Commands, directives, keywords, and feature names are in text with letter gothic

font.

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

Note: For correct operation, ...

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

Caution: Incorrect device operation may result if ...

Caution: Device damage may result if ...

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

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 Warning appears instead of this symbol.

xxiv VisualDSP++ 5.0 Assembler and Preprocessor Manual

Assembler

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

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

Provides reference information on the assembler’s switches and conventions

L

The code examples in this manual have been compiled using

VisualDSP++ 5.0. The examples compiled with other versions of

VisualDSP++ may result in build errors or different output although the highlighted algorithms stand and should continue to stand in future releases of VisualDSP++.

VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-1

Assembler Guide

Assembler Guide

In VisualDSP++ 5.0, 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, and header files, and produces an object file. Assembler operations depend on two types of controls: assembler directives and assembler switches.

VisualDSP++ 5.0 supports the following assembler drivers:

• easm21k.exe

(for SHARC processors)

• easmts.exe

(for TigerSHARC processors)

• easmblkfn.exe

(for Blackfin processors)

This section describes 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-20

•

“Preprocessing a Program” on page 1-23

•

“Using Assembler Feature Macros” on page 1-25

•

“Make Dependencies” on page 1-31

•

“Reading a Listing File” on page 1-32

•

“Statistical Profiling for Assembly Functions” on page 1-33

•

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

1-2 VisualDSP++ 5.0 Assembler and Preprocessor Manual

Assembler

For information about processor architecture, including the instruction set used when writing the assembly programs, see the Hardware Reference and programming manual for the appropriate processor.

Assembler Overview

The assembler processes data from assembly source (

.asm

), data (

.DAT

), and header (

.h

) files to generate object files in executable and linkable format (ELF), an industry-standard format for binary object files. The object file has a

.doj

extension.

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

Assembler switches are specified from the VisualDSP++ IDDE or from 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 Command-Line Reference” on page 1-139 .

You can also set assembler options via the Assemble page of the

VisualDSP++ Project Options dialog box. (See “Specifying Assembler

Options in VisualDSP++” on page 1-167

).

Writing Assembly Programs

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

Write assembly language programs using the VisualDSP++ editor or any editor that produces text files. Do not use a word processor that embeds special control codes in the text. Use an

.asm

extension to source file names to identify them as assembly source files.


Assembler Guide

Figure 1-1 shows a graphical overview of the assembly process. The figure shows the preprocessor processing the assembly source (

.asm

) and header

(.

H

) files.

Data initialization file

(.DAT)

Assembly source file

(.ASP)

Preprocessor

Intermediate preprocessed file (.IS)

Assembler

Object file

(.OBJ)

Listing file

(.LST)

Header file

(.H)

Figure 1-1. Assembler Input and Output Files


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 intermediate file to produce a binary object file (

.doj

) and an optional listing file (

.lst

).

Object files produced by the processor assembler may be used as input to the linker and archiver. You can archive the output of an assembly process into a library file (

.dlb

), which can then be linked with other objects into an executable. Use the linker to combine separately assembled object files and objects from library files to produce an executable file. For more information on the linker and archiver, see the VisualDSP++ 5.0 Linker

and Utilities Manual.

A binary object file (

.doj

) and an optional listing (

.lst

) file are final results of the successful assembly.

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

.IMPORT

directive

on page 1-87

.) The file shows the name, total size, and layout with offset for the members. The information appears at the end of the listing. You must specify the

-l switch (

on page 1-157 ) 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 is deleted during the assembly process.


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 programming 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-8 shows an example assembly source file.

To mark the location of an instruction, place an address label at the beginning of an instruction line or on the preceding line. End the label with a colon (

:

) before beginning the instruction. Your program can then refer to this memory location using the label instead of an address. The assembler places no restriction on the number of characters in a label.

Labels are case sensitive. The assembler treats “outer” and “Outer” as unique labels. For example (in Blackfin processors), outer: [I1] = R0;

Outer: R1 = 0X1234;

JUMP outer; // jumps back 2 instructions

Assembler Directives

Directives begin with a period (

.

) and end with a semicolon (

;

). The assembler does not differentiate between directives in lowercase or uppercase.

L

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


Assembler

For example (in Blackfin processors),

.SECTION data1;

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

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

“Assembler

Directives” on page 1-66 .

Preprocessor Commands

Preprocessor commands begin with a pound sign (

#

) and end with a carriage return. The pound sign must be the first non-white space character on the line containing the command. If the command is longer than one line, use a backslash (

\

) and a carriage return to continue the command onto the next line.

Do not put any characters between the backslash and the carriage return.

Unlike assembler directives, preprocessor commands are case sensitive and must be lowercase. For example,

#include "string.h"

#define MAXIMUM 100

For more information, see

“Writing Preprocessor Commands” on page 2-3 . For a list of the preprocessor commands, see

“Preprocessor

Command-Line Reference” on page 2-44 .

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.


Assembler Guide

1-8

Use the

.SECTION

directive to organize the code and data in assembly source files. The

.SECTION directive defines a grouping of instructions and data that occupies contiguous memory addresses in the processor. The name given in a

.SECTION

directive corresponds to an input section name in the linker description file.

Table 1-1 , Table 1-2 , and Table 1-3 show suggested input section names for data and code that 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 LDFs, refer to the VisualDSP++ Linker and Utilities Manual.

Table 1-1. Suggested Input Section Names for a SHARC LDF

.SECTION

Name

seg_pmco seg_dmda seg_pmda seg_rth

Description

A section in Program Memory that holds code

A section in Data Memory that holds data

A section in Program Memory that holds data

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

data1 data2 program

Description

A section that holds data in memory block M1

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

PM memory qualifier)

A section that holds code

Use sections in a program to group elements to meet hardware constraints.

For example, the ADSP-BF535 processor has a separate program and data memory in Level 1 memory only. Level 2 memory and external memory are not separated into instruction and data memory.


Assembler

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

.SECTION

Name

data1 program constdata

Description

A section that holds data

A section that holds code

A section that holds global data (which is declared as constant) and literal constants such as strings and array initializers

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

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

.SECTION directive and ends with the occurrence of the next

.SECTION directive or end-of-file.

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

Table 1-4. Sections in Source Programs

Section

Data Section

Variables and buffers are declared and can be initialized

SHARC

seg_dmda

Program Section

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

TigerSHARC Blackfin

data1 data2 data1 constdata program seg_rth 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 processor family. They show 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

#include

to include other files in your source code),

#ifdef

(for conditional assembly), or

#define

(to define macros).

The

SECTIONS{}

commands define the .

SECTION

placements in the sys-


Assembler Guide

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

Code File Structure 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

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

LDF for SHARC Processors

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

Looking at the LDF’s

SECTIONS{}

command, notice that the

INPUT_SECTION

commands map to the names of memory sections (such as program

, data1

, data2

, ctor

, heaptab

, and so on) used in the example assembly sample program.


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


Assembler Guide

.seg_dmda {

INPUT_SECTIONS( $OBJECTS(seg_dmda) $LIBRARIES(seg_dmda))

} > seg_dmda

.stackseg { ldf_stack_space = .; ldf_stack_length = 0x2000;

} > seg_stak

/* section placement for default heap */

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

} > seg_heap

/* section placement for additional custom heap */

.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


Assembler

Code File Structure for TigerSHARC Processors

Figure 1-3 describes assembly code file structure for TigerSHARC processors. Looking at Figure 1-3 , notice that an assembly source may contain preprocessor commands, such as

#include

(to include other files in 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.

Data Section

Assembler Directive

Data Section

Code Section

Assembler Label

Preprocessor Commands for Conditional Assembly


.SECTION data1;

.VAR buffer1 [0x100] = 'buffer .dat.';

.SECTION data2;

.VAR buffer2;

.SECTION program; start:

#ifdef XR0_SET_TO_2 xR0=0x2;;

#else xR0=0x1;;

#endif

J1 = buffer1;;

JL1 = 0;;

J2 = 1;;

LC0 = 0x100;; this loop: [J+=J2] = XRO;;

IF NLCOE, JUMP this_loop;;

Figure 1-3. Assembly Code File Structure for TigerSHARC Processors


Assembler Guide

LDF for TigerSHARC Processors

Listing 1-2 shows a sample user-defined LDF for TigerSHARC processors. Looking at the LDF’s

SECTIONS{}


INPUT_SECTION

commands map to the names of memory sections (such as program

, data1

, data2

, ctor

, heaptab

, and so on) used in the example assembly sample program.

Listing 1-2. Example Linker Description File for TigerSHARC Processors

ARCHITECTURE(ADSP-TS101)

SEARCH_DIR( $ADI_DSP\TS\lib )

$OBJECTS = $COMMAND_LINE_OBJECTS;

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

}

}

MEMORY

{

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 *

/


Assembler

{

OUTPUT($COMMAND_LINE_OUTPUT_FILE)

SECTIONS

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

{

FILL(0xb3c00000)

INPUT_SECTION_ALIGN(4)

INPUT_SECTIONS( $OBJECTS(program) )

} >M0Code data1

{

INPUT_SECTIONS( $OBJECTS(data1) )

} >M1Data data2

{

INPUT_SECTIONS( $OBJECTS(data2) )

} >M2Data

// Provide support for initialization, including C++ static

// initialization. This section builds a table of

// initialization function pointers.

ctor

{

INPUT_SECTIONS( $OBJECTS(ctor0) )




INPUT_SECTIONS( $OBJECTS(ctor) )

} >M1Data

// Table containing heap segment descriptors heaptab

{

INPUT_SECTIONS( $OBJECTS(heaptab) )

} >M1Data


Assembler Guide

// Allocate stacks for the application.

jstackseg

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

} >M1Stack kstackseg

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

} >M2Stack

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

{ ldf_defheap_base = .; ldf_defheap_size = MEMORY_SIZEOF(M1Heap);

} >M1Heap

}

}

Code File Structure for Blackfin Processors

Figure 1-4 describes the Blackfin processor’s assembly code file structure and shows how a program divides into sections that match the memory segmentation of Blackfin processors.

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

LDF for Blackfin Processors

Listing 1-3 on page 1-17 shows a sample user-defined linker description

file. Looking at the LDF’s

SECTIONS{}


INPUT_SECTION

commands map to sections program

, data1

, and constdata

.


Assembler

Data Section


Data Section


Preprocessor Commands for Conditional Assembly

Code (program) Section

Assembler Label


.SECTION constdata;

.VAR buffer1 [ 6 ] = "buffer1.dat";

.SECTION data1;

.VAR buffer2[ 0x100];

#ifdef INCLUDE_BUFFER3

.VAR buffer3[ 0x100];

#endif

.SECTION program;

.global my_function; my_function:

P0 = R0;

I0 = R1;

P1 = 19;

R0 = 0;

R1 = [P0++];

R2 = [I0++];

LSETUP (begin_loop, end_loop) LC0 = P1; begin_loop:

R1 *= R2;

R2 = [I0++]; end_loop:

R0= R0 + R1 (NS) || R1 = [P0++] || NOP;

R1 *= R2;

R0 = R0 + R1; my_function.end:

Assembler Label

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

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;


Assembler Guide

MEMORY /* Define/label system memory */

{ /* List of global Memory Segments */

MEM_PROGRAM { TYPE(RAM) START(0xF0000000) END(0xF002FFFF)

WIDTH(8) }

MEM_HEAP

WIDTH(8) }

MEM_STACK

{ TYPE(RAM) START(0xF0030000) END(0xF0037FFF)

{ TYPE(RAM) START(0xF0038000) END(0xF003DFFF)

WIDTH(8) }

MEM_SYSSTACK { TYPE(RAM) START(0xF003E000) END(0xF003FDFF)

WIDTH(8) }

MEM_ARGV

WIDTH(8) }

}

{ TYPE(RAM) START(0xF003FE00) END(0xF003FFFF)

PROCESSOR p0

{

/* The processor in the system */

OUTPUT($COMMAND_LINE_OUTPUT_FILE)

SECTIONS

{ program

{

/* List of sections for processor P0 */

// Align all code sections on 2 byte boundary


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


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


INPUT_SECTIONS(

$OBJECTS(constdata)$LIBRARIES(constdata))


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


INPUT_SECTIONS( $OBJECTS(seg_rth))

} >MEM_PROGRAM stack


Assembler

{ ldf_stack_space = .; ldf_stack_end = ldf_stack_space +

MEMORY_SIZEOF(MEM_STACK) - 4;

} >MEM_STACK sysstack

{ ldf_sysstack_space = .; ldf_sysstack_end = ldf_sysstack_space +

MEMORY_SIZEOF(MEM_SYSSTACK) - 4;

} >MEM_SYSSTACK heap

{ // Allocate a heap for the application ldf_heap_space = .; ldf_heap_end = ldf_heap_space + MEMORY_SIZEOF(MEM_HEAP)

- 1; ldf_heap_length = ldf_heap_end - ldf_heap_space;

} >MEM_HEAP argv

{ // Allocate argv space for the application ldf_argv_space = .; ldf_argv_end = ldf_argv_space + MEMORY_SIZEOF(MEM_ARGV)

- 1; ldf_argv_length = ldf_argv_end - ldf_argv_space;

} >MEM_ARGV

}

}


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++ 5.0 C/C++ Compiler and Library Manual for the appropriate target processor.

When writing a C or C++ program that interfaces with assembly, observe the same rules that the compiler follows as it produces code to run on the processor. These rules for compiled code define the compiler’s run-time environment. Complying with a run-time environment means following rules for memory usage, register usage, and variable names.

The definition of the run-time environment for the C/C++ compiler is provided in the VisualDSP++ 5.0 C/C++ Compiler and Library Manual for the appropriate target processor, which also includes a series of examples to demonstrate how to mix C/C++ and assembly code.

Using Assembler Support for C Structs

The assembler supports C typedef/struct

declarations within assembly source. These assembler data directives and built-ins provide high-level programming features with C structs in the assembler.


Assembler

.

Data Directives:

IMPORT

(see

on page 1-87

)

.

EXTERN STRUCT

(see

on page 1-81

)

.

STRUCT

(see

on page 1-128 )

C Struct in Assembly Built-Ins:

OFFSETOF(struct/typedef,field)

SIZEOF(struct/typedef)

(see

on page 1-62 )

(see

on page 1-62 )

Struct References:

struct->field

(support nests) (see “Struct References” on page 1-63 )

For more information on C struct support, refer to the “-flags-compiler”

command-line switch

on page 1-151

and to

“Reading a Listing File” on page 1-32

.

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.

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


Assembler Guide

Blackfin Example

.IMPORT "Coordinate.h";

// typedef struct Coordinate {

// int

// int

X;

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);

SHARC Example

.IMPORT "Samples.h";

// typedef struct Samples {

//

// int I1; int I2;

//

// int I3;

}Samples;


Assembler

.SECTION/DM seg_dmda;

.STRUCT Samples Sample1 ={

I1 = 0x1000,

I2 = 0x2000,

I3 = 0x3000

};

.SECTION/PM seg_pmco; doubleMe:

// The code may look confusing, but I2 can be used both

// as a register and a struct member name

B2 = Sample1;

M2 = OFFSETOF(Sample1,I2);

R0 = DM(M2,I2);

R0 = R0+R0;

DM(M2,I2) = R0;

L

For better code readability, avoid using

.STRUCT

member names that have the same spelling as assembler keywords. This may not always be possible if your application needs to use an existing set of

C header files.

Preprocessing a Program

The assembler includes a preprocessor that allows the use of C-style preprocessor commands in your assembly source files. The preprocessor automatically runs before the assembler unless you use the assembler’s

-sp

(skip preprocessor) switch.

Table 2-5 on page 2-21 lists preprocessor com-

mands 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

switch ( on page 1-164 ) to the assembler command

line or by selecting the Generate verbose output option on the Assemble page of the Project Options dialog box, accessible from the Project menu.

See

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

.


Assembler Guide

Preprocessor commands are useful for modifying assembly code. For example, you can use the

#include command to fill memory, load configuration registers, or set up processor parameters. You can use the

#define command to define constants and aliases for frequently used instruction sequences. The preprocessor replaces each occurrence of the macro reference with the corresponding value or series of instructions.

For example, the

MAXIMUM

macro in the example on page 1-7 is replaced with the number

100

during preprocessing.

For more information on the preprocessor command set, see

“Preprocessor Command Reference” on page 2-20 . For more information on

preprocessor usage, see

“-flags-pp -opt1 [,-opt2...]” on page 1-153

L

There is one important difference between the assembler preprocessor and compiler preprocessor. The assembler preprocessor treats the “

.

” character as part of an identifier. Thus,

.EXTERN

is a single identifier and will not match a preprocessor macro

EXTERN

.

This behavior can affect how macro expansion is done for some instructions.

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

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 lists the set of feature macros for SHARC processors.

Table 1-5. Feature Macros for SHARC Processors

-D_LANGUAGE_ASM=1

-D__ADSP21000__=1

-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

Always present

Always present

Present when running easm21K -proc ADSP-21020 with ADSP-21020 processors




Present when running easm21K -proc ADSP-21065L with ADSP-21065L processors






Assembler Guide

-D__ADSP21266__=1

-D__2126x__=1

-D__ADSP21267__=1

-D__2126x__=1

-D__ADSP21362__=1

-D__2136x__=1

-D__ADSP21363__=1

-D__2136x__=1

-D__ADSP21364__=1

-D__2136x__=1

-D__ADSP21365__=1

-D__2136x__=1

-D__ADSP21366__=1

-D__2136x__=1

-D__ADSP21367__=1

-D__2136x__=1

-D__ADSP21368__=1

-D__2136x__=1

-D__ADSP21369__=1

-D__2136x__=1

-D__ADSP2137x__=1

-D__2136x__=1

-D__ADSP21371__=1

-D__2136x__=1

-D__ADSP21375__=1

-D__2136x__=1

Table 1-5. Feature Macros for SHARC Processors (Cont’d)











Present when running easm21K -proc ADSP-2137x with ADSP-2137x processors




Assembler

Table 1-6 lists the set of feature macros for TigerSHARC processors.

Table 1-6. Feature Macros for TigerSHARC Processors

-D_LANGUAGE_ASM =1

-D__ADSPTS__ =1

-D__ADSPTS101__ =1

-D__ADSPTS201__ =1

-D__ADSPTS202__ =1

-D__ADSPTS203__ =1

-D__ADSPTS20x__ =1

Always present

Always present

Present when running easmts -proc ADSP-TS101 with ADSP-TS101 processor




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 lists the set of feature macros for Blackfin processors.

Table 1-7. Feature Macros for Blackfin Processors

-D_LANGUAGE_ASM=1

-D__ADSPBLACKFIN__ =1

-D__ADSPLPBLACKFIN__

=1

-D__ADSPBF522__=1

-D__ADSPBF525__=1

-D__ADSPBF527__=1

Always present

Always present

Always present for non-ADSP-BF535 processors

Present when running easmblkfn -proc ADSP-BF522 with ADSP-BF522 processor




Assembler Guide

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

-D__ADSPBF531__=1

-D__ADSP21531__=1

-D__ADSPBF532__=1

-D__ADSP21532__=1

-D__ADSPBF533__=1

-D__ADSP21533__=1

-D__ADSPBF534__=1

-D__ADSPBF535__=1

-D__ADSP21535__=1

-D__ADSPBF536__=1

-D__ADSPBF537__=1

-D__ADSPBF538__=1

-D__ADSPBF539__=1

-D__ADSPBF542__=1

-D__ADSPBF544__=1

-D__ADSPBF548__=1

-D__ADSPBF549__=1

-D__ADSPBF561__=1
















Assembler

For .

IMPORT

headers, the assembler calls the compiler driver with the appropriate processor option and the compiler sets the machine constants accordingly (and defines

-D_LANGUAGE_C=1

). This macro is present when used for C compiler calls to specify headers. It replaces

-D_LANGUAGE_ASM

.

For example, easm21k -proc adsp-21262 assembly --> cc21K -proc adsp-21262 easmts -proc -ADSP-TS101

assembly --> ccts -proc ADSP-TS101 easmblkfn -proc ADSP-BF535

assembly --> ccblkfn -proc ADSP-BF535

L

Use the

-verbose

option to verify what macro is default-defined.

Refer to Chapter 1 in the VisualDSP++ 5.0 C/C++ Compiler and

Library Manual of the appropriate target processor for more information.

-D__VISUALDSPVERSION__ Predefined Macro (Assembler)

The

-D__VISUALDSPVERSION__

predefined macro provides VisualDSP++ product version information. The macro allows a pre-processing check to be placed within code. It can be used to differentiate between VisualDSP++ releases and updates. This macro applies to all Analog Devices processors.

Syntax:

-D__VISUALDSPVERSION__=0xMMmmUUxx

Table 1-8 explains the parameters of this macro.

Table 1-8. -D__VISUALDSPVERSION__ Decoding of Hex Value

Parameter

MM mm

Description

VersionMajor. The major release number; for example, 4 in release 4.5.

VersionMinor. The minor release number; for example, 5 in release 4.5.


Assembler Guide

Table 1-8. -D__VISUALDSPVERSION__ Decoding of Hex Value

Parameter

UU xx

Description

VersionPatch. The number of the release update; for example, 6 in release 4.5, update 6.

Reserved for future use (always 00 initially)

The

0xMMmmUUxx

information is obtained from the

<install-dir>\System\VisualDSP.ini

file. The

xx

is initially set at 00.

If an unexpected problem occurs in trying to locate

VisualDSP.ini

or in extracting information from the

VisualDSP.ini

file, the

__VISUALDSPVERSION__

macro will not be encoded to the VisualDSP++ product version. In the Error Check example below, the

-D__VISUALDSPVERSION__ 0xffffffff string is displayed as part of an error message when the version information is unable to be encoded.

Code Example: Legacy

#if !defined(__VISUALDSPVERSION__)

#warning Building with VisualDSP++ 4.5 Update 5 or prior. No

__VISUALDSPVERSION__ available.

#endif

Code Example: VisualDSP++ 4.5 Update 6 or Later

#if __VISUALDSPVERSION__ >= 0x04050600

#warning Building with VisualDSP++ 4.5 Update 6 or later

#endif

Code Example: Error Check

#if __VISUALDSPVERSION__ == 0xffffffff

#error Unexpected build problems, unknown VisualDSP++ Version

#endif


Assembler

Code Examples: Assembly

#if __VISUALDSPVERSION__ == 0x05000000

//Building with VisualDSP++ 5.0

.VAR VersionBuildString[] = ‘Building with VisualDSP++ 5.0’;

#elif __VISUALDSPVERSION__ == 0x04050600

//Building with VisualDSP++ 4.5, Update 6

.VAR VersionBuildString[] = 'Building with VisualDSP++ 4.5 Update

6';

#else

//Building with unknown VisualDSP++ version

.VAR VersionBuildString[] = 'Building with unknown VisualDSP++ version?';

#endif

Make Dependencies

The assembler can generate make dependencies for a file to allow

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 identified in the

#include

commands,

.

IMPORT

directives, or buffer initializations (in .

VAR

and .

STRUCT

directives) constitute the make dependencies for an object file.

When you request make dependencies for the assembly, the assembler produces the dependencies from buffer initializations. The assembler also invokes the preprocessor to determine the make dependency from

#include

commands, and the compiler to determine the make dependencies from the

.IMPORT

headers.

For example, easmblkfn -proc ADSP-BF533 -MM main.asm

"main.doj": "/VisualDSP/Blackfin/include/defBF532.h"

"main.doj": "/VisualDSP/Blackfin/include/defBF533.h"

"main.doj": "/VisualDSP/Blackfin/include/def_LPBlackfin.h"


Assembler Guide

"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

...

In this case, defBF533.h

includes defBF532.h

, which also includes def_LPBlackfin.h

.

Reading a Listing File

A listing file (

.lst

) is an optional output text file that lists the results of the assembly process. Listing files provide the following information:

• Address – The first column contains the offset from the

.SECTION

’s base address.

• Opcode – The second column contains the hexadecimal opcode that the assembler generates for the line of assembly source.

• Line – The third column contains the line number in the assembly source file.

• Assembly Source – The fourth column contains the assembly source line from the file.

The assembler listing file provides information about the imported C data structures. It tells which imports were used within the program, followed by a more detailed section. It shows the name, total size, and layout with


Assembler

offset for the members. The information appears at the end of the listing.

You must specify the

-l

filename option (as shown

on page 1-157 ) to get a

listing file.

Statistical Profiling for Assembly Functions

Use the following steps to enable statistical profiling in assembler sources.

1. When using the VisualDSP++ IDDE, use the Assemble page of the

Project Options dialog box ( Figure 1-6 on page 1-168 ) to select and/or set assembler functional options.

2. Select the Generate debug information option.

3. Mark ending function boundaries with .end labels in the assembler source. For example:

.SECTION program;

.GLOBAL funk1; funk1:

...

RTS; funk1.end:


...

RTS; funk2.end:

If you have global functions without ending labels, the assembler provides warnings when debug information is generated.



Assembler Guide

...

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 Additional options field on the

Assembly page (refer to “WARNING ea1121: Missing End Labels” on page 1-154 for more information).

5. Choose Statistical Profiling -> New Profile or Linear Profiling ->

New Profile , as appropriate. Assembler functions automatically appear in the profiling window along with C functions. Click on the function name to bring up the source containing the function definition.


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 syntax conventions to define symbols (identifiers) and expressions, and to use different numeric and comment formats.

Software developers who write assembly programs should be familiar with:

•

“Assembler Keywords and Symbols” on page 1-36

•

“Assembler Expressions” on page 1-49

•

“Assembler Operators” on page 1-50

•

“Numeric Formats” on page 1-55

•

“Comment Conventions” on page 1-58

•

“Conditional Assembly Directives” on page 1-58

•

“C Struct Support in Assembly Built-In Functions” on page 1-62

•

“Struct References” on page 1-63

•

“Assembler Directives” on page 1-66



Assembler Keywords and Symbols

The assembler supports predefined keywords that include register and bitfield names, assembly instructions, and assembler directives. The following tables list assembler keywords for supported processors.

Although the keywords appear in uppercase, the keywords are case insensitive in the assembler’s syntax. For example, the assembler does not differentiate between

MAX

and max

.

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

Table 1-9. SHARC Processor Assembler Keywords

__ADI__

__TIME__

__DATE__ __FILE__ __LastSuffix__ __LINE__

.ALIGN

.FILE

.LEFTMARGIN

.LIST_LOCTAB

.ELIF

.FILE_ATTR

.LIST

.ELSE

.GLOBAL

.LIST_DATA

.LIST_WRAPDATA .NEWPAGE

.NOLIST_WRAPDA

TA

.PAGELENGTH

.ROUND_NEAREST .ROUND_PLUS

.STRUCT

.VAR

.PAGEWIDTH

.ROUND_ZERO

.WEAK

.ENDIF

.EXTERN

.IF

.IMPORT

.LIST_DATFILE

.LIST_DEFTAB

.NOLIST_DATA

.PRECISION

.NOLIST_DATFIL

E

.ROUND_MINUS

.PREVIOUS

.SECTION

ABS ACS ACT

ASHIFT ASTAT AV

B0 B1 B2

B5 B6

B10 B11

B7

B12

ADDRESS

B3

AND

B4

B8 B9

B13 B14


Assembler

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

BTGL

BIT

BTSTS BITREV BM

BY

CA CACHE

BSET

CALL

CJUMP CL CLIP

COS CURLCNTR

DADDR

DMA1E

DMABANK1

DOVL

DB

DMA1S

DMABANK2

DEC

DMA2E

DMABANK3

EB

EMUCLK2

ECE

EMUIDLE

EF

EMUN

EQ EX EXP

F0 F1 F2

F5 F6

F10 F11

F15 FADDR

FIX FLAGO_IN

F7

F12

FDEP

FLAG1_IN

FLOAT FLUSH

FRACTIONAL FTA

FMERG

FTB

GCC_COMPILED GE GT

I0 I1 I2

I5 I6

I10 I11

I15 IDLEI15

IMASKP INC

JUMP

I7

I12

IDLE16

IRPTL

CH CI

COMP COPYSIGN

DEF

DMA2S

DMAWAIT

DIM

DMADR

DO

ELSE

ENDEF

EXP2

F3

EMUCLK

EOS

F4

F8 F9

F13 F14

FLAG2_IN

FTC

FLAG3_IN

FUNPACK

I3 I4

I8 I9

I13 I14

IF IMASK




L0 L1 L2

L5 L6 L7

L10 L11

L15 LA

L12

LADDR

LE LADDR

L15 LA

LE

LINE

LEFTO

LN

LCE

LADDR

LEFTZ

LOAD

LOOP LR LSHIFT

M0 M1 M2

M5 M6

M10 M11

M7

M12

M15 MANT

MOD

MAX

MODE1 MODE2

MROF

MRB

MR1B MR1F

MRF MS

L3

L8

LCNTR

LCE

LT

M3

MBM

MODIFY

MR2B

MV

L4

L9

L13 L14

LCE LCNTR

LE

LCNTR

LENGTH

LOG2 LOGB

M4

M8 M9

M13 M14

MIN

MROB

MR2F

MROB

MROF

NE

NOT

OFFSETOF

P20

PC

PMBANK1

NOFO

NU

OR

NOFZ

P32 P40

PCSTK PCSTKP

PMDAE PMDAS

POVL1 PSA1E PSA1S

NOP NOPSPECIAL

PM PMADR

POP POVLO

PSA2E PSA3E

PSA3S

PX1

PSA4E PSA4S

PX2 RETAIN_NAME

R0 R1 R2

PUSH PX

R3 R4


Assembler


RF5 R6

R10 R11

R15 READ

ROT RS

SCALB SCL

SIN SIZE

SSF SSFR

STEP STKY

SUFR SV

TAG TCOUNT

TRUE

UF

TRUNC

UI

USF

USTAT2

USFR

UUF

VAL WITH

R7

R12

RECIPS

RSQRTS

SE

SIZEOF

SSI

STRUCT

SZ

TF TGL

TST TYPE

UNPACK UNTIL

USI USIR

UUFR UUIR

XOR

R8 R9

R13 R14

RFRAME

RTI

RND

RTS

SET

SQR

SSIR

STS

SF

SR

ST

SUF

TPERIOD

TRAP

UR

USTAT1

UUIR



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

Table 1-10. TigerSHARC Processor Assembler Keywords

__ADI__

__TIME__

.ALIGN

.EXTERN

.IMPORT

__DATE__

.ALIGN_CODE

.FILE

.LEFTMARGIN

__FILE__

.ELIF

.FILE_ATTR

.LIST

__LastSuffix__

.ELSE

.GLOBAL

.LIST_DATA

.LIST_DEFTAB

.NOLIST_DATFIL

E

.LIST_LOCTAB

.NOLIST_WRAPDA

TA

.LIST_WRAPDATA .MESSAGE

.NEWPAGE

.NOLIST_DATA

.PAGEWIDTH

.PREVIOUS

.NOLIST_WRAPDA

TA

.PAGELENGTH

.SEPARATE_MEM_

SEGMENTS

.SET

.STRUCT

.VAR

__LINE__

.ENDIF

.IF

.LIST_DATFILE

.NOLIST_DATA

.NOLIST_DATFIL

E

.SECTION

.WEAK

ABS ACS

BKFPT BR

BTBEN BTBLOCK

C CALL

DAB

ELSE

DEC

EMUTRAP

FCOMP FDEP

FTEST0 FTEST1

INC

LD0

LP

JC

LD1

LSHIFT

ADDRESS

BSET

BTBINV

CB

AND

BITEST

ASHIFT

BITFIFO

BTBDIS BTBELOCK

BTGL BY

CJMP CJMP_CALL

DESPREAD

EXP

FEXT

FOR

JUMP

LENGTH

LSHIFTR

D0

EXPAND

FIX

GETBITS

KC

LINES

LIBSIM_CALL

EXTD

FLOAT

IDLE

LOGB


Assembler

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

MANT MASK

NEWPAGE NOT

OFFSETOF

PASS

ONES

MAX

NOP

OR

PERMUTE PRECISION

RDS

ROTL

RECIPS

ROTR

RESET

ROUND

SCALB SDAB

SF1

SE

SNGL SIZE

SUM TMAX TRAP

VMIN VMAX XCORRS

MERGE MIN

NP

PUTBITS

RETI

RSQRTS

ROT

RTI

SECTION

SIZEOF

SFO

STRUCT

TYPEVAR UNTIL

XOR XSDAB

YDAB

JK Register Group

J0

through

J31

K0

through

K31

YSDAB

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

R0

through

R31

XYSTAT XSTAT YSTAT

XR0

through

XR31

YR0

through

YR31




Accelerator Register Group

TR0

through

TR31

THR0 THR1 THR2 THR3

EP Register Group

FLGPINST SDRCON SYSCON

FLGPIN

SYSCONCL

FLGPINCL

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

CASTAT0 CASTAT2 CASTAT4 CASTAT8 CASTAT10

CASTATALL

CCAIR0 CCAIR2 CCAIR4 CCAIR8 CCAIR10

CCAIRALL


Assembler


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

IVDBG IVHW

IVDMA0

through

IVDMA13

IVIRQ0 IVIRQ1 IVIRQ2 IVIRQ3 IVLINK0

IVLINK1 IVLINK2 IVLINK3 IVSW

IVTIMER0LP IVTIMER1HP IVTIMER1LP

LBUFRX0 LBUFRX1 LBUFRX2 LBUFRX3

LBUFTX0 LBUFTX1 LBUFTX2 LBUFTX3

IVTIMER0HP

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

LTCTL0 LTCTL1 LTCTL2 LTCTL3

LTSTAT0 LTSTAT1 LTSTAT2 LTSTAT3

LTSTATC0 LTSTATC1 LTSTATC2 LTSTATC3

MISR0 MISR1 MISR2 MISRCTL




RETI RETIB RETS RTI

OSPID

PMASKH PMASKL PRFM PRFCNT RETAIN_NAME

SERIAL_H SERIAL_L SFREG SQCTL SQCTLST

SQCTLCL SQSTAT

TESTMODES TIMER0L TIMER1L TIMER0H TIMER1H

TMRIN0L TMRIN0H TMRIN1L TMRIN1H TRCB

TRCBMASK TRCBPTR TRCBVAL

VIRPT

WP0CTL WP1CTL WP2CTL WP0STAT WP1STAT

W2H W2L

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

AEQ ALE ALT MEQ

MLT SEQ SF1

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

SF0

CBQ EQ LE LT

Conditions which may be prefixed with N

ISF0 ISF1 LC0E

FLAG0_IN FLAG1_IN FLAG2_IN

LC1E

FLAG3_IN

MLE

SLT

CB1

BM

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

Table 1-11. Blackfin Processor Assembler Keywords

.ALIGN

.BYTE

.ELSE

.FILE

.ASCII

.BYTE2

.ENDIF

.FILE_ATTR

.ASM_ASSERT

.BYTE4

.ELSE

.GLOBAL

.ASSERT

.DATA

.ENDIF

.GLOBL

.BSS

.ELIF

.EXTERN


Assembler

A0

ALIGN8

AND

ASTAT

B

BANG

BITSET

BREV

BYTEOP16M

BYTEOP3P

CALL

CO

DATA

DOZE

EMUEXCPT

FEXT

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

.IF

.LEFTMARGIN

.LIST_LOCTAB

.NEWPAGE

.PAGELENGTH

.SHORT

.WEAK

.INC/BINARY

.LIST

.INCBIN

.LIST_DATA

.IMPORT

.LIST_DATFILE

.LIST_DEFTAB

.LIST_WRAPDAT

A

.LONG

.NOLIST

.PAGEWIDTH

.NOLIST_DATA

.NOLIST_DATFILE .NOLIST_WRAPDAT

A

.PREVIOUS

.SECTION

.SET SYMBOL

.SYMBOL

.STRUCT

.TEXT

.TYPE

.VAR

A1

ALIGN16

ASHIFT

AV0

B0

BAR

BITTGL

BRF

BYTEOP1NS

BYTEPACK

CARET

CODE

DIVQ

EXCAUSE

FEXTSX

ABORT ABS

ALIGN24

ASL

AMNOP

ASR

AV1

B1

BITCLR

BITTST

AZ

B2

BITMUX

BIT_XOR_AC

BY BRT

BYTEOP16P

BYTEUNPACK BXOR

CC CLI

COLON COMMA

DEPOSIT

DIVS

EXCPT

FLUSH

DISALGNEXCPT

DOT

EXPADJ

FLUSHINV

AC

AN

ASSIGN

B3

BITPOS

BP

BYTEOP1P

BYTEOP2P

BXORSHIFT

CLIP

CSYNC

DIVSDEPOSIT

EMUCAUSE

EXTRACT

FP




FU GE GF

I0

IDLE_REQ

ISS2

L

LE

LMIN

LPAREN

LT1

M M0

MAX MIN

NEG

ONES

NO_INIT

OR

P0

P5

P1

PACK

PLUS PREFETCH

R R0

I1

IFLUSH

IU

LB0

LENGTH

LO

LSETUP

LZ

R32

RAISE

RETS

RNDH

R4

RBRACE

RETX

RNDL

ROT_L_AC

RTI

ROT_R_AC

RTN

R1_COLON0 RETAIN_NAME

S S2RND

SAA2H SAA2L

M1

MINUS

NOP

OUTC

P2

PC

I2

IH

JUMP

LB1

LINK

LOOP

LSHIFT

R1

R5

RBRACK

RND

ROL

RPAREN

RTS

SAA

SAA3H

M2

MNOP

NOT

P3

PRNT

R2

R6

RETI

RND12

ROR

RSDL

RTX

GT

HWERRCAUSE

I3

INTRP

JUMP.L

LC0

LJUMP

LOOP_BEGIN

LT

SAA1H

SAA3L

IDLE

IS

JUMP.S

LC1

LMAX

LOOP_END

LT0

M3

MUNOP

NS

P4

PERCENT

R3

R7

RETN

RND20

ROT

RTE

RUNTIME_INIT

SAA1L

SAT


Assembler


SCO

SLASH

SS

SSF_RND

SEARCH

SLEEP

SSF

SSF_TRUNC

STT_TYPE SU

T TESTSET

TST UNLINK

V VIT_MAX

W W32

X XB

ZERO_INIT

_ADI_

_TIME_

_DATE_

SHT_TYPE SIGN

SKPF SKPT

SSF_RND_HI

SSYN

SSF_TRUNC

STI

SYSCFG

TFU

UNLNK

TH

UNRAISE

WEAK

XH

_FILE_

XOR

_LastSuffix_

SIGNBITS

SP

SSF_TRUNC_HI

STRUCT

TL

UU

Z

_LINE_

Extend these sets of keywords with symbols that declare sections, variables, constants, and address labels. When defining symbols in assembly source code, follow these conventions:

• Define symbols that are unique within the file in which they are declared.

If you use a symbol in more than one file, use the

.GLOBAL

assembly directive to export the symbol from the file in which it is defined.

Then use the

.EXTERN

assembly directive to import the symbol into other files.

• Begin symbols with alphabetic characters.

Symbols can use alphabetic characters (

A—Z

and a—z

), digits (

0—9

), and the special characters “

$

” and “

_

” (dollar sign and underscore) as well as “

.

” (dot).



Symbols are case sensitive; so input_addr

and

INPUT_ADDR

define unique variables.

The dot, point, or period, “

.

” as the first character of a symbol triggers special behavior in the VisualDSP++ environment. A symbol with a “

.

” as the first character cannot have a digit as the second character. Such symbols will not appear in the symbol table accessible in the debugger. A symbol name in which the first two characters are dots will not appear even in the symbol table of the object.

The compiler and run-time libraries prepend “

_

” to avoid using symbols in the user namespace that begin with an alphabetic character.

• Do not use a reserved keyword to define a symbol.

• Match source and LDF sections’ symbols.

Ensure that

.SECTION

name symbols do not conflict with the linker’s keywords in the LDF. The linker uses sections’ name symbols to place code and data in the processor’s memory. For details, see the VisualDSP++ 5.0 Linker and Utilities Manual.

Ensure that

.SECTION

name symbols do not begin with the “

.

”

(dot).

• Terminate the definition of address label symbols with a colon (

:

).

• The reserved word list for processors includes some keywords with commonly used spellings; therefore, ensure correct syntax spelling.

Address label symbols may appear at the beginning of an instruction line or stand alone on the preceding line.


Assembler

The following disassociated lines of code demonstrate symbol usage.

.BYTE2 xoperand;

.BYTE4 input_array[10]; sub_routine_1:

.SECTION kernel;

// xoperand is a 16-bit variable

// input_array is a 32-bit wide

// data buffer with 10 elements

// sub_routine_1 is a label

// 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-55

.



Symbolic Expressions

Symbolic expressions contain symbols, whose values may not be known until link time. For example, data/8

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

Symbols in this type of expression are data variables, data buffers, and program labels. In the first three examples above, the symbol name represents the address of the symbol. The fourth example combines that meaning of a symbol with a use of the length operator (see Table 1-13 ).

Assembler Operators

Table 1-12 lists the assembler’s numeric and bitwise operators used in constant expressions and address expressions. These operators are listed in group order from highest precedence to lowest precedence. Operators with the highest precedence are evaluated first. When two operators have the same precedence, the assembler evaluates the left-most operator first.

Relational operators are supported only in relational expressions in conditional assembly, as described in

“Conditional Assembly Directives” on page 1-58 .

Table 1-12. Operator Precedence

~

-

Operator

(expression)

Usage Description

expression

in parentheses evaluates first

Ones complement

Unary minus

Designation Processors

Parentheses All

Tilde

Minus

All


Assembler

&

|

^

+

-

<<

>>

Operator

*

/

%

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


Multiply

Divide

Modulus

Addition

Subtraction

Shift left

Shift right

Bitwise AND

Bitwise inclusive OR

Bitwise exclusive OR

&&

||

Logical AND

Logical OR

Designation Processors

Asterisk

Slash

Percentage

Plus

Minus

All

All

All

All

All

TigerSHARC and

SHARC

TigerSHARC only

TigerSHARC only

The assembler also supports special operators. Table 1-13 lists and describes these operators used in constant and address expressions.

Table 1-13. Special Assembler Operators

Operator

ADDRESS

(

symbol)

BITPOS(constant)

HI(expression)

LO(expression)

LENGTH(symbol) symbol


Address of

symbol

Note: Used with SHARC and TigerSHARC assemblers only.

Bit position (Blackfin processors ONLY)

Extracts the most significant 16 bits of expression.

Extracts the least significant 16 bits of expression.

Note: Used with the Blackfin assembler ONLY where

HI/LO replaces the

ADRRESS()

operator. The expression in the

HI

and

LO

operators can be either symbolic or constant.

Length of

symbol

in number of elements (in a buffer/array)

Address pointer to symbol



The

ADDRESS

and

LENGTH

operators can be used with external symbols— apply them to symbols that are defined in other sections as

.GLOBAL symbols.

Blackfin Processor Example

The following code example demonstrates how Blackfin assembler operators are used to load the length and address information into registers.

#define n 20

...

.SECTION data1;

.VAR real_data [n];

// data section

// n=number of input sample s

.SECTION program;

P0.L = real_data;

P0.H = real_data;

P1=LENGTH(real_data);

LOOP loop1 LC0=P1;

LOOP_BEGIN loop1;

R0=[P0++];

...

LOOP_END loop1;

// code section

// buffer's length

// get next sample

Th code fragment above initializes

P0

and

P1

to the base address and length, respectively, of the real_data

buffer. The loop is executed 20 times.

The

BITPOS()

operator takes a bit constant (with one bit set) and returns the position of the bit. Therefore,

BITPOS(0x10)

would return 4 and

BITPOS(0x80)

would return 7. For example,

#define DLAB 0x80

#define EPS 0x10

R0 = DLAB | EPS (z); cc = BITSET (R0, BITPOS(DLAB));


Assembler

TigerSHARC Processor Example

The following example demonstrates how assembler operators are used to load the length and address information into registers (when setting up circular buffers in TigerSHARC processors).

.SECTION data1;

.VAR real_data[n];

...

.SECTION program;

// Data segment

// n = number of input samples

// Code segment

// Load the base address of

// the circular buffer

JB3 = real_data;;

// Load the index

J3=real_data;;

// Load the circular buffer length

JL3 = LENGTH(real_data);;

// Set loop counter 0 with buffer length

LC0 = JL3;; start:

XR0 = CB [J3 += 1];; // Read data from the circular buffer if NLC0E, jump start;;

The code fragment above initializes

JB3

and

JL3

to the base address and length, respectively, of the real_data circular buffer. The buffer length value contained in

JL3

determines when addressing wraps around the top of the buffer. For further information on circular buffers, refer to the

Hardware Reference of the target processor.



SHARC Processor Example

The following code example determines the base address and length of the real_data

circular buffer. The buffer’s length value (contained in

L5) determines when addressing wraps around to the top of the buffer (when setting up circular buffers in SHARC processors). For further information on circular buffers, refer to the Hardware Reference of the target processor.

.SECTION/DM seg_dmda;

.VAR real_data[n];

...

// data segment

// n=number of input samples

.SECTION/PM seg_pmco;

B5=real_data;

L5=length(real_data);

M6=1;

LCNTR=length(real_data)

,DO loopend UNTIL LCE;

// code segment

// buffer base address

// I5 loads automatically

// buffer’s length

// post-modify I5 by 1

// loop counter=buffer’s length

// get next sample

...

F0=DM(I5,M6); loopend:

...

L

Although the SHARC assembler accepts the source code written with the legacy

@

operator, it is recommended to use

LENGTH()

in place of

@

.


Assembler

Numeric Formats

Depending on the processor architectures, the assemblers support binary, decimal, hexadecimal, floating-point, and fractional numeric formats

(bases) within expressions and assembly instructions. Table 1-14 describes the notation conventions used by the assembler to distinguish between numeric formats.

Table 1-14. Numeric Formats

Convention

0x

number

Description

The “

0x

” prefix indicates a hexadecimal number

The “

B#

” or “b#” prefix indicates a binary number

B#

number

b#

number number.number[e {+/-} number]

Entry for floating-point number

number

No prefix and no decimal point indicates a decimal number

number

r

The “r” suffix indicates a fractional number

L

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

, the preprocessor’s

“-stringize” command-line switch ( on page 2-53

),

and the assembler’s “-flags-pp -opt1 [,-opt2...]” command-line

switch (

on page 1-153 ).

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

L

In Blackfin processors, fract 1.15 is a default. Use a

/R32

qualifier

(in

.BYTE4/R32

or

.VAR/R32

) to support 32-bit initialization for use with 1.31 fracts.

1.31 Fracts

Fracts supported by 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 floating-point format to fixed-point format uses a scale factor of 31.

For example,

.VAR/R32 myFract = 0.5r;

// Fract output for 0.5r is 0x4000 0000

// sign bit + 31 bits

// 0100 0000 0000 0000 0000 0000 0000 0000

4 0 0 0 0 0 0 0 = 0x4000 0000 =

.5r

//

.VAR/R32 myFract = -1.0r;

// Fract output for -1.0r is 0x8000 0000



Assembler

// 1000 0000 0000 0000 0000 0000 0000 0000

// 8 0 0 0 0 0 0

0000 = -1.0r

0 = 0x8000

.VAR/R32 myFract = -1.72471041E-03r;

// Fract output for -1.72471041E-03 is 0xFFC77C15


// 1111 1111 1100 0111 0111 1100 0001 0101

// F F C 7 7 C 1 5

1.0r Special Case

1.0r

is out-of-the-range fract

. Specify

0x7FFF FFFF

for the closest approximation of

1.0r

within the 1.31 representation.

Fractional Arithmetic

The assembler provides support for arithmetic expressions using operations on fractional constants, consistent with the support for other numeric types in constant expressions, as described in

“Assembler Expressions” on page 1-49

.

The internal (intermediate) representation for expression evaluation is a double floating-point value. Fract range checking is deferred until the expression is evaluated. For example,

#define fromSomewhereElse 0.875r

.SECTION data1;

.VAR localOne = fromSomewhereElse + 0.005r;

// Result .88r is within the legal range

.VAR xyz = 1.5r -0.9r;

// Result .6r is within the legal range

.VAR abc = 1.5r; // Error: 1.5r out of range



Mixed Type Arithmetic

The assembler does not support arithmetic between fracts and integers.

For example,

.SECTION data1;

.VAR myFract = 1 - 0.5r;

[Error ea1998] "fract.asm":2 User Error: Illegal mixing of types in expression.

Comment Conventions

The assemblers support C and C++ style formats for inserting comments in assembly sources. The assemblers do not support nested comments.

Table 1-15 lists and describes assembler comment conventions.

Table 1-15. Comment Conventions

Convention

/* comment */

// comment

Description

A “

/* */

” string encloses a multiple-line comment

A pair of slashes “

//

” begin a single-line comment

Conditional Assembly Directives

Conditional assembly directives are used for evaluation of assembly-time constants using relational expressions. The expressions may include relational and logical operations. In addition to integer arithmetic, the operands may be the C structs in the

SIZEOF()

and

OFFSETOF()

assembly built-in functions that return integers.

The conditional assembly directives include:

•

.IF constant-relational-expression;

•

.ELIF

constant-relational-expression;


Assembler

•

.ELSE;

•

.ENDIF;

Conditional assembly blocks begin with an

.IF

directive and end with an

.ENDIF

directive. Table 1-16 shows examples of conditional directives.

Table 1-16. Relational Operators for Conditional Assembly

>

>=

<

<=

==

!=

Operato r

!

||

&&

Purpose Conditional Directive Examples

Not

Greater than

.IF !0;

.IF (SIZEOF(myStruct) > 16 );

Greater than or equal to

.IF (SIZEOF(myStruct) >= 16 );

Less than

.IF (SIZEOF(myStruct) < 16 );

Less than or equal to

Equality

Not equal

Logical OR

Logical AND

.IF (SIZEOF(myStruct) <= 16 );

.IF ( 8 == SIZEOF(myStruct) );

.IF ( 8 != SIZEOF(myStruct) );

.IF (2 !=4 ) || (5 == 5);

.IF (SIZEOF(char) == 2 && SIZEOF(int) == 4);

Optionally, any number of

.ELIF

and .

ELSE directive pairs may appear within a air of .

IF

and

.ENDIF

directives. The conditional directives are each terminated with a semi-colon “

;

” just like all existing assembler directives. Conditional directives do not have to appear alone on a line.

These directives are in addition to the C-style

#if

,

#elif

,

#else

, and

#endif

preprocessing directives.

L

The

.IF

, .

ELSE

,

.ELIF

, and

.ENDIF

directives (in any case) are reserved keywords.



The

.IF

conditional assembly directive must be used to query about C structs in assembly using the

SIZEOF()

and/or

OFFSETOF()

built-in functions. These built-ins are evaluated at assembly time, so they cannot appear in expressions in

#if

preprocessor directives.

In addition, the

SIZEOF()

and

OFFSETOF()

built-in functions (see

“C

Struct Support in Assembly Built-In Functions” on page 1-62 ) can be

used in relational expressions. Different code sequences can be included based on the result of the expression.

For example,

SIZEOF(struct/typedef/C_base_type)

is permitted.

The assembler supports nested conditional directives. The outer conditional result propagates to the inner condition, just as it does in C preprocessing.

Assembler directives are distinct from preprocessor directives, as follows:

• The

#

directives are evaluated during preprocessing by the preprocessor. Therefore, the preprocessor

#if

directives cannot use assembler built-ins (see

“C Struct Support in Assembly Built-In

Functions” on page 1-62

).

• 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;


Assembler

If you have “

#define tryit 2

”, the code

<some code>

will assemble, and

<some more code>

will not be assembled.

• There are no parallel assembler directives for C-style directives

#define

,

#include

,

#ifdef

,

#if defined(name)

,

#ifndef

, and so on.



C Struct Support in Assembly Built-In Functions

The assemblers support built-in functions that enable you to pass information obtained from the imported C struct layouts. The assemblers currently support two built-in functions:

OFFSETOF()

and

SIZEOF()

.

OFFSETOF Built-In Function

The

OFFSETOF()

built-in function is used to calculate the offset of a specified member from the beginning of its parent data structure.

OFFSETOF(struct/typedef, memberName

) where: struct/typedef

– a struct

VAR

or a typedef

can be supplied as the first argument

memberName

– a member name within the struct

or typedef

(second argument)

L

For SHARC and TigerSHARC processors,

OFFSETOF()

units are in words. For Blackfin processors,

OFFSETOF()

units are in bytes.

SIZEOF Built-In Function

The

SIZEOF()

built-in function returns the amount of storage associated with an imported C struct or data member. It provides functionality similar to its C counterpart.

SIZEOF(struct/typedef/C_base_type); where:

The

SIZEOF()

function takes a symbolic reference as its single argument. A symbolic reference is a name followed by none or several qualifiers to members.


Assembler

The

SIZEOF()

function gives the amount of storage associated with:

• An aggregate type (structure)

• A C base type ( int

, char

, and so on)

• A member of a structure (any type)

For example (Blackfin processor code):

.IMPORT "Celebrity.h";

.EXTERN STRUCT Celebrity StNick;

L3 = SIZEOF(Celebrity);

L3 = SIZEOF(StNick);

L3 = SIZEOF(char);

L3 = SIZEOF(StNick->Town);

L3 = SIZEOF(Celebrity->Town);

// typedef

// struct var of typedef Celebrity

// C built-in type

// member of a struct var

// member of a struct typedef

L

The

SIZEOF()

built-in function returns the size in the units appropriate for its processor. For SHARC and TigerSHARC processors, units are in words. For Blackfin processors, units are in bytes.

When applied to a structure type or variable,

SIZEOF()

returns the actual size, which may include padding bytes inserted for alignment. When applied to a statically dimensioned array,

SIZEOF()

returns the size of the entire array.

Struct References

A reference to a struct VAR

provides an absolute address. For a fully qualified reference to a member, the address is offset to the correct location within the struct. The assembler syntax for struct

references is “

->

”.



1-64

For example, myStruct->Member5 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

L

Unlike struct

members in C, struct

members in the assembler are always referenced with “

->

” (not “

.

”) because “

.

” is a legal character in identifiers in assembly and is not available as a struct reference.

References within nested structures are permitted. A nested struct definition can be provided in a single reference in assembly code, and a nested struct

via a pointer type requires more than one instruction. Use the

OFF-

SETOF()

built-in to avoid hard-coded offsets that may become invalid if the struct layout changes in the future.

Following are two nested struct

examples for

.IMPORT "CHeaderFile.h".

Example 1:

Nested Reference Within the Struct Definition with

Appropriate C Declarations

C Code

struct Location { char Town[16]; char State[16];

}; struct myStructTag {


Assembler

int field1; struct Location NestedOne;

};

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)];



Assembler Directives

Directives in an assembly source file control the assembly process. Unlike assembly instructions, directives do not produce opcodes during assembly.

Use the following general syntax for assembler directives

.

directive

[/

qualifiers

|

arguments

];

Each assembler directive starts with a period (

.

) and ends with a semicolon (

;

). Some directives take qualifiers and arguments. A directive’s qualifier immediately follows the directive and is separated by a slash (

/

); arguments follow qualifiers. Assembler directives can be uppercase or lowercase; uppercase distinguishes directives from other symbols in your source code.

Table 1-17 lists all currently supported assembler directives. A description of each directive appears in the following sections. These directives were added for GNU compatibility.

Table 1-17. Assembler Directive Summary

Directive

.ALIGN

(see

on page 1-71 )

.ALIGN_CODE

(see

on page 1-73 )

.ASCII

(see

on page 1-75 )

.BSS

.BYTE

.BYTE2

.BYTE4

(see

on page 1-76 )

Description

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.

Equivalent to

.SECTION/zero_init bsz;

Refer to

“.SECTION, Declare a Memory Section” on page 1-120

for more information.


Defines and initializes one-, two-, and four-byte data objects, respectively.



Assembler

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

Directive Description

.DATA

to

Refer to




Conditional assembly directive

.ELSE

(see

on page 1-58 )

.ENDIF

(see

on page 1-58 )


.ENDSEG

(see

on page 1-126 )

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

.EXTERN

(see

on page 1-80 )

.EXTERN STRUCT

(see

on page 1-81 )

.FILE

(see

on page 1-83 )

.FILE_ATTR

(see

on page 1-84 )

Allows reference to a global symbol ( in another file

Overrides compiler filename struct

) that was defined

given on the command line. Used by C

Creates a attribute in the generated object file

Changes a symbol’s scope from local to global

.GLOBAL

(see

on page 1-85 )

.GLOBL

.IF

(see

on page 1-58 )

Equivalent to

.GLOBAL

.

Refer to

“.GLOBAL, Make a Symbol Available Globally” on page 1-85




.IMPORT

(see

on page 1-87 )

.INC/BINARY

(see

on page 1-90 )

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

Includes the content of file at the current location.




Directive

.INCBIN

Description

Equivalent to

.INC/BINARY

Refer to

“.INC/BINARY, Include Contents of a File” on page 1-90



Defines the width of the left margin of a listing

.LEFTMARGIN

(see

on page 1-91 )

.LIST/.NOLIST

(see

on page 1-92 )

.LIST_DATA

(

see on page 1-93

)

.LIST_DATFILE

(see

on page 1-94 )

.LIST_DEFTAB

(see

on page 1-95 )

.LIST_LOCTAB

(see

on page 1-97 )

.LIST_WRAPDATA

(see

on page 1-98 )

.LONG

(see

on page 1-99 )

.MESSAGE

(see

on page 1-100 )

.NEWPAGE

(see

on page 1-104 )

.NOLIST

(see

on page 1-92 )

.NOLIST_DATA

(see

on page 1-93 )

.NOLIST_DATFILE

(see

on page 1-94 )

Starts listing of source lines

Starts listing of data opcodes

Starts listing of data initialization files

Sets the default tab width for listings

Sets the local tab width for listings

Starts wrapping opcodes that don’t fit listing column

Supports four-byte data initializer lists for GNU compatibility.


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


Assembler


Directive

.NOLIST_WRAPDATA

(see

on page 1-98 )

.PAGELENGTH

(see

on page 1-105 )

.PAGEWIDTH

(see

on page 1-106 )

.PORT

(see

on page 1-108 )

.PRECISION

(see

on page 1-109 )

.PREVIOUS

(see

on page 1-111 )

.PRIORITY

(see

on page 1-112 )

.REFERENCE

(see

on page 1-115 )

Description

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.


Defines the number of significant bits in a floating-point value.


Reverts to a previously described

.SECTION

Allows prioritized symbol mapping in the linker

Provides better information in an X-REF file.

Refer to

“.REFERENCE, Provide Better Info in an X-REF

File” on page 1-115 for more information.


Stops the linker from eliminating a symbol.

.RETAIN_NAME

(see

on page 1-116 )

.ROUND_NEAREST

(see

on page 1-117 )

.ROUND_MINUS

(see

on page 1-117 )

.ROUND_PLUS

(see

on page 1-117 )

.ROUND_ZERO

(see

on page 1-117 )

.SECTION

(see

on page 1-120 )

Specifies the Round-to-Nearest mode.


Specifies the Round-to-Negative Infinity mode.


Specifies the Round-to-Positive Infinity mode.


Specifies the Round-to-Zero mode.


Marks the beginning of a section




Directive

.SEGMENT

(see

on page 1-126 )

.SEPARATE_MEM_SEGMENTS

(see

on page 1-126 )

.SET

(see

on page 1-127

.SHORT

(see

on page 1-127 )

.STRUCT

(see

on page 1-128 )

.TEXT

Description

Legacy directive. Replaced with the

.SECTION

directive.


Specifies that two buffers should be placed into different memory segments by the linker.


Sets symbolic aliases

Supports two-byte data initializer lists for GNU compatibility.


Defines and initializes data objects based on C typedefs

from

.

IMPORT

C header files

Equivalent to

.SECTION program;

Refer to




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

.TYPE

(see

on page 1-132 )

.VAR

(see

on page 1-133 )

.WEAK

(see

on page 1-138 )

Defines and initializes 32-bit data objects

Creates a weak definition or reference


Assembler

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

LDF command

(in the .

LDF

file) to force all the following input sections to the specified alignment. Refer to the VisualDSP++ 5.0 Linker and Utilities Manual for more information on section alignment.

Syntax:

.ALIGN expression

; where

expression

– evaluates to an integer. It specifies an alignment 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.

The linker stops allocating padding for symbols aligned by 16 or more.

L

In the absence of the

.ALIGN

directive, the default address alignment is 1.

Example

...

.ALIGN 1;

...

.SECTION data1;

// no alignment requirement



.ALIGN 2;

.VAR single;

/* aligns the data item on the word boundary, at the location with the address value that can be evenly divided by 2 */

.ALIGN 4;

.VAR samples1[100]=”data1.dat”;

/* aligns the first data item on the doubleword boundary, at the location with the address value that can be evenly divided by 4; advances other data items consecutively */

L

The Blackfin assembler uses

.BYTE

instead of

.VAR

.


Assembler

.ALIGN_CODE, Specify an Address Alignment

L

Used with TigerSHARC processors ONLY.

The

.ALIGN_CODE

directive forces the address alignment of an instruction within the

.SECTION

in which it is used. 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++ 5.0 Linker and Utilities

Manual for more information on section alignment.

Syntax:

.ALIGN_CODE expression; where

expression

– evaluates to an integer. It specifies an alignment requirement; its value must be a power of 2. In TigerSHARC processors, the

expression

value is usually 4. When aligning a data item or instruction, the assembler adjusts the address of the current location counter to the next address that is divisible by the value of the

expression

. The expression set to 0 or 1 signifies no address alignment requirement.

L

In the absence of the

.ALIGN_CODE

directive, the default address alignment is 1.

Example

.ALIGN_CODE 0;

...

.ALIGN_CODE 1;

...

.SECTION program;

.ALIGN_CODE 4;

/* no alignment requirement */

/* no alignment requirement */



JUMP LABEL;;

/* Jump instruction aligned to four word boundary.

If necessary, padding will be done with NOPs */


Assembler

.ASCII

L

Used with Blackfin processors ONLY.

The

.ASCII

directive initializes a data location with one or more characters from a double-quoted ASCII string. This is equivalent to the

.BYTE

directive. Note that the syntax differs from the

.BYTE

directive as follows:

• There is no “=” sign

• The string is enclosed in double-quotes, not single quotes

Syntax:

.ASCII “string” ;

Example:

.SECTION data1;

ASCII_String:

.TYPE ASCII_String,STT_OBJECT;

.ASCII "ABCD";

.ASCII_String.end:

Byte_String:

.TYPE Byte_String,STT_OBJECT;

.Byte = ‘ABCD’;

.Byte_String.end:



.BYTE, Declare a Byte Data Variable or Buffer

L


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

= initExpression

,

varName2 = initExpression2,…

.BYTE bufferName[] = initExpression1, initExpression2,…;

.BYTE bufferName[] = “fileName";

.BYTE bufferName[length ] = ” fileName“;

.BYTE bufferName[length] = initExpression1, initExpression2,…; where

varName

– user-defined symbols that name variables

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 quote (

“ “

) characters. Note that when reading in a data file, the assembler reads in whitespace-separated lists of decimal digits or hex strings.


Assembler

If the file name is not found in the current directory, the assembler looks in the directories in the processor include

path. You may use the

-I

switch (see on page 1-156 ) to add a directory to the processor

include path.

Initializing from files is useful for loading buffers with data, such as filter coefficients or FFT phase rotation factors that are generated by other programs. The assembler determines how the values are stored in memory when it reads the data files.

Ellipsis (…) – represents a comma-delimited list of parameters.

initExpressions

parameters – sets initial values for variables and buffer elements

L

The optional

[length]

parameter defines the length of the associated buffer in words. The number of initialization elements defines

length

of an implicit-size buffer. The brackets

[ ]

that enclose the optional [

length

] are required. For more information, see the following

.BYTE

examples.

In addition, use a

/R32

qualifier (

.BYTE4/R32

) to support 32-bit initialization for use with 1.31 fracts (see

on page 1-55

).

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;

// 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-133

.

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 in which 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).


Assembler

Example:

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

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

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



.EXTERN, Refer to a Globally Available Symbol

The

.EXTERN

directive allows a code module to reference global data structures, symbols, and so on that are declared as

.GLOBAL

in other files. For additional information, see the

.GLOBAL

directive

on page 1-85

.

Syntax:

.EXTERN

symbolName1

[,

symbolName2, …]; where

symbolName

– the name of a global symbol to import. A single

.EXTERN

directive can reference any number of symbols on one line, separated by commas.

Example:

.EXTERN coeffs;

// This code declares an external symbol to reference

// the global symbol “coeffs” declared in the example

// code in the .GLOBAL directive description.


Assembler

.EXTERN STRUCT, Refer to a Struct Defined Elsewhere

The

.EXTERN STRUCT

directive allows a code module to reference a struct defined in another file. Code in the assembly file can then reference the data members by name, just as if they were declared locally.

Syntax:

.EXTERN STRUCT

typedef

structvarName ; where

typedef

– the type definition for a struct VAR

structvarName

– a struct VAR name

The

.EXTERN STRUCT

directive specifies a struct symbol name that was declared in another file. The naming conventions are the same for structs as for variables and arrays:

• If a struct was declared in a C file, refer to it with a leading _.

• If a struct was declared in an

.asm

file, use the name “as is”, no leading underscore (

_

) is necessary.

The

.EXTERN STRUCT

directive optionally accepts a list, such as:

.EXTERN STRUCT

typedef

structvarName [,STRUCT typedef

structvar-

Name ...]

The key to the assembler knowing the layout is the

.IMPORT

directive and the

.EXTERN STRUCT

directive associating the

typedef

with the struct VAR.

To reference a data structure that was declared in another file, use the

.IMPORT

directive with the .

EXTERN

directive. This mechanism can be used for structures defined in assembly source files as well as in C files.



The

.EXTERN

directive supports variables in the assembler. If the program references struct members,

.EXTERN STRUCT

must be used because the assembler must consult the struct layout to calculate the offset of the struct members. If the program does not reference struct members, you can use

.EXTERN

for struct VARs.

Example (SHARC code):

.IMPORT "MyCelebrities.h";

// 'Celebrity' is the typedef for struct var 'StNick'

// .EXTERN means that '_StNick' is referenced within this

// file, but not locally defined. This example assumes StNick

// was declared in a C file and it must be referenced with

// a leading underscore.

.EXTERN STRUCT Celebrity _StNick;

// “isSeniorCitizen” is one of the members of the 'Celebrity'

// type

P3.L = LO( _StNick->isSeniorCitizen);

P3.H = HI(_StNick->isSeniorCitizen);


Assembler

.FILE, Override the Name of a Source File

The

.FILE

directive overrides the name of the source file. This directive may appear in the C/C++ compiler-generated assembly source file (

.s

).

The

.FILE

directive is used to ensure that the debugger has the correct file name for the source file that had generated the object file.

Syntax:

.FILE “filename.ext”; where

filename

– the name of the source file to associate with the object file.

The argument is enclosed in double quotes.



.FILE_ATTR, Create an Attribute in the Object File

The

.FILE_ATTR

directive instructs the assembler to place an attribute in the object file which can be referenced in the LDF when linking. See the

VisualDSP++ 5.0 Linker and Utilities Manual for more information.

Syntax:

.FILE_ATTR

attrName1 [= attrVal1] [ , attrName2 [= attrVal2] ]

where

attrName

– the name of the attribute. Attribute names must follow the same rules for naming symbols.

attrVal

– sets the attribute to this value. If omitted, “1” is used. The value must be double-quoted unless it follows the rules for naming symbols (as described in


).

Examples:

.FILE_ATTR at1;

.FILE_ATTR at10=a123;

.FILE_ATTR at101=a123, at102,at103="999";


Assembler

.GLOBAL, Make a Symbol Available Globally

The

.GLOBAL

directive changes the scope of a symbol from local to global, making the symbol available for reference in object files that are linked to the current one.

By default, a symbol has local binding, meaning the linker can resolve references to it only from the local file (that is, the same file in which it is defined). It is visible only in the file in which it is declared. Local symbols in different files can have the same name, and the linker considers them to be independent entities. Global symbols are visible from other files; all references from other files to an external symbol by the same name will resolve to the same address and value, corresponding to the single global definition of the symbol.

You change the default scope with the

.GLOBAL

directive. Once the symbol is declared global, other files may refer to it with

.EXTERN

. For more information, refer to the

.EXTERN

directive on page 1-80

. Note that .

GLOBAL

(or

.

WEAK

) scope is required for symbols that appear in

RESOLVE

commands in the LDF.

Syntax:

.GLOBAL symbolName1[, symbolName2,…]; where

symbolName

– the name of a global symbol. A single

.GLOBAL

directive may define the global scope of any number of symbols on one line, separated by commas.

Example (SHARC and TigerSHARC code):

.VAR coeffs[10];

.VAR taps=100;

// declares a buffer

// declares a variable



.GLOBAL coeffs, taps; // makes the buffer and the variable

// visible to other files

Example (Blackfin code):

.BYTE coeffs[10];

.BYTE4 taps=100;

.GLOBAL coeffs, taps;

// declares a buffer

// declares a variable

// makes the buffer and the variable

// visible to other files


Assembler

.IMPORT, Provide Structure Layout Information

The

.IMPORT

directive makes struct layouts visible inside an assembler program. The

.IMPORT

directive provides the assembler with the following structure layout information:

• The names of typedefs

and structs

available

• The name of each data member

• The sequence and offset of the data members

• Information as provided by the C compiler for the size of C base types (alternatively, for the

SIZEOF()

C base types).

Syntax:

.IMPORT “headerfilename1” [ , “headerfilename2”

,

…]; where

headerfilename

– one or more comma-separated C header files enclosed in double quotes.

L

The system processes each

.IMPORT

directive and each file specified in an

.IMPORT

directive separately. Therefore all type information must be available within the context for the individual file. If headerfile1.h

defines a type referenced in headerfile2.h

, an attempt to import the second file into assembly will fail.

One solution is to have the assembler call the compiler once for the set of import statements. The compiler then has all the information it needs when processing the second header file.

In other words, create a third file to be imported in place of headerfile2.h

.



This file would simply consist of these lines:

#include “headerfile1.h”

#include “headerfile2.h”

The

.IMPORT

directive does not allocate space for a variable of this type.

Allocating space requires the

.STRUCT

directive (see

on page 1-128 ).

The assembler takes advantage of knowing the struct layouts. The assembly programmer may reference struct data members by name in assembler source, as one would do in C. The assembler calculates the offsets within the structure based on the size and sequence of the data members.

If the structure layout changes, the assembly code need not change. It just needs to get the new layout from the header file, via the compiler. Make dependencies track the

.IMPORT

header files and know when a rebuild is needed. Use the

-flags-compiler

assembler switch (

on page 1-151 ) to

pass options to the C compiler for

.IMPORT

header file compilations.

An

.IMPORT

directive with one or more

.EXTERN

directives allows code in the module to refer to a struct variable that was declared and initialized elsewhere. The C struct can be declared in C-compiled code or another assembly file.

The

.IMPORT

directive with one or more .

STRUCT

directives declares and initializes variables of that structure type within the assembler section in which it appears.

For more information, refer to the

.EXTERN

directive

on page 1-80

and the

.STRUCT

directive

on page 1-128 .


Assembler

Example:

.IMPORT "CHeaderFile.h";

.IMPORT "ACME_IIir.h","ACME_IFir.h";

.SECTION program;

// ... code that uses CHeaderFile, ACME_IIir, and

// ACME_IFir C structs



.INC/BINARY, Include Contents of a File

The

.INC/BINARY

directive includes the content of file at the current location. You can control the search paths used via the

-i

command-line

switch ( on page 1-156 ).

Syntax:

.INC/BINARY [ symbol = ] "filename" [,skip [,count]] ;

.INC/BINARY [ symbol[] = ] "filename" [,skip [,count]] ; where

symbol

– the name of a symbol to associate with the data being included from the file

filename

– the name of the file to include. The argument is enclosed in double quotes.

The

skip

argument skips a number of bytes from the start of the file.

The

count

argument indicates the maximum number of bytes to read.

Example:

.SECTION data1;

.VAR jim;

.INC/BINARY sym[] = "bert",10,6;

.VAR fred;

.INC/BINARY Image1[] = "photos/Picture1.jpg";


Assembler

.LEFTMARGIN, Set the Margin Width of a Listing File

The

.LEFTMARGIN

directive sets the margin width of a listing page. It specifies the number of empty spaces at the left margin of the listing file

(

.lst

), which the assembler produces when you use the

-l

switch. In the absence of the

.LEFTMARGIN

directive, the assembler leaves no empty spaces for the left margin.

The assembler compares the .

LEFTMARGIN

and .

PAGEWIDTH

values against one another. If the specified values do not allow enough room for a properly formatted listing page, the assembler issues a warning and adjusts the directive that was specified last to allow an acceptable line width.

Syntax:

.LEFTMARGIN

expression;

where

expression

– evaluates to an integer from 0 to 100. Default is 0. Therefore, the minimum left margin value is 0 and maximum left margin value is 100. To change the default setting for the entire listing, place the

.LEFTMARGIN directive at the beginning of your assembly source file.

Example:

.LEFTMARGIN 9; /* the listing line begins at column 10 */

L

You can set the margin width only once per source file. If the assembler encounters multiple occurrences of the

.LEFTMARGIN

directive, it ignores all of them except the last directive.



.LIST/.NOLIST, Listing Source Lines and Opcodes

The

.LIST/.NOLIST

directives (on by default) turn on and off the listing of source lines and opcodes.

If

.NOLIST

is in effect, no lines in the current source (or any nested source) are listed until a

.LIST

directive is encountered in the same source, at the same nesting level. The

.NOLIST

directive operates on the next source line, so that the line containing a

.NOLIST

appears in the listing and accounts for the missing lines.

The

.LIST/.NOLIST

directives do not take any qualifiers or arguments.

Syntax:

.LIST;

.NOLIST;

These directives can appear multiple times anywhere in a source file, and their effect depends on their location in the source file.


Assembler

.LIST_DATA/.NOLIST_DATA, Listing Data Opcodes

The

.LIST_DATA/.NOLIST_DATA

directives (off by default) turn the listing of data opcodes on and off. When

.NOLIST_DATA

is in effect, opcodes that correspond to variable declarations do not apear in the opcode column.

Nested source files inherit the current setting of this directive pair, but a change to the setting made in a nested source file will not affect the parent source file.

The

.LIST_DATA/.NOLIST_DATA


Syntax:

.LIST_DATA;

.NOLIST_DATA;




.LIST_DATFILE/.NOLIST_DATFILE, Listing Data Initialization Files

The

.LIST_DATFILE/.NOLIST_DATFILE

directives (off by default) turn the listing of data initialization files on and off. Nested source files inherit the current setting of this directive pair, but a change to the setting made in a nested source file will not affect the parent source file.

The

.LIST_DATFILE/.NOLIST_DATFILE


Syntax:

.LIST_DATFILE;

.NOLIST_DATFILE;

These directives can appear multiple times anywhere in a source file, and their effect depends on their location in the source file. They are used in assembly source files, but not in data initialization files.


Assembler

.LIST_DEFTAB, Set the Default Tab Width for Listings

Tab characters in source files are expanded to blanks in listing files under the control of two internal assembler parameters that set the tab expansion width. The default tab width is normally in control, but it can be overridden if the local tab width is explicitly set with a directive.

The

.LIST_DEFTAB

directive sets the default tab width, and the

.

LIST_LOCTAB

directive sets the local tab width (see

on page 1-97 ).

Both the default tab width and the local tab width can be changed any number of times via the

.LIST_DEFTAB

and

.LIST_LOCTAB

directives. The default tab width is inherited by nested source files, but the local tab width only affects the current source file.

Syntax:

.LIST_DEFTAB expression; where

expression

– evaluates to an integer greater than or equal to 0.

In the absence of a .

LIST_DEFTAB

directive, the default tab width defaults to 4. A value of 0 sets the default tab width.

Example:

// Tabs here are expanded to the default of 4 columns

.LIST_DEFTAB 8;

// Tabs here are expanded to 8 columns

.LIST_LOCTAB 2;

// Tabs here are expanded to 2 columns

// But tabs in "include_1.h" will be expanded to 8 columns

#include "include_1.h"

.LIST_DEFTAB 4;



// Tabs here are still expanded to 2 columns

// But tabs in "include_2.h" will be expanded to 4 columns

#include "include_2.h"


Assembler

.LIST_LOCTAB, Set the Local Tab Width for Listings

Tab characters in source files are expanded to blanks in listing files under the control of two internal assembler parameters that set the tab expansion width. The default tab width is normally in control, but it can be overridden if the local tab width is explicitly set with a directive.

The

.LIST_LOCTAB

directive sets the local tab width, and the .

LIST_DEFTAB directive sets the default tab width (see

on page 1-95 ).

Both the default tab width and the local tab width can be changed any number of times via the .

LIST_DEFTAB

and

.LIST_LOCTAB

directives. The default tab width is inherited by nested source files, but the local tab width only affects the current source file.

Syntax:

.LIST_LOCTAB expression; where

expression

– evaluates to an integer greater than or equal to 0.

A value of 0 sets the local tab width to the current setting of the default tab width.

In the absence of a .

LIST_LOCTAB

directive, the local tab width defaults to the current setting for the default tab width.

Example: See the .

LIST_DEFTAB

example

on page 1-95

.



.LIST_WRAPDATA/.NOLIST_WRAPDATA

The

.LIST_WRAPDATA/.NOLIST_WRAPDATA

directives control the listing of opcodes that are too big to fit in the opcode column. By default, the

.NOLIST_WRAPDATA

directive is in effect.

This directive pair applies to any opcode that does not fit, but in practice, such a value almost always is the data (alignment directives can also result in large opcodes).

• If

.LIST_WRAPDATA

is in effect, the opcode value is wrapped so that it fits in the opcode column (resulting in multiple listing lines).

• If

.NOLIST_WRAPDATA

is in effect, the printout is what fits in the opcode column.

Nested source files inherit the current setting of this directive pair, but a change to the setting made in a nested source file does not affect the parent source file.

The

.LIST_WRAPDATA/.NOLIST_WRAPDATA


Syntax:

.LIST_WRAPDATA;

.NOLIST_WRAPDATA;



Assembler

.LONG, Defines and initializes 4-byte data objects

L


The

.LONG

directive declares and optionally initializes four-byte data objects. It is it is effectively equivalent to

.BYTE4 initExpression1,

initExpression2,…

. For more information, see

“.BYTE, Declare a Byte

Data Variable or Buffer” on page 1-76

.

Syntax:

When declaring and/or initializing memory variables or buffer elements, use the following format. Note that the terminating semicolon is optional.

.LONG initExpression1, initExpression2,…[;]

.LONG constExpression1, constExpression2,…[;] where

initExpressions

parameters – contain one or more comma-separated

“symbol=value” expressions

constExpressions

parameters – contain a comma-separated list of constant values


.LONG

directives:

// Define an initialized variable

.LONG buf1=0x1234;

// Define two initialized variables

.LONG 0x1234, 0x5678, ...;

// Declare three 8 byte areas of memory, initialized to

3, 4 and 5 respectively

.LONG 0x0003, 0x0004, 0x0005;



.MESSAGE, Alter the Severity of an Assembler Message

The

.MESSAGE

directive can be used to alter the severity of an error, warning, or informational message generated by the assembler for all or part of an assembly source.

Syntax:

.MESSAGE/qualifier

warnid1 [,warnid2,…]

;



UNTIL sym;



FOR

n

LINES;

.MESSAGE/DEFAULT/qualifier


; where

warnid1[,warnid2,…]

is a list of one or more message identification numbers.

A qualifier can be:

•

ERROR

– change messages to errors

•

WARN

– change messages to warnings

•

INFO

– change messages to informational messages

•

SUPPRESS

– do not output the messages

•

RESTORE_CL

– change the severity of the messages back to the default values they had at the beginning of the source file, after the command line arguments were processed, but before any

DEFAULT directives have been processed.

•

RESTORE

– change the severity of the messages back to the default values they had at the beginning of the source file, after the command line arguments were processed, and after any

DEFAULT directives have been processed.

•

POP

– change the severity of the messages back to what they were


Assembler

prior to the previous

.MESSAGE

directive.

The

RESTORE

,

RESTORE_CL

, and

POP

qualifiers cannot be used with the

UNTIL

,

FOR

, or

DEFAULT

forms of the

.MESSAGE

directive.

The

DEFAULT

qualifier cannot be used with the

UNTIL

or

FOR

forms of the

.MESSAGE

directive.

The simple form of the

.MESSAGE

directive changes the severity of messages until another

.MESSAGE

directive is seen. It can be placed anywhere in a source file. Messages that could not be associated with a source line can be reported with line number 0. These cannot be altered in severity by a

.MESSAGE

directive. This should be done by using the

-Werror

,

-Wwarn

,

-Winfo

, or

-Wsuppress

assembler switches. (See

“Assembler Command-Line Switch Descriptions” on page 1-142

.)

Example:

.MESSAGE/ERROR 1049;

.SECTION program;

.VAR two[2]=1;

.MESSAGE/SUPPRESS 1049;

.VAR three[3]=1,2;

.MESSAGE/WARN 1049;

.VAR four[4]=1,2,3;

// generates an error

// generates no message

// generates a warning



The temporary forms of the

.MESSAGE

directive (

UNTIL

and

FOR

) changes the severity of messages until the specified label (or for the specified number of source lines). The temporary forms of the

.MESSAGE

directive must start and end within a single

.SECTION

directive.

Example (for TigerSHARC Processors):

.SECTION program;

.VAR one=1.0r;

.MESSAGE/ERROR 1177 UNTIL sym;

.VAR two=1.0r; sym:

.VAR three=1.0r;

.MESSAGE/ERROR 1177 FOR 3 LINES;

.VAR apple;

.VAR four=1.0r;

.VAR orange;

.VAR five=1.0r;






The

POP

qualifier changes the severity of the messages back to previous severities.


.MESSAGE/INFO 3012;

.SECTION program;

RETI;;


RETI;;

.MESSAGE/INFO 3012;

RETI;;

.MESSAGE/POP 3012;

RETI;;

.MESSAGE/POP 3012;

// generates an informational



// generates an error - 2nd directive


Assembler

RETI;;

.MESSAGE/POP 3012;

RETI;;

// generates an informational - 1st directive

// generates a warning - the default for this message

The

DEFAULT

qualifier is used to redefine the default severity for messages.

It can be placed anywhere in a source file. It only takes affect when the message severity has not been changed by a

.MESSAGE

directive.


.MESSAGE/DEFAULT/ERROR 1177;

.MESSAGE/DEFAULT/INFO 1177;

.SECTION program;

.VAR one=1.0r;


.VAR two=1.0r;

.MESSAGE/RESTORE 1177;

.VAR three=1.0r;

.MESSAGE/RESTORE_CL 1177;

.VAR four=1.0r;





L

The

-Werror

,

-Wwarn

, -

Winfo

, or

-Wsuppress

assembler switches have the same affect as the

DEFAULT

form of

.MESSAGE

. (See

“Assembler Command-Line Switch Descriptions” on page 1-142 .)

Many error messages cannot be altered in severity as the assembler behavior is unknown.

Include files inherit any severity changes from the files which

#include them.

.MESSAGE

directives in include files do not control the severity of messages generated after returning to the source file which included them.

A

.MESSAGE/DEFAULT

directive in an include file controls the severity of messages generated after returning to the source file which included them.



.NEWPAGE, Insert a Page Break in a Listing File

The

.NEWPAGE

directive inserts a page break in the printed listing file

(.

LST

), which the assembler produces when you use the

-l

switch

(

on page 1-157

). The assembler inserts a page break at the location of the

.NEWPAGE

directive.

The

.NEWPAGE

directive does not take any qualifiers or arguments.

Syntax:

.NEWPAGE

;

This directive may appear anywhere in your source file. In the absence of the

.NEWPAGE

directive, the assembler generates no page breaks in the file.


Assembler

.PAGELENGTH, Set the Page Length of a Listing File

The

.PAGELENGTH

directive controls the page length of the listing file produced by the assembler when you use the

-l

switch (

on page 1-157

)

Syntax:

.PAGELENGTH

expression

; where

expression –

evaluates to an integer 0 or greater.

It specifies the number of text lines per printed page. The default page length is 0, which means the listing has no page breaks.

To format the entire listing, place the

.PAGELENGTH

directive at the beginning of your assembly source file. If a page length value greater than 0 is too small to allow a properly formatted listing page, the assembler issues a warning and uses its internal minimum page length (approximately 10 lines).

Example:

.PAGELENGTH 50; // starts a new page after printing 50 lines

L

You can set the page length only once per source file. If the assembler encounters multiple occurrences of the directive, it ignores all except the last directive.



.PAGEWIDTH, Set the Page Width of a Listing File

The

.PAGEWIDTH

directive sets the page width of the listing file produced by the assembler when you use the

-l

switch.

Syntax:

.PAGEWIDTH

expression; where

expression

– evaluates to an integer

Depending on setting of the .

LEFTMARGIN

directive, this integer should be at least equal to:

LEFTMARGIN

value plus 46 (for Blackfin processors)

LEFTMARGIN

value plus 49 (for TigerSHARC processors)

LEFTMARGIN

value plus about 66 (for SHARC processors)

You cannot set this integer to less than 46, 49, or 66, respectively. There is no upper limit. If

LEFTMARGIN

= 0 and the

.PAGEWIDTH

value is not specified, the actual page width is set to any number over 46, 49, or 66, respectively.

To change the number of characters per line in the entire listing, place the

.PAGEWIDTH

directive at the beginning of the assembly source file.


Assembler

Example:

.PAGEWIDTH 72; // starts a new line after 72

characters

// are printed on one line, assuming

// the .LEFTMARGIN setting is 0.

L

You can set the page width only once per source file. If the assembler encounters multiple occurrences of the directive, it ignores all of them except the last directive.



.PORT, Legacy Directive

L

Used with SHARC processors ONLY.

The

.PORT

legacy directive assigns port name symbols to I/O ports. Port name symbols are global symbols; they correspond to memory-mapped

I/O ports defined in the LDF.

The

.PORT

directive uses the following syntax:

.PORT portName; where:

portName

– a globally available port symbol

Example:

.PORT p1;

.PORT p2;

// declares I/O port P1

// declares I/O port P2

To declare a port using the SHARC assembler syntax, use the

.VAR directive (for port-identifying symbols) and the linker description file (for corresponding I/O sections). The linker resolves port symbols in the .

LDF file.

For more information on the linker description file, see the VisualDSP++

5.0 Linker and Utilities Manual.


Assembler

.PRECISION, Select Floating-Point Precision

L


The

.PRECISION

directive controls how the assembler interprets floating-point numeric values in constant declarations and variable initializations. To configure the floating-point precision of the target processor system, you must set up control registers of the chip using instructions specific to the processor core.

Use one of the following options:

.PRECISION [=] 32;

.PRECISION [=] 40; where:

The precision of 32 or 40 (default) specifies the number of significant bits for floating-point data. The equal sign (

=

) following the

.PRECISION keyword is optional.

Note that the

.PRECISION

directive applies only to floating-point data.

Precision of fixed-point data is determined by the number of digits specified. The

.PRECISION

directive applies to all floating-point expressions in the file that follow it up to the next

.PRECISION

directive.



Example:

.PRECISION=32; /* Selects standard IEEE 32-bit single-precision format; */

.PRECISION 40; /* Selects standard IEEE 40-bit format with extended mantissa. This is the default setting. */

L

The

.ROUND_

directives (

on page 1-117 ) specify how the assembler converts a value of many significant bits to fit into the selected

precision.


Assembler

.PREVIOUS, Revert to the Previously Defined Section

The

.PREVIOUS

directive instructs the assembler to set the current section in memory to the section described immediately before the current one.

The

.PREVIOUS

directive operates on a stack.

Syntax:

.PREVIOUS;

The following examples provide valid and invalid cases of the use of the consecutive .

PREVIOUS

directives.

Example of Invalid Directive Use

.SECTION data1;

.SECTION code;

.PREVIOUS;

.PREVIOUS;

// data

// instructions

// previous section ends, back to data1

// no previous section to set to

Example of Valid Directive Use

#define MACRO1

.SECTION data2;

.VAR vd = 4;

.PREVIOUS;

.SECTION data1;

\

\

\

.VAR va = 1;

.SECTION program;

.VAR vb = 2;

MACRO1

.PREVIOUS;

.VAR vc = 3;

// data

// instructions

// invoke macro



evaluates as:

.SECTION data1;

.VAR va = 1;

.SECTION program;

.VAR vb = 2;

// Start MACRO1

.SECTION data2;

.VAR vd = 4;

.PREVIOUS;

// End MACRO1

.PREVIOUS;

.VAR vc = 3;

// data

// instructions

// end data2, section program

// end program, start data1

.PRIORITY, Allow Prioritized Symbol Mapping in Linker

The

.PRIORITY

directive allows prioritized symbol mapping in the linker.

The directive can be specified in three ways:

• For a symbol defined in the same file as the directive

• For a globally defined symbol

• For a local symbol in a different source file

Syntax:

.PRIORITY symbolName, priority;

.PRIORITY symbolName,”sourcefile”, priority; where:

In the first case,

symbolName

is a global symbol or locally defined symbol.

In the second case,

symbolName

is a symbol defined in

‘sourcefile’

.


Assembler

Example:

.PRIORITY _foo, 35;

.PRIORITY _main, 15;

// Symbol with highest priority

// Symbol with medium priority

.PRIORITY bar, “barFile.asm”, -10; // Symbol with lowest

// priority

Linker Operation

After the absolute placement of symbols specified in the LDF’s

RESOLVE() command (but before mapping commands are processed), the linker tries to map all symbols appearing in priority directives (in decreasing order of their priorities).

The prioritized symbol is placed into memory that contains only the

INPUT_SECTIONS()

command for input sections defining the symbol.

Symbols with assigned priority are mapped after absolutely placed symbols, but before symbols without assigned priority.

The symbols are placed into memory segments based on the order that the segments are appear in the LDF. Therefore, an output section targeting a higher-priority memory segment should appear before an output section targeting a lower-priority segment.

Example of Assembler Code:

section program;

_func1:

_func2: section L1_code;

_L1_func:

...

.PRIORITY _L1 func,10;



.PRIORITY _func1,11;

.PRIORITY _func2,12;

Example of LDF Code:

L1_A

L1_A

L2

{ INPUT_SECTIONS($OBJECTS(L1_code)) } > L1_A;//

{ INPUT_SECTIONS($OBJECTS(L1_code program)) } > L1_B;

{ INPUT_SECTIONS($OBJECTS(program)) } > L2;

The preceding two examples result in the linker executing the following three steps:

1. Because

_func2

is assigned the highest priority (12) in the assembler code, the linker first tries to map it into the

L1_B

memory segment. If

_func2

does not fit into

L1_B

, it tries the

L2

segment.

2. Because

_func1

is assigned the middle priority (11) in the assembler code, the linker first tries to map it into the

L1_B

memory segment. If

_func2

does not fit into

L1_B

, it tries the

L2

segment.

3. Because

_L1_func

is assigned the lowest priority (10) in the assembler code, the linker first tries to map it into the

L1_A

memory segment. If

_L1_func

does not fit into

L1_A

, it tries the

L1_B segment.


Assembler

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

L


The

.REFERENCE

directive is used by the compiler to provide better information in an X-REF file generated by the linker. This directive is used when there are indirect symbol references that would otherwise not appear in an X-REF file.

The

.REFERENCE


.REFERENCE symbol; where:

symbol

– is a symbol

Example:

.REFERENCE P1;

.REFERENCE P2;

//

//



.RETAIN_NAME, Stop Linker from Eliminating Symbol

The

.RETAIN_NAME

directive stops the linker from eliminating the symbol when linking the generated object file. This directive has the same effect as the KEEP() LDF command has when used with the linker.

Syntax:

The

.RETAIN_NAME


.RETAIN_NAME symbol; where:

symbol

– is a user-defined symbol

For information on KEEP(), refer to the VisualDSP++ 5.0 Linker and

Utilities manual.


Assembler

.ROUND_, Select Floating-Point Rounding

L


The

.ROUND_

directives control how the assembler interprets literal floating-point numeric data after

.PRECISION

is defined. The

.PRECISION

directive determines the number of bits to be truncated to match the

number of significant bits (see on page 1-109 ).

The

.ROUND_

directives determine how the assembler handles the floating-point values in constant declarations and variable initializations.

To configure the floating-point rounding modes of the target processor system, you must set up control registers on the chip using instructions specific to the processor core.

The

.ROUND_

directives use the following syntax:

.ROUND_mode; where:

The

mode

string specifies the rounding scheme used to fit a value in the destination format. Use one of the following IEEE standard modes:

.ROUND_NEAREST;

(default)

.ROUND_PLUS;

.ROUND_MINUS;

(rounds to round-to-positive infinity)

(rounds to round-to-negative infinity)

.ROUND_ZERO;

(selects round-to-zero)

In the following examples, the numbers with four decimal places are reduced to three decimal places and are rounded accordingly.

.ROUND_NEAREST;

/* Selects Round-to-Nearest scheme; this is the default setting.

A 5 is added to the digit that follows the third



decimal digit (the least significant bit - LSB). The result is truncated after the third decimal digit (LSB).

1.2581 rounds to 1.258

8.5996 rounds to 8.600

-5.3298 rounds to -5.329

-6.4974 rounds to -6.496

*/

.ROUND_ZERO;

/* Selects Round-to-Zero. The closer to zero value is

taken.

The number is truncated after the third decimal digit

(LSB)

1.2581 rounds to 1.258

8.5996 rounds to 8.599

-5.3298 rounds to -5.329

-6.4974 rounds to -6.497

*/

.ROUND_PLUS;

/* Selects Round-to-Positive Infinity. The number rounds to the next larger.

For positive numbers, a 1 is added to the third decimal digit (the least significant bit). Then the result is truncated after the LSB.

For negative numbers, the mantissa is truncated after the third decimal digit (LSB).

1.2581 rounds to 1.259

8.5996 rounds to 8.600

-5.3298 rounds to -5.329

-6.4974 rounds to -6.497

*/


.ROUND_MINUS;

/* Selects Round-to-Negative Infinity. The value rounds to the next smaller.

For negative numbers, a 1 is subtracted from the third decimal digit (the least significant bit).

Then the result is truncated after the LSB.

For positive numbers, the mantissa is truncated after the third decimal digit (LSB).

1.2581 rounds to 1.258

8.5996 rounds to 8.599

-5.3298 rounds to -5.330

-6.4974 rounds to -6.498

*/

Assembler



.SECTION, Declare a Memory Section

The

.SECTION

directive marks the beginning of a logical section mirroring an array of contiguous locations in your processor memory. Statements between one

.SECTION

directive and the following

.SECTION

directive (or the end-of-file instruction), comprise the content of the section.

TigerSHARC and Blackfin Syntax:

.SECTION/qualifier [/qualifier] sectionName [sectionType];

SHARC Syntax:

.SECTION[/TYPE/qualifier sectionName [sectionType];

L

All qualifiers are optional, and more than one qualifier can be used.

Common .SECTION Attributes

The following are common syntax attributes used by the assembler:

•

sectionName

– section name symbol which is not limited in length and is case-sensitive. Section names must match the corresponding input section names used by the LDF to place the section. Use the default LDF included in the

.../ldf

subdirectory of the VisualDSP++ installation directory, or write your own LDF.

L

Some sections starting with “

.

” names have certain meaning within the linker. Do not use the dot (

.

) as the initial character in

sectionName

.


Assembler

The assembler generates relocatable sections for the linker to fill in the addresses of symbols at link time. The assembler implicitly prefix the name of the section with the “

.rela.

” string to form a relocatable section. To avoid ambiguity, ensure that your section names do not begin with “

.rela.

”.

•

sectionType

– an optional ELF section type identifier. The assembler uses the default

SHT_PROGBITS

when this identifier is absent.

For example,

.SECTION program SHT_DEBUGINFO;

Supported ELF section types are

SHT_PROGBITS

,

SHT_DEBUGINFO

, and

SHT_NULL

. These sectionTypes

are described in the

ELF.h

header file, which is available from third-party software development kits. For more information on the ELF file format, see the

VisualDSP++ 5.0 Linker and Utilities Manual.

[

If you select an invalid common qualifier or specify no common qualifier, the assembler exits with an error message.

Blackfin Example:

/* Declared below memory sections correspond to the default LDF’s input sections. */

.SECTION/DOUBLE32 data1;

.SECTION/DOUBLE32 program;

// memory section to store data

// memory section to store code

DOUBLE* Qualifiers

The

DOUBLE*

qualifier can be one of:

Table 1-18. DOUBLE Qualifiers

Qualifer

DOUBLE32

DOUBLE64

DOUBLEANY

Description

DOUBLEs

are represented as 32-bit types

DOUBLEs

are represented as 64-bit types

Section does not include code that depends on the size of

DOUBLE



The

DOUBLE

size qualifiers are used to ensure that object files are consistent when linked together and with run-time libraries. A memory section may have one

DOUBLE

size qualifier – it cannot have two

DOUBLE

size qualifiers.

Sections in the same file do not have to have the same type size qualifiers.

L

Use of

DOUBLEANY

in a section implies that

DOUBLE

’s are not used in this section in any way that would require consistency checking with any other section.

TigerSHARC-Specific Qualifiers

In addition, the TigerSHARC-specific

qualifier1

,

qualifier2...

can be one of the following, listed in Table 1-19 :

Table 1-19. TigerSHARC-Specific Qualifiers

CHAR8 CHAR32

CHARs

are represented as 8-bit types.

Shorts


CHARs

are represented as

32-bit types.

Shorts


CHARANY

Section does not include code that depends on the size of

CHAR

.

The char

size qualifiers are used to ensure that object files are consistent when linked together and with run-time libraries. A section may have a double

size qualifier and a char

size qualifier. It cannot have two char

size qualifiers. Sections in the same file do not have to have the same type size qualifiers.

L

Note: Use of

CHARANY

in a section implies that char

and shorts

are not used in this section in any way that would require consistency checking with any other section.


Assembler

SHARC-Specific Qualifiers

For the SHARC assembler, the .

SECTION

directive supports qualifiers that specify the size of data words in the section (and a qualifier that may be used to specify restricted placement for the section). Each section that defines data or code must bear an appropriate size qualifier; the placement qualifier is optional. Table 1-20 lists the SHARC-specific qualifiers.

Table 1-20. SHARC-Specific Qualifiers

Memory/Section

Type

PM

or

Code

DM

or

Data

DATA64

DMAONLY

Description

Section contains instructions and/or data, in 48-bit words

Section contains data in 40-bit words

Section defines data in 64-bit words

Section is to be placed in memory that can be accessed through DMA only

The

DMAONLY

qualifier does enforce that access to the section contents occurs through DMA alone; this qualifier passes to the linker the request that this section is to be placed in a memory segment that has the

DMAONLY qualifier, which applies to memory accessed through the external parallel port of ADSP-2126x processors and some ADSP-2136x processors.

For example:

.SECTION/DM/DMAONLY seg_extm;

.VAR _external_var[100];

Initialization Section Qualifiers

The

.SECTION

directive may identify “how/when/if” a section is initialized.

The initialization qualifiers, common for all supported assemblers, are listed in Table 1-21 .



Table 1-21. SHARC-Specific Qualifiers

Qualifier

NO_INIT

ZERO_INIT

RUNTIME_INIT

Description

The section is “sized” to have enough space to contain all data elements placed in this section. No data initialization is used for this memory section.

Similar to /NO_INIT, except that the memory space for this section is initialized to zero at “load time” or “runtime”, if invoked with the linker’s

-meminit switch. If the -meminit switch is not used, the memory is initialized at “load” time when the .DXE file is loaded via VisualDSP++

IDDE, or boot-loaded by the boot kernel. If the memory initializer is invoked, the C/C++ run-time library (CRTL) processes embedded information to initialize the memory space during the CRTL initialization process.

If the memory initializer is not run, this qualifier has no effect. If the memory initializer is invoked, the data for this section is set during the CRTL initialization process.

For example,

.SECTION/NO_INIT seg_bss;

.VAR big[0x100000];

.SECTION/ZERO_INIT seg_bsz;

.VAR big[0x100000];

Initialized data in a

/NO_INIT

or

/ZERO_INIT

section is ignored.

For example, the assembler can generate a warning for the

.VAR zz initialization.

.SECTION/NO_INIT seg_bss;

.VAR xx[1000];

.VAR zz = 25; // [Warning ea1141] "example.asm":3 'zz':

Data directive with assembly-time initializers found in .SECTION 'seg_bss' with qualifier /NO_INIT.


Assembler

Likewise, the assembler generates a warning for an explicit initialization to

0 in a

ZERO_INIT

section.

.SECTION/ZERO_INIT seg_bsz;

.VAR xx[1000];

.VAR zz = 0;

The assembler calculates the size of

NO_INIT

and

ZERO_INIT

sections exactly as for the standard

SHT_PROGBITS

sections. These sections, like the sections with initialized data, have the

SHF_ALLOC

flag set. Alignment sections are produced for

NO_INIT

and

ZERO_INIT

sections.

Table 1-22. Section Qualifiers, Section-Header-Types, and

Section-Header-Flags

.SECTION Qualifier

.SECTION/NO_INIT

.SECTION/ZERO_INIT

.SECTION/RUNTIME_INIT

ELF SHT_* (Elf.h)

Section-Header-Type

SHT_NOBITS

SHT_NOBITS

SHT_PROGBITS

ELF SHF_* (Elf.h)

Section-Header-Flag

SHF_ALLOC

SHF_ALLOC

,

SHF_INIT

SHF_ALLOC

,

SHF_INIT

For more information, refer to the VisualDSP++ 5.0 Linker and Utilities

Manual.



.SEGMENT and .ENDSEG, Legacy Directives

L


Releases of the ADSP-210xx DSP development software prior to

VisualDSP++ 4.1 used the

.SEGMENT

and

.ENDSEG

directives to define the beginning and end of a section of contiguous memory addresses.

Although these directives have been replaced with the

.SECTION directive, the source code written with

.SEGMENT

/

.ENDSEG

legacy directives is accepted by the ADSP-21xxx assembler.

.SEPARATE_MEM_SEGMENTS

L

Used with TigerSHARC processors ONLY.

The

.SEPARATE_MEM_SEGMENTS

directive allows you to specify two buffers the linker should try to place into different memory segments.

Syntax:

.SECTION data1;

.VAR buf1;

.VAR buf2;

.EXTERN buf3;

.SEPARATE_MEM_SEGMENTS buf1, buf2

.SEPARATE_MEM_SEGMENTS buf1, buf3

You can also use the compiler’s separate_mem_segments

pragma to perform the same function. For more information, refer to Chapter 2 of the VisualDSP++ 5.0 Linker and Utilities Manual.


Assembler

.SET, Set a Symbolic Alias

The

.SET

directive is used to alias one symbol for another.

Syntax:

.SET

symbol1,

symbol2

Where where

symbol1

becomes an alias to

symbol2

.

Example

.SET symbol1, symbol1

.SHORT, Defines and initializes 2-byte data objects

L


The

.SHORT

directive declares and optionally initializes two-byte data objects. It is it is effectively equivalent to

.BYTE2 initExpression1,

initExpression2,…

. For more information, see

“.BYTE, Declare a Byte

Data Variable or Buffer” on page 1-76

.

Syntax:

When declaring and/or initializing memory variables or buffer elements, use this format. Note that the terminating semicolon is optional.

.SHORT initExpression1, initExpression2,…[;]

.SHORT constExpression1, constExpression2,…[;] where

initExpressions

parameters – contain one or more comma-separated

“symbol=value” expressions



constExpressions

parameters – contain a comma-separated list of constant values


.SHORT

directives:

// Declare three 2-byte variables, zero-initialized

.SHORT Ins, Outs, Remains;

// Declare a 2-byte variable and initialize it to 100

.SHORT taps=100;

// Declare three 2-byte areas of memory, initialized to

3, 4 and 5 respectively

.SHORT 0x3, 0x4, 0x5;

.STRUCT, Create a Struct Variable

The

.STRUCT

directive allows you to define and initialize high-level data objects within the assembly code. The

.STRUCT

directive creates a struct variable using a C-style

typedef

as its guide from .

IMPORT

C header files.

Syntax:

.STRUCT typedef

structName

;

.STRUCT typedef

structName

= {};

.STRUCT typedef

structName

= {

struct-member-initializers

[ ,struct-member-initializers... ] };

.STRUCT typedef

ArrayOfStructs

[] =

{


[ ,struct-member-initializers... ] }; where

typedef

– the type definition for a struct

VARstructName

– a struct

name


– per struct member initializers


Assembler

The

{ }

curly braces are used for consistency with the C initializer syntax.

Initialization can be in “long” or “short” form where data member names are not included. The short form corresponds to the syntax in C compiler struct initialization with these changes:

• Change C compiler keyword struct

to .

struct

(adds the period (

.

)

• Change C compiler constant string syntax “

MyString

” to

'

MyString

' (changes the double quotes (

“ “

) into single quotes

(

‘ ‘

))

The long form is assembler-specific and provides the following benefits:

• Provides better error checking

• Supports self-documenting code

• Protects from possible future changes to the layout of the struct

.

If an additional member is added before the member is initialized, the assembler will continue to offset to the correct location for the specified initialization and zero-initialize the new member.

Any members that are not present in a long-form initialization are initialized to zero. For example, if struct

StructThree

has three members

( member1

, member2

, and member3

), and

.STRUCT StructThree myThree { member1 = 0xaa, member3 = 0xff

}; then member2

will be initialized to 0 because no initializer was present for it. If no initializers are present, the entire struct

is zero-initialized.

If data member names are present, the assembler validates that the assembler and compiler are in agreement about these names. The initialization of data struct members declared via the assembly

.STRUCT

directive is processor-specific.



Example 1. Long-Form .STRUCT Directive

#define NTSC 1

// contains layouts for playback and capture_hdr

.IMPORT "comdat.h";

.STRUCT capture_hdr myLastCapture = { captureInt = 0, captureString = ‘InitialState’

};

.STRUCT myPlayback playback = { theSize = 0, ready = 1, stat_debug = 0, last_capture = myLastCapture, watchdog = 0, vidtype = NTSC

};

Example 2. Short-Form .STRUCT Directive

#define NTSC 1

// contains layouts for playback and capture_hdr

.IMPORT "comdat.h";

.STRUCT capture_hdr myLastCapture = { 0, ‘InitialState’ };

.STRUCT playback myPlayback = { 0, 1, 0, myLastCapture, 0, NTSC};

Example 3. Long-Form .STRUCT Directive to Initialize an Array

.STRUCT structWithArrays XXX = { scalar = 5, array1 = { 1,2,3,4,5 }, array2 = { "file1.dat" }, array3 = "WithBraces.dat" // must have { } within dat

};


Assembler

In the short-form, nested braces can be used to perform partial initializations as in C. In Example 4 below, if the second member of the struct is an array with more than four elements, the remaining elements is initialized to zero.

Example 4. Short-Form .STRUCT Directive to Initialize an Array

.STRUCT structWithArrays XXX = { 5, { 1,2,3,4 }, 1, 2 };

Example 5. Initializing a Pointer

A struct may contain a pointer. Initialize pointers with symbolic references.

.EXTERN outThere;

.VAR myString[] = 'abcde',0;

.STRUCT structWithPointer PPP = { scalar = 5, myPtr1 = myString, myPtr2 = outThere

};

Example 6. Initializing a Nested Structure

A struct may contain a struct. Use fully qualified references to initialize nested struct members. The struct name is implied.

For example, the reference “ scalar

” (“ nestedOne->scalar

” implied) and

“ nested->scalar1

” (“ nestedOne->nested->scalar1

” implied).

.STRUCT NestedStruct nestedOne = { scalar = 10, nested->scalar1 = 5, nested->array = { 0x1000, 0x1010, 0x1020 }

};



.TYPE, Change Default Symbol Type

The

.TYPE

directive directs the assembler to change the default symbol type of an object. This directive may appear in the compiler-generated assembly source file (

.S

).

Syntax:

.TYPE

symbolName, symbolType

; where

symbolName

– the name of the object to which the

symbolType

is applied

symbolType

– an ELF symbol type

STT_*

. Valid ELF symbol types are listed in the

ELF.h

header file. By default, a label has an

STT_FUNC

symbol type, and a variable or buffer name defined in a storage directive has an

STT_OBJECT

symbol type.


Assembler

.VAR, Declare a Data Variable or Buffer

The

.VAR

directive declares and optionally initializes variables and data buffers. A variable uses a single memory location, and a data buffer uses an array of memory locations.

When declaring or initializing variables:

• A

.VAR

directive may appear only within a section. The assembler associates the variable with the memory type of the section in which the

.VAR

appears.

• A single

.VAR

directive can declare any number of variables or buffers, separated by commas, on one line.

Unless the absolute placement for a variable is specified with a

RESOLVE()

command (from an .

LDF

file), the linker places variables in consecutive memory locations. For example,

.VAR d,f,k[50]; sequentially places symbols x

, y

, and 50 elements of the buffer z

in the processor memory. Therefore, code example may look like:

.VAR d;

.VAR f;

.VAR k[50];

• The number of initializer values may not exceed the number of variables or buffer locations that you declare.

• The

.VAR

directive may declare an implicit-size buffer by using empty brackets [ ]. The number of initialization elements defines the

length

of the implicit-size buffer. At runtime, the length operator can be used to determine the buffer size. For example,

.SECTION data1;

.VAR buffer [] = 1,2,3,4;



.SECTION program;

LO = LENGTH( buffer ); // Returns 4

Syntax:

The

.VAR

directive takes one of the following forms:

.VAR

varName1[,varName2,…];

.VAR =

initExpression1,

initExpression2,…;

.VAR

bufferName[] = {initExpression1, initExpression2,...};

.VAR

bufferName[] = {"fileName"};

.VAR

bufferName[length] = "fileName";

.VAR

bufferName[length] = initExpression1,initExpression2,…; where:

varName

– user-defined symbols that identify variables

bufferName

– user-defined symbols that identify buffers

fileName

parameter – indicates that the elements of a buffer get their initial values from the

fileName

data file. The

<fileName>

can consist of the actual name and path specification for the data file. If the initialization file is in the current directory of your operating system, only the

fileName

need be given quotes. Note that when reading in a data file, the assembler reads in whitespace-separated lists of decimal digits or hex strings.

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 (…) – a comma-delimited list of parameters

[length]

– optional parameter that defines the length (in words) of the associated buffer. When length is not provided, the buffer size is determined by the number of initializers.


Assembler

Brackets (

[ ]

) – enclosing the optional [

length

] is required. For more information, see the following

.VAR

examples.

initExpressions

parameters – set initial values for variables and buffer elements.

L

With Blackfin processors, the assembler uses a

/R32

qualifier

(

.VAR/R32

) to support 32-bit initialization for use with 1.31 fracts

(see on page 1-55

).

The following code demonstrate some

.VAR

directives:

.VAR buf1=0x1234;

// Define one initialized variable

.VAR=0x1234, 0x5678;

// Define two initialized words

.VAR samples[] = {10, 11, 12, 13, 14};

// Declare and initialize an implicit-length buffer

// since there are five values; this has the same effect

// as samples[5]

.

// Initialization values for implicit-size buffer

// must be in curly brackets.

.VAR Ins, Outs, Remains;

// Declare three uninitialized variables

.VAR samples[100] = "inits.dat";

// Declare a 100-location buffer and initialize it

// with the contents of the inits.dat file;

.VAR taps=100;

// Declare a variable and initialize the variable

// to 100

.VAR twiddles[10] = "phase.dat";

// Declare a 10-location buffer and load the buffer



// with the contents of the phase.dat file

.VAR Fract_Var_R32[] = "fr32FormatFract.dat";

L

All Blackfin processor memory accesses require proper alignment.

Therefore, when loading or storing an

N

-byte value into the processor, ensure that this value is aligned in memory by

N

boundary; otherwise, a hardware exception is generated.

Blackfin Code Example:

In the following example, the 4-byte variables y0

, y1

, and y2

would be misaligned unless the

.ALIGN 4;

directive is placed before the

.VAR y0; and

.VAR y2;

statements.

.SECTION data1;

.ALIGN 4;

.VAR X0;

.VAR X1;

.BYTE B0;

.ALIGN 4; // aligns the following data item “Y0” on a word

// boundary; advances other data items

// consequently

.VAR Y0;

.VAR Y1;

.BYTE B1;

.ALIGN 4; // aligns the following data item “Y2” on a word

// boundary

.VAR Y2;

.VAR and ASCII String Initialization Support

The assemblers support ASCII string initialization. This allows the full use of the ASCII character set, including digits and special characters.

On SHARC and TigerSHARC processors, the characters are stored in the upper byte of 32-bit words. The least significant bits (LSBs) are cleared.


Assembler

When using 16-bit Blackfin processors, refer to the

.BYTE

directive description

on page 1-76 for more information.

String initialization takes one of the following forms:

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

.VAR symbolString[] = ‘initString’, 0;

Note that the number of initialization characters defines length of a string.

For example,

.VAR x[13] = ‘Hello world!’, 0;

.VAR x[] = {‘Hello world!’, 0};

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

The assemblers also accept ASCII characters within comments.

Note special characters handling:

.VAR s1[] = {'1st line',13,10,'2nd line',13,10,0};

// carriage return

.VAR s2[] = {'say:"hello"',13,10,0}; // quotation marks

.VAR s3[] = {'say:',39,'hello',39,13,10,0};

// simple quotation marks



.WEAK, Support Weak Symbol Definition and Reference

The

.WEAK

directive supports weak binding for a symbol. Use this directive where the symbol is defined (replacing the

.GLOBAL

directive to make a weak definition) and the

.EXTERN

directive (to make a weak reference).

Syntax:

.WEAK symbol; where:

symbol

– the user-defined symbol

While the linker will generate an error if two objects define global symbols with identical names, it will allow any number of instances of weak definitions of a name. All will resolve to the first, or to a single, global definition of a symbol.

One difference between

.EXTERN

and .

WEAK

references is that the linker does not extract objects from archives to satisfy weak references. Such references, left unresolved, have the value 0.

L

The .

WEAK

(or .

GLOBAL

scope) directive is required to make symbols available for placement through

RESOLVE

commands in the .

LDF file.


Assembler

Assembler Command-Line Reference

This section describes the assembler command-line interface and switch set. It describes the assembler’s switches, which are accessible from the operating system’s command line or from the VisualDSP++ environment.

This section contains:

•

“Running the Assembler” on page 1-140

•


Command-line switches control certain aspects of the assembly process, including debugging information, listing, and preprocessing. Because the assembler automatically runs the preprocessor as your program is assembled (unless you use the

-sp

switch), the assembler’s command line can receive input for the preprocessor program and direct its operation. For more information on the preprocessor, see Chapter 2

“Preprocessor” .

L

When developing a DSP project, you may find it useful to modify the assembler’s default options settings. The way you set the assembler’s options depends on the environment used to run the DSP development software.

See

“Specifying Assembler Options in VisualDSP++” on page 1-167 for more information.



Running the Assembler

To run the assembler from the command line, type the name of the appropriate assembler program followed by arguments (in any order), and the name of the assembly source file. easm21K

[ -switch1 [ -switch2 … ] ] sourceFile

easmts


easmblkfn


Table 1-23 explains these arguments.

Table 1-23. Assembler Command Line Arguments

Argument

easm21K easmts easmblkfn

-switch

Description

Name of the assembler program for SHARC, TigerSHARC, and Blackfin processors, respectively.

sourceFile

Switch (or switches) to process. The command-line interface offers many optional switches that select operations and modes for the assembler and preprocessor. Some assembler switches take a file name as a required parameter.

Name of the source file to assemble.

The name of the source file to assemble can be provided as:

•

ShortFileName

– a file name without quotes (no special characters)

•

LongFileName

– a quoted file name (may include spaces and other special path name characters)

The assembler outputs a list of command-line options when run without arguments (same as

-h[elp]

).


Assembler

The assembler supports relative path names and absolute path names.

When you specify an input or output file name as a parameter, follow these guidelines for naming files:

• Include the drive letter and path string if the file is not in the current project directory.

• Enclose long file names in double quotation marks; for example,

“long file name”.

• Append the appropriate file name extension to each file.

Table 1-24 summarizes file extension conventions accepted by the

VisualDSP++ environment.

Extension

.asm

.is

.h

.lst

.doj

.dat

Table 1-24. File Name Extension Conventions

File Description

Assembly source file

Note: The assembler treats files with unrecognized (or not existing) extensions as assembly source files.

Preprocessed assembly source file

Header file

Listing file

Assembled object file in ELF/DWARF-2 format

Data initialization file

Assembler command-line switches are case sensitive. For example, the following command line easmblkfn -proc ADSP-BF535 -l pList.lst -Dmax=100 -v -o bin\p1.doj p1.asm



runs the assembler with:

-proc ADSP-BF535

– specifies assembles instructions unique to

ADSP-BF535 processors

-l pList.lst

– directs the assembler to output the listing file

-Dmax=100

– defines the preprocessor macro max

to be 100

-v

– displays verbose information on each phase of the assembly

-o bin\p1.doj

– specifies the name and directory for the assembled object file p1.asm

– identifies the assembly source file to assemble

Assembler Command-Line Switch Descriptions

This section describes the assembler command-line switches in ASCII collation order. A summary of the assembler switches appears in Table 1-25 .

Detailed description of each assembler switch starts

on page 1-146

.

Table 1-25. Assembler Command-Line Switch Summary

Switch Name

-align-branch-lines

(

on page 1-146

)

Purpose

Aligns branch lines to avoid ADSP-TS101 processor sequencer anomaly.


Issues a warning or an error for an anomaly id.

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

(

on page 1-147

)

-anomaly-warn

{id1[,id2]|all|none}

(

on page 1-147

)

-anomaly-workaround id1[,id2...]

(

on page 1-148

)

Checks assembly instructions against hardware anomalies.


Implements a workaround for an anomaly id.


Assembler

Table 1-25. Assembler Command-Line Switch Summary (Cont’d)

Switch Name

-char-size-8

(

on page 1-148

)

-char-size-32

(

on page 1-148

)

-char-size-any

(

on page 1-149

)

-default-branch-np

(

on page 1-149

)

-default-branch-p

(

on page 1-149

)

Purpose

Adds

/CHAR8

to

.SECTION

s in the source file.


Adds

/CHAR32

to

.SECTION



Adds

/CHARANY

to

.SECTION



Makes branch lines default to NP to avoid ADSP-TS101 processor sequencer anomaly.


Make branch lines default to the Branch Target Buffer

(BTB).


Passes macro definition to the preprocessor.

-Dmacro[=definition]

(

on page 1-149

)

-double-size-32

(

on page 1-150

)

-double-size-64

(

on page 1-150

)

-double-size-any

(

on page 1-151

)

-expand-symbolic-links

(

on page 1-151

)

-expand-windows-shortcuts

(

on page 1-151

)

-file-attr attr [=value]

(

on page 1-151

)

-flags-compiler

-opt1...

(

on page 1-151

)

-flags-pp

...

-opt1...

(

on page 1-153

)

Adds

/DOUBLE32

to the

.SECTION


Adds

/DOUBLE64

to the

.SECTION


Adds

/DOUBLEANY

to the

.SECTION


Enables support for Cygwin style paths.

Enables support for Windows shortcuts.

Creates an attribute in the generated object file.

Passes each comma-separated option to the compiler.

(Used when compiling .

IMPORT

C header files.)

Passes each comma-separated option to the preprocessor.




Switch Name

-g

(

on page 1-154

)

–h[elp]

(

on page 1-155

)

-i|-I

directory pathname

(

on page 1-156

)

–l filename

(

on page 1-157

)

–li filename

(

on page 1-157

)

-M

(

on page 1-157

)

Purpose

Generates debug information (DWARF-2 format).

Outputs a list of assembler switches.

Searches a directory for included files.

Outputs the named listing file.

-MM

(

on page 1-158

)

–Mo filename

(

on page 1-158

)

–Mt filename

(

on page 1-158

)

Outputs the named listing file with # include

files expanded.

Generates make dependencies for

#include

and data files only; does not assemble. For example,

-M

suppresses the creation of an object file.

Generates make dependencies for

#include

and data files. Use

-MM

for make dependencies with assembly.

Writes make dependencies to the

filename

specified.

The

-Mo

option is for use with either the

-M

or -

MM option. If

-Mo

is not present, the default is

<stdout>

display.

Specifies the make dependencies target name. The

-Mt option is for use with either the

-M

or -

MM

option. If

-Mt is not present, the default is base name plus '

DOJ

'.

Treats multi-issue conflicts as warnings.


Do not issue a warning or an error for an anomaly id.

-micaswarn

(

on page 1-159

)

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

(

on page 1-159

)

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

(

on page 1-159

)

-no-expand-symbolic-links

(

on page 1-160

)

Do not implement a workaround for an anomaly id.

Disables support for Cygwin style paths.


Assembler


Switch Name

-no-expand-windows-shortcuts

(

on page 1-160

)

-no-temp-data-file

(

on page 1-160

)

-no-source-dependency

(

on page 1-159

)

Purpose

Disables support for Windows shortcuts.

Suppresses writing temporary data to a disk file.


Suppresses output of the source filename in the dependency output produced when "

-M

" or "

-MM

" has been specified.

Outputs the named object [binary] file.

–o filename

(

on page 1-161

)

-pp

(

on page 1-161

)

-proc

processor

(

on page 1-161

)

-save-temps

(

on page 1-162

)

–si-revision version

(

on page 1-162

)

-sp

(

on page 1-163

)

-stallcheck={none|cond|all}

(

on page 1-164

)

Runs the preprocessor only; does not assemble.

Specifies a target processor for which the assembler should produce suitable code.

Saves intermediate files

Specifies silicon revision of the specified processor.

Assembles without preprocessing.

Displays stall information:

• none

- no messages

• cond

- conditional stalls only (default)

• all

- all stall information


Displays information on each assembly phase.

-v

or

-verbose

(

on page 1-164

)

–version

(

on page 1-164

)

-w

(

on page 1-164

)

Displays version information for the assembler and preprocessor programs.

Disables all assembler-generated warnings.




Switch Name

-Werror

number[,number ...]

(

on page 1-165

)

-Winfo


(

on page 1-165

)

-Wno-info

(

on page 1-165

)

-Wnumber[,number ...]

(

on page 1-165

)

Purpose

Selectively turn assembler messages into errors.

Selectively turns assembler messages into informationals.

Does not display informational assembler messages..

Selectively disables warnings by one or more message numbers. For example,

-W1092

disables warning message ea1092

.

-Wsuppress

number[,number...]

(

on page 1-166

)

-Wwarn


(

on page 1-166

)

Selectively turns off assembler messages.

Selectively turns assembler messages into warnings.

-Wwarn-error

(

on page 1-166

)

Display all assembler warning messages as errors.

A description of each command-line switch includes information about case-sensitivity, equivalent switches, switches overridden/contradicted by the one described, and naming and spacing constraints on parameters.

-align-branch-lines

L

This switch is used with TigerSHARC processors ONLY.

The

-align-branch-lines

switch directs the assembler to align branch instructions (

JUMP

,

CALL

,

CJMP

,

CJMP_CALL

,

RETI

, and

RTI

) on quad-word boundaries by inserting

NOP

instructions prior to the branch instruction.

This may be done by adding

NOP

instructions in free slots in previous instruction lines.


Assembler

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

The

-anomaly-detect

switch directs the assembler to check assembly instructions for a specific hardware anomaly. Switch parameter is: id

Anomaly identifier (for example, 05-00-0245 or 05000245)

The check may result in an assembler warning or error when the assembler encounters assembly code that the anomaly will have an impact upon.

This option overrules any default behavior for the anomaly.

A warning may be issued if the assembler always implements a workaround for the anomaly instead of a check.

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

The

-anomaly-warn

switch directs the assembler to check assembly instructions against hardware anomalies. Switch parameters are: id

Anomaly identifier (for example, 05-00-0245 or 05000245) all none

Uses all identifiers known to the assembler

Do nothing

This option allows the user to control which anomaly warnings are to be displayed. Typically, the user would assemble the code using the

“

-anomaly-warn all

” selection. This will cause the assembler to issue a warning for all anomalies it knows about. To date this includes the following anomaly IDs:

05000165 05000209 05000227 05000244

05000245 F3F008 F3F013 F3F021

Any combination of these warning ids can be used as part of the command-line option.

L

This switch is used with Blackfin processors ONLY.



-anomaly-workaround [id]

The

-anomaly-workaround

switch directs the assembler to switch on any workaround instruction for a specific hardware anomaly. Switch parameter is: id


The workaround may result in an assembler altering the user assembly code so that it cannot encounter the anomaly. The assembler may issue a warning to indicate that it has altered the user assembly code. This option overrules any default behavior for the anomaly.

A warning may be issued if the assembler always checks for the anomaly and has no workaround.

-char-size-8

The

-char-size-8

switch directs the assembler to add

/CHAR8

to

.SECTION

s in the source file that do not have char

size qualifiers.

For .

SECTION s in the source file that already have a char

size qualifier, this option is ignored and a warning is produced. For more information, see

“.SECTION, Declare a Memory Section” on page 1-120 .

L


-char-size-32

The

-char-size-32


/CHAR32

to

.SECTION


size qualifiers.

For .




L



Assembler

-char-size-any

The

-char-size-any


/CHARANY

to

.SECTION


size qualifiers.

For .




L


-default-branch-np

The

-default-branch-np

(branch lines default to NP) switch directs the assembler to stop branch instructions (

JUMP

,

CALL

) from using the branch target buffer (BTB). This can be used to avoid a sequencer anomaly present on the ADSP-TS101 processor only. It is still possible to make branch instructions use the BTB when

-default-branch-np

is used by adding the (

P

) instruction option; for example,

JUMP lab1 (P);;

.

L


-default-branch-p

The

-default-branch-p

switch makes branch instructions (

JUMP, CALL

) use the branch target buffer (BTB). This is the default behavior. It is still possible to make branch instructions not use the BTB when

-default-branch-p

is used by adding the (

NP

) instruction option; for example,

JUMP labe1 (NP);;

.

L


-Dmacro[=definition]

The

-D

(define macro) switch directs the assembler to define a macro and

pass it to the preprocessor. See “Using Assembler Feature Macros” on page 1-25

for the list of predefined macros.



For example,

–Dinput

–Dsamples=10

–Dpoint=’Start’

// defines input as 1

// defines samples as 10

// defines point as the string ‘Start’

-double-size-32

The

-double-size-32


/DOUBLE32

to

.SECTION

s in the source file that do not have double

size qualifiers. For

.

SECTION s in the source file that already have a double



-double-size-64

The

-double-size-64


/DOUBLE64

to

.SECTION


size qualifiers. For

.


size qualifier, this option is ignored and a warning is produced. The

-double-size-any

flag should be used to avoid a linker warning when compiling C/C++ sources with

-double-size-64

.

Warning Example:

[Warning li2151] Input sections have inconsistent qualifiers as follows.

For more information, see


.


Assembler

-double-size-any

The

-double-size-any


/DOUBLEANY

to

.SECTION


size qualifiers, making

SECTION

contents independent of size of double

type. For .



“.SECTION,

Declare a Memory Section” on page 1-120 .

-expand-symbolic-links

The expand-symbolic-links

switch directs the assembler to correctly access directories and files whose name or path contain Cygwin path components.

-expand-windows-shortcuts

The expand-windows-shortcuts

switch directs the assembler to correctly access directories and files whose name or path contain Windows shortcuts.

-file-attr attr[=val]

The

-file-attr

(file attribute) switch directs the assembler to add an attribute, attr

, to the object file. The attribute will be given the value, val

, or “1” if the value is omitted.

Attr

should follow the rules for naming symbols.

Val

should be double quoted unless it follows the rules for naming symbols. See


for more information on naming conventions.

-flags-compiler

The

-flags-compiler -opt1 [,-opt2...]

switch passes each comma-separated option to the C compiler. The switch takes a list of one or more comma-separated compiler options that are passed on the compiler command line for compiling

.IMPORT

headers. The assembler calls the



compiler to process each header file in an

.IMPORT

directive. It calls the compiler with the

-debug-types

option along with any

-flags-compiler switches given on the assembler command line.

For example:

// file.asm has .IMPORT "myHeader.h" easmbkln -proc ADSP-BF535 -flags-compiler -I/Path -I. file.asm

The rest of the assembly program, including its

#include

files, are processed by the assembler preprocessor. The

-flags-compiler

switch processes a list of one or more valid C compiler options, including the

-D and

-I

options.

User-Specified Defines Options

-D

(defines) options in an assembler command line are passed to the assembler preprocessor, but they are not passed to the compiler for

.IMPORT

header processing. If

#defines

are used for

.IMPORT

header compilation, they must be explicitly specified with the

-flags-compiler switch.

For example:

// file.asm has .IMPORT "myHeader.h" easmblkfn -proc ADSP-BF535 -DaDef -flags-compiler -DbDef,

-DbDefTwo=2 file.asm

// -DaDef is not passed to the compiler ccblkfn -proc ADSP-BF535 -c -debug-types -DbDef -DbDefTwo=2 myHeader.h

L

See

“Using Assembler Feature Macros” on page 1-25

for the list of

predefined macros, including default macros.


Assembler

Include Options

The

-I

(include search path) options and

-flags-compiler

arguments are passed to the C compiler for each .

IMPORT header compilation.

The compiler include

path is always present automatically.

Use the

-flags-compiler

switch to control the order that the include directories are searched. The

-flags-compiler

switch attributes take precedence from the assembler’s

-I

options.

For example, easmblkfn -proc ADSP-BF535 -I/aPath -DaDef -flags-compiler

-I/cPath,-I. file.asm

ccblkfn -proc ADSP-BF535 -c -debug-types -I/cPath -I. myHeader.h

The .

IMPORT

C header files are preprocessed by the C compiler preprocessor. The struct

headers are standard C headers, and the standard C compiler preprocessor is needed. The rest of the assembly program

(including its

#include

files) are processed by the assembler preprocessor.

Assembly programs are preprocessed using the pp

preprocessor (the assembler/linker preprocessor) as well as

-I

and

-D

options from the assembler command line. However, the pp

call does not receive the

-flags-compiler switch options.

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

The

-flags-pp

switch passes each comma-separated option to the preprocessor.

L

Use

-flags-pp

with caution. For example, if pp

legacy comment syntax is enabled, the comment characters become unavailable for non-comment syntax.



-g

The

-g

(generate debug information) switch directs the assembler to generate complete data type information for arrays, functions, and the C structs. This switch also generates DWARF2 function information with starting and ending ranges based on the myFunc: … myFunc.end:

label boundaries, as well as line number and symbol information in DWARF2 binary format, allowing you to debug the assembly source files.

When the assembler’s

-g

switch is in effect, the assembler produces a warning when it is unable to match a

*.end

label to a matching beginning label. This feature can be disabled using the

-Wnnnn

switch (see

on page 1-165

).

WARNING ea1121: Missing End Labels

Warning ea1121

occurs on assembly file debug builds (using the

-g switch) when a globally defined function or label for a data object is missing its corresponding ending label, with the naming convention label +

“

.end

”. For example:

[Warning ea1121] "./gfxeng_thickarc.asm":42 _gfxeng_thickarc:

-g assembly with global function without ending label. Use

'_gfxeng_thickarc.end' or '_gfxeng_thickarc.END' to mark the ending boundary of the function for debugging information for automated statistical profiling of assembly functions.

The ending label marks the boundary of the end of a function. Compiled code automatically provides ending labels. Hand-written assembly code needs to have the ending labels explicitly added to tell the tool chain where the ending boundary is. This information is used to automate statistical profiling of assembly functions. It is also needed by the linker to eliminate unused functions and other features.


Assembler

To suppress a specific assembler warning by unique warning number, the assembler provides the following option:

-Wsuppress 1121

L

It is highly recommended that warning ea1121

not be suppressed and the code be updated to have ending labels.

Functions (Code)

_gfxeng_vertspan:

...

[--sp] = fp; rts;

Add ending label after rts;

. Use the prefix “

.end

” and begin the label with “.” to have it treated as an internal label that is not displayed in the debugger.

.global _gfxeng_vertspan;

_gfxeng_vertspan:

...

[--sp] = fp; rts;

._gfxeng_vertspan.end:

-h[elp]

The

-h

(or

-help

) switch directs the assembler to output to standard output a list of command-line switches with a syntax summary.



-i

The

-idirectory

(or

-I

) switch (include directory path) directs the assembler to append the specified directory (or a list of directories separated by semicolons “

;

”) to the search path for included files.

L

No space is allowed between

-i

and the path name.

These files are:

• Header files (

.h

) included with the

#include

preprocessor command

• Data initialization files (

.dat

) specified with the

.VAR

assembly directive

The assembler passes this information to the preprocessor; the preprocessor searches for included files in the following order:

1. Directory for assembly program

2.

...\include

subdirectory of the VisualDSP++ installation directory

3. Specified directory (or list of directories). The order of the list defines the order of multiple searches.

The current directory is the directory where the assembly service is, not the directory of the project. Usage of full path names for the

-I

switch on the command line is recommended.

For example, easm21K -proc ADSP-21161 -I “\bin\include” file.asm


Assembler

-l filename

The

-l

filename

(listing) switch directs the assembler to generate the named listing file. Each listing file (

.lst

) shows the relationship between your source code and instruction opcodes that the assembler produces.

For example, easmblkfn -proc ADSP-BF533 -I\path -I. -l file.lst file.asm

The file name is a required argument to the

-l

switch. For more information, see

“Reading a Listing File” on page 1-32 .

-li filename

The

-li

(listing) switch directs the assembler to generate the named listing file with

#include

files. The file name is a required argument to the

-li switch. For more information, see

“Reading a Listing File” on page 1-32 .

-M

The

-M

(generate make rule only) assembler switch directs the assembler to generate make dependency rules, suitable for the make utility, describing the dependencies of the source file. No object file is generated for

-M assemblies. For make dependencies with assembly, use the

-MM

switch.

The output, an assembly make dependencies list, is written to stdout

in the standard command-line format:

“target_file”: “dependency_file.ext”

where

dependency_file.ext

may be an assembly source file, a header file included with the

#include

preprocessor command, a data file, or a header file imported via the .

IMPORT

directive.



The

-Mo

filename

switch writes make dependencies to the

filename

specified instead of

<stdout>

. For consistency with the compilers, when

-o filename

is used with

-M

, the assembler outputs the make dependencies list to the named file. The

-Mo

filename

takes precedence if both

-o filename

and

-Mo filename

are present with

-M

.

-MM

The

-MM

(generate make rule and assemble) assembler switch directs the assembler to output a rule, suitable for the make utility, describing the dependencies of the source file. The assembly of the source into an object file proceeds normally. The output, an assembly make dependencies list, is written to stdout.

The only difference between

-MM

and

-M

actions is that the assembling continues with

-MM

. See

“-M” for more information.

-Mo filename

The

-Mo

(output make rule) assembler switch specifies the name of the make dependencies file that the assembler generates when you use the

-M or

-MM

switch. If

-Mo

is not present, the default is

<stdout>

display. If the named file is not in the current directory, you must provide the path name in double quotation marks (

“ ”

).

L

The

-Mo

filename

switch takes precedence over the

-o

filename

switch.

-Mt filename

The

-Mt

filename

(output make rule for named object) assembler switch specifies the name of the object file for which the assembler generates the make rule when you use the

-M

or

-MM

switch. If the named file is not in the current directory, you must provide the path name. If

-Mt

is not present, the default is the base name plus the

.doj

extension. See

“-M”



Assembler

-micaswarn

The

-micaswarn

switch treats multi-issue conflicts as warnings.

L


-no-source-dependency

The

-no-source-dependency

switch directs the assembler not to print anything about dependency between the

.asm

source file and the

.doj

object file when outputting dependency information. This switch can only be used in conjunction with the

-M

or

-MM

switches (see on page 1-157 ).

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

The

-no-anomaly-detect

switch directs the assembler to switch off any check for a specific anomaly id in the assembler. No assembler warning or error will be issued when the assembler encounters assembly code that the anomaly will have an impact upon. This option overrules any default behavior for the anomaly.. The switch parameter is: id


A warning may be issued if the assembler always implements a workaround for the anomaly instead of a check.

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

The

-no-anomaly-workaround

switch directs the assembler to switch off any workaround for a specific anomaly id in the assembler. The assembler will not alter the user assembly code so that it cannot encounter the anomaly. This option overrules any default behavior for the anomaly.



The switch parameter is: id


A warning may be issued if the assembler always checks for the anomaly and has no workaround.

-no-expand-symbolic-links

The no-expand-symbolic-links

switch directs the assembler to not expand any directories or files whose name or path contain Cygwin path components.

-no-expand-windows-shortcuts

The

-no-expand-windows-shortcuts

switch directs the assembler to not expand directories or files whose name or path contain Windows shortcuts.

-no-temp-data-file

The

-no-temp-data-file

switch directs the assembler not to write temporary data to a memory (disk).

As part of a space saving measure, the assembler stores all data declarations into a file. This is to allow large sources to assemble more quickly by freeing valuable memory resources. By default, the temporary data files are stored into the system temporary folder (for example,

C:\Documents and

Settings\User\Local Settings\Temp

) and is given the prefix “

EasmblkfnNode

”). These files are removed by the assembler but, if for any reason the assembler does not complete, these files will not be deleted and persist in the temporary folder. These can always be safely deleted in such circumstances after the assembler has stopped.


Assembler

This command line option allows the user to turn off this default feature.

When turned off, all data is stored into internal memory and not written to the disk.

-o filename

The

-o

filename

(output file) switch directs the assembler to use the specified

filename

argument as the output file. This switch names the output, whether for conventional production of an object, a preprocessed, assemble-produced file (

.is

), or make dependency (

-M

). By default, the assembler uses the root input file name for the output and appends a

.doj

extension.

Some examples of this switch syntax are: easmblkfn -proc ADSP-BF535 -pp -o test1.is test.asm

// preprocessed output goes into test1.is

easmblkfn -proc ADSP-BF535 -o -debug/prog3.doj prog3.asm

// specify directory and filename for the object file

-pp

The

-pp

(proceed with preprocessing only) switch directs the assembler to run the preprocessor, but stop without assembling the source into an object file. When assembling with the

-pp

switch, the

.is

file is the final result of the assembly. By default, the output file name uses the same root name as the source, with the

.is

extension.

-proc processor

The

-proc

processor

(target processor) switch specifies that the assembler produces code suitable for the specified processor.

The

processor

identifiers directly supported by VisualDSP++ 5.0 are

listed in “Supported Processors”

.



For example: easm21K easmts

-proc ADSP-21161 -o bin\p1.doj p1.asm

-proc ADSP-TS201 -o bin\p1.doj p1.asm

easmblkfn -proc ADSP-BF533 -o bin\p1.doj p1.asm

If the processor identifier is unknown to the assembler, it attempts to read required switches for code generation from the file

<processor>.ini

.

The assembler searches for the .

ini

file in the VisualDSP++

System

folder.

For custom processors, the assembler searches the section “ proc

” in the

<processor>.ini

file for key “ architecture

”. The custom processor must be based on an architecture key that is one of the known processors.

For example,

-proc Custom-xxx

searches the

Custom-xxx.ini

file.

L

See also the

-si-revision version

switch description

( on page 1-162 ) for more information on silicon revision of the

specified processor.

-save-temps

The

-save-temps

(save intermediate files) switch directs the assembler to retain intermediate files generated and normally removed as part of the assembly process.

-si-revision version

The

-si-revision version

(silicon revision) switch directs the assembler to build for a specific hardware revision. Any errata workarounds available for the targeted silicon revision will be enabled. The

version

parameter represents a silicon revision for the processor specified by the

-proc

switch

(

on page 1-161

).

For example, easmblkfn -proc ADSP- BF533 -si-revision 0.1


Assembler

If silicon version “ none

” is used, no errata workarounds are enabled, whereas specifying silicon version “ any

” enables all errata workarounds for the target processor.

If the

-si-revision

switch is not used, the assembler will build for the target processor’s latest known silicon revision and will enable any errata workarounds appropriate for the latest silicon revision.

The

__SILICON_REVISION__

macro is set by the assembler to two hexadecimal digits representing the major and minor numbers in the silicon revision. For example,

1.0

becomes

0x100

and

10.21

becomes

0xa15

.

If the silicon revision is set to “ any

”, the


macro is set to

0xffff

. If the

-si-revision

switch is set to “ none

”, the assembler will not set the


macro.

-sp

The

-sp

(skip preprocessing) switch directs the assembler to assemble the source file into an object file without running the preprocessor. When the assembler skips preprocessing, no preprocessed assembly file (

.is

) is created.



-stallcheck

The

-stallcheck = option

switch provides the following choices for displaying stall information:

Table 1-26. -stallcheck Options

-stallcheck Option

-stallcheck=none

stallcheck=cond

stallcheck=all

Description

Displays no messages for stall information

Displays information about conditional stalls only (default)

Displays all stall information

L


-v[erbose]

The

-v

(or

-verbose

) switch directs the assembler to display version and command-line information for each phase of assembly.

-version

The

-version

(display version) switch directs the assembler to display version information for the assembler and preprocessor programs.

-w

The

-w

(disable all warnings) switch directs the assembler not to display warning messages generated during assembly.


Assembler

-Werror number[,number]

The

-Werror

number

switch turns the specified assembler messages into errors. For example, “

-Werror 1177

” turns warning message ea1177

into an error. This switch optionally accepts a list, such as

[,number ...]

.

L


-Winfo number[,number]

The

-Winfo

number

switch turns the specified assembler messages into informational messages. For example, “

-Winfo 1177

” turns warning message ea1177

into an informational message. This switch optionally accepts a list, such as

[,number ...]

.

L


-Wno-info

The

-Wno-info

switch turns off all assembler informational messages.

-Wnumber[,number]

The

-Wnumber

(warning suppression) switch selectively disables warnings specified by one or more message numbers. For example,

-W1092

disables warning message ea1092

. Optionally, this switch accepts a list, such as

[,number ...]

. See also

“-g” on page 1-154 .



-Wsuppress number[,number]

The

-Wsuppress

number

switch selectively turn off assembler messages.

For example, “

-Wsuppress 1177

” turns off warning message ea1177.

Optionally, this switch accepts a list, such as

[,number ...]

.

L


-Wwarn number[,number]

The

-Wwarn

number

switch turns the specified assembler messages into warnings. For example, “

-Wwarn 1154

” turns error message ea1154

into a warning. Optionally, this switch accepts a list, such as

[,number ...]

.

L


-Wwarn-error

The

-Wwarn-error

switch displays all the assembler warning messages as errors.


Assembler

Specifying Assembler Options in VisualDSP++

Within the VisualDSP++ IDDE, specify tool settings for project builds.

Use the Project menu to open the Project Options dialog box

Figure 1-5 shows an example of the Project page of the Project Options dialog box showing selections for a Blackfin processors.

Figure 1-5. Example: Project Options Dialog Box - Project Page

These dialog boxes allow you to select the target processor, type and name of the executable file, as well as VisualDSP++ tools available for use with the selected processor.



When using the VisualDSP++ IDDE, use the Assemble page of the

Project Options dialog box ( Figure 1-6 ) to select and/or set assembler functional options.

Figure 1-6. Example: Project Options Dialog Box – Assemble Page

Most dialog box options have corresponding assembler command-line switches described in


.

For more information, use the VisualDSP++ context-sensitive online Help for each target architecture to select information on assembler options you can specify in VisualDSP++. To do that, click on the ? button and then click on the field or box for which you require information.


Assembler

The Additional options field is used to enter the appropriate command-line switches, file names, and options that do not have corresponding controls on the Assemble page but are available via command-line invocation.

Assembler options apply to directing calls to an assembler when assembling

.asm

files. Changing assembler options in VisualDSP++ does not affect the assembler calls made by the compiler during the compilation of

.C/.CPP

files.




Preprocessor

2 PREPROCESSOR

The preprocessor program ( pp.exe

) evaluates and processes preprocessor commands in source files on all supported processors. The preprocessor commands direct the preprocessor to define macros and symbolic constants, include header files, test for errors, and control conditional assembly and compilation. The preprocessor supports ANSI C standard preprocessing with extensions, such as “

?

” and “

...

”.

The preprocessor is run by other build tools (assembler and linker) from the operating system’s command line or from within the VisualDSP++ 5.0 environment. The pp

preprocessor can also operate from the command line with its own command-line switches.

This chapter contains:

•

“Preprocessor Guide” on page 2-2

Contains the information on building programs

•

“Preprocessor Command Reference” on page 2-20

Describes the preprocessor’s commands, with syntax and usage examples

•

“Preprocessor Command-Line Reference” on page 2-44

Describes the preprocessor’s command-line switches, with syntax and usage examples


Preprocessor Guide


This section describes pp

preprocessor information used when building programs from a command line or from within the VisualDSP++ 5.0 environment. Software developers who use the preprocessor should be familiar with:

•

“Writing Preprocessor Commands” on page 2-3

•

“Header Files and the #include Command” on page 2-4

•

“Writing Macros” on page 2-7

•

“Using Predefined Preprocessor Macros” on page 2-15

•

“Specifying Preprocessor Options” on page 2-20

Compiler Preprocessor

The compiler has it own preprocessor that enables the use of preprocessor commands within C/C++ source. The compiler preprocessor automatically runs before the compiler. This preprocessor is separate from the assembler preprocessor and has some features that may not be used within your assembly source files. For more information, refer to the

VisualDSP++ 5.0 C/C++ Compiler and Library Manual for the target processor.

Assembler Preprocessor

The assembler preprocessor differs from the ANSI C standard preprocessor in several ways. First, the assembler preprocessor supports a “?” operator (see

on page 2-42

) that directs the preprocessor to generate a unique label for each macro expansion. Second, the assembler preprocessor does not treat “.” as a separate token. Instead, “.” is always treated as


Preprocessor

part of an identifier. This behavior matches the assembler’s behavior, which uses “

.

” to start directives and accepts “

.

” in symbol names.

For example, the following command sequence:

#define VAR my_var

.VAR x; does not cause any change to the variable declaration. The text “.

VAR

” is treated as a single identifier which does not match the macro name

VAR

.

The standard C preprocessor treats .

VAR

as two tokens ( “

.

” and “

VAR

”) and makes the following substitution:

.my_var x;

The assembler preprocessor also produces assembly-style strings

(single-quote delimiters) instead of C-style strings.

Finally, under command-line switch control, the assembler preprocessor supports legacy assembler commenting formats (“

!

” and “

{ }

”).

Writing Preprocessor Commands

Preprocessor commands begin with a pound sign (

#

) and end with a carriage return. The pound sign must be the first non-white space character on the line containing the command. If the command is longer than one line, use a backslash (

\

) and a carriage return to continue the command on the next line. Do not place any characters between the backslash and the carriage return. Unlike assembly directives, preprocessor commands are case sensitive and must be lowercase.

For more information on preprocessor commands, see “Preprocessor

Command-Line Reference” on page 2-44 .



For example:

#include "string.h"

#define MAXIMUM 100

When the preprocessor runs, it modifies the source code by:

• Including system header files and user-defined header files

• Defining macros and symbolic constants

• Providing conditional assembly

Specify preprocessing options with preprocessor commands—lines that start with a

#

character. In the absence of commands, the preprocessor performs these three global substitutions:

• Replaces comments with single spaces

• Deletes line continuation characters (

\

)

• Replaces macro references with corresponding expansions

The following cases are notable exceptions to the described substitutions:

• The preprocessor does not recognize comments or macros within the file name delimiters of an

#include

command.

• The preprocessor does not recognize comments or predefined macros within a character or string constant.

Header Files and the #include Command

Header (

.h

) files contain lines of source code to be included (textually inserted) into another source file. Typically, header files contain declarations and macro definitions.


Preprocessor

The

#include

preprocessor command includes a copy of the header file at the location of the command. There are three forms for the

#include command, as described next.

System Header Files

Syntax:

#include <filename>

The file name is placed between a pair of angle bracket characters. The file name in this form is interpreted as a system header file. These files are used to declare global definitions, especially memory-mapped registers, system architecture, and processors.

Example:

#include <device.h>

#include <major.h>

System header files are installed in the

.../VisualDSP/Blackfin/include folder for the processor family.

User Header Files

Syntax:

#include “filename”

The file name is placed within a pair of double quote characters. The file name in this form is interpreted as a user header file. These files contain declarations for interfaces between the source files of the program.

Example:

#include "defTS.h”

#include "fft_ovly.h"



Sequence of Tokens

Syntax:

#include

text

In this case,

text

is a sequence of tokens subject to macro expansion by the preprocessor.

It is an error if after macro expansion the text does not match one of the two header file forms. If the text on the line after the

#include

is not placed between double quotes (as a user header file) or between angle brackets (as a system header file), the preprocessor performs macro expansion on the text. After that expansion, the line requires either of the two header file forms.

L

Unlike most preprocessor commands, the text after the

#include is available for macro expansion.

Examples:

// define preprocessor macro with name for include file

#define includefilename "header.h"

// use the preprocessor macro in a #include command

#include includefilename

// the code above evaluates to #include "header.h"

// define preprocessor macro to build system include file

#define syshdr(name) <name ## .h>

// use the preprocessor macro in a #include command

#include syshdr(adi)

// the code above evaluates to #include <adi.h>


Preprocessor

Include Path Search

It is good programming practice to distinguish between system header files and user header files. The only technical difference between the two different notations is the directory search order that the assembler follows to locate the specified header file.

For example, when using Blackfin processors, the

#include <file>

search order is:

1. The include path specified by the

-I

switch

2.

.../VisualDSP/Blackfin/include

folders

The

#include "file"

search order is:

1. The local directory – the directory in which the source file resides

2. The include path specified by the

-I

switch

3.

...VisualDSP/Blackfin/include

folders

If you use the

-I

and the

-I-

switches on the command line, the system search path (

#include < >

) is modified in such a manner that search the directories specified with the

-I

switch that appear before the directory specified with the

-I-

switch are ignored. For syntax information and usage examples on the

#include

preprocessor command, see

“#include” on page 2-33

.

Writing Macros

The assembler/linker preprocessor processes macros in assembly source files and linker description files (LDF). Macros provide for text substitution.

The term macro defines a macro-identifying symbol and its corresponding definition that the preprocessor uses to substitute the macro reference(s).



For example, use macros to define symbolic constants or to manipulate register bit masks in an assembly program based on a macro argument, as follows:

/* Define a symbolic constant */

#define MAX_INPUT 256

/* Mask peripheral #x interrupt */

#define SIC_MASK(x) (1 << ((x)&0x1F))

Macros can be defined to repeat code sequences in assembly source code.

When you pass parameters to a code macro, the macro serves as a general-purpose routine that is usable in many different programs.

The block of instructions that the preprocessor substitutes can vary with each new set of arguments.

A macro differs from a subroutine call. During assembly, each instance of a macro inserts a copy of the same block of instructions, so multiple copies of that code appear in different locations in the object code.

By comparison, a subroutine appears only once in the object code, and the block of instructions at that location are executed for every call.

For more information, see:

•

“#define” on page 2-23

•

“Macro Definition and Usage Guidelines” on page 2-9

•

“Examples of Multi-Line Code Macros with Arguments” on page 2-12

•

“Debugging Macros” on page 2-13


Preprocessor

Macro Definition and Usage Guidelines

A macro definition can be any text that may occur legally in the source file that references the macro. In assembly files, the macro may expand to include instructions, directives, register names, constants, and so on.

In LDFs, a macro may expand to include LDF commands, memory descriptions and other items that are legal in an LDF. The macro definition may also have other macro names that are replaced with their own definitions.

The following guidelines are provided to help you construct macros and use them appropriately.

• A macro definition must begin with

#define

and must end with a carriage return.

• Macro termination. If a macro definition ends with a terminator on the instruction [one semicolon (

;

) for SHARC and Blackfin processors; two semicolons (

;;

) for TigerSHARC processors], do not place a terminator at the end of the macro (usage) in an assembly statement. However, if a macro definition does not end with a terminator, each instance of the macro usage must be followed by the terminator in the assembly statement.

Be consistent with regard to how you use terminators in macro definitions.

L

Examples shown in this section omit the terminator in the macro definition and use the terminator in the assembly text. Note that the mac;

statement in the following Blackfin example has a “

;

”.

// macro definition

#define mac mrf = mrf+R2*R5(ssfr)

// macro usage

R2 = R1-R0; // set parameters



2-10

R5 = DM(I1,M0); mac;

• Line continuation. A macro definition can be split across multiple lines for readability. When a macro definition is longer than one line, place a backslash (

\

) character at the end of each line (except the last line) for line continuation.

Incorrect

#define MultiLineMacro instruction1; instruction2;

\

\ instruction3

Notice that the backslash in the

#define

line is missing.

Correct

#define MultiLineMacro instruction1; instruction2;

\

\

\ instruction3

No characters are permitted on a line after a backslash.

A warning is generated when there is white space after what might have been intended as a line continuation. For example:

#define macro1 instruction1; instruction2; instruction3

\

\(whitespace)

\

[Warning pp0003] "header.h":3

The backslash at the end of this line is followed by whitespace

It is not a line continuation


Preprocessor

• Comments within #define. Use C-style comments (

/* comment

*

/) within multi-line macros. Otherwise, the line-continuation character (

\

) will cause the next line to be concatenated to the comment, thus becoming part of the comment.

The preprocessor supports C-style comments (

/* comment */

) as well as C++-style comments (

// comment

). The C-style comment has a delimiter at the start and end of the comment; the C++-style comment begins at the “

//

” and terminates at the end of the line.

The “terminates at the end of the line” aspect of C++-style comments renders “

//

” comments unsuitable within multi-line macro definitions. The line continuation character causes the next line to be concatenated to the comment, thus becoming part of the comment.

The following code fragment demonstrates the problem.

#define macro \ first line; second line

\ when expanded by writing “ macro

” in your

.asm

file, this code becomes: first line; second line

If you use C-style comments, you can write:

#define macro

/* this macro has two lines */ first line;

/* and two comments */ second line

\

\

\

\



which will expand to: first line; second line

However, if you use C++ style comments (as shown below),

#define macro \

// this comment will devour the rest of the macro \ first line; second line

\ the macro expands into an “empty” macro.

In the code above, the first line of the macro definition starts a comment. Since there are line-continuation characters, the logical end of line for that comment is the end of the macro. Thus, the code yields an “empty” macro.

• Macro nesting (macros called within another macro) is limited only by the memory available during preprocessing. Recursive macro expansion, however, is not allowed.

Refer also to

“#define” on page 2-23

for reference information on the

#define

command.

Examples of Multi-Line Code Macros with Arguments

The following are examples of multi-line code macros with arguments.

Blackfin Code Example:

#define false 0

#define xchg(xv,yv)

P0=xv;

P1=yv;

R0=[P0];

\

\

\

\


Preprocessor

R1=[P1];

[P1]=R0;

[P0]=R1

SHARC Code Example:

\

\

#define ccall(x)

R2=I6; I6=I7;

JUMP (pc, x) (db); \

DM(I7,M7)=R2; \

DM(I7, M7)=PC

\

\

Macro Usage in Code Section:

<instruction code here> ccall(label1);

<instruction code here> label1: NOP;

<instruction code here>

TigerSHARC Code Example:

#define copy (src,dest)

J0 = src;;

J1 = dest;;

R0 = [J0+0];;

[J1+0] = R0

\

\

\

\

Debugging Macros

If you get an unexpected syntax error from the assembler on a macro expansion, it can be helpful to debug the macro by looking at what the preprocessor produced post preprocessing. The intermediate file produced by the preprocessor is the

.is

output file.



From the VisualDSP++ IDDE, select the Save temporary files check box on the Assemble page of the Project Options dialog box. If you are running the assembler from the command line, add the

-save-temps

switch

(see

“-save-temps” on page 1-162 ).

Tips for Debugging Macros

Assembly programmers may find it useful to include the processor system header files for pre-defined macros that are helpful to assembly language programmers for that processor family. These are known as “ def

headers”.

For example, an ADSP-BF534 programmer would use:

// Header is located in <install_path>/Blackfin/include


A symbol in your program may inadvertently use the same spelling as a

#define

in the def

header. Typically, this results in a syntax error due to the symbol being replaced with a constant or constant expression, which is not what you intended.

For example, defBF534.h

contains:

#define ALARM 0x0002 /* Alarm Interrupt Enable */

If an assembly program uses

ALARM

as a symbol name, it will get a textual replacement of “

0x0002

”, making the program illegal, as demonstrated by the following code fragment.


#define FALSE 0

#define TRUE 1

.SECTION data1;

.VAR ALARM = FALSE;

[Error ea5004] "alarm.asm":7 Syntax Error in :


Preprocessor

.var 0x0002 = 1; syntax error is at or near text '0x0002'.

Attempting error recovery by ignoring text until the ';'

Using Predefined Preprocessor Macros

In addition to macros you define, the pp

preprocessor provides a set of predefined macros and feature macros that can be used in assembly code.

The preprocessor automatically replaces each occurrence of the macro reference found throughout the program with the specified (predefined) value. The DSP development tools also define feature macros that can be used in your code.

L

The

__DATE__

,

__FILE__

, and

__TIME__

macros return strings within the single quotation marks (

‘’

) suitable for initializing character buffers (see

“.VAR and ASCII String Initialization Support” on page 1-136 ).

Table 2-1 describes the common predefined macros provided by the pp preprocessor. Table 2-2 , Table 2-3 , and Table 2-4 list processor-specific feature macros that are defined by the project development tools to specify the architecture and language being processed.



Table 2-1. Common Predefined Preprocessor Macros

Macro

ADI

__LastSuffix__

__LINE__

__FILE__

__TIME__

__DATE__

_LANGUAGE_ASM

_LANGUAGE_C

Definition

Defines

ADI

as 1.

Specifies the last value of suffix that was used to build preprocessor generated labels.

Replaces

__LINE__

with the line number in the source file that the macro appears on.

Defines

__FILE__

as the name and extension of the file in which the macro is defined, for example,

‘macro.asm’

.

Defines

__TIME__

as current time in the 24-hour format

‘hh:mm:ss’

, for example,

‘06:54:35’

.

Defines

__DATE__

as current date in the format

‘mm dd yyyy’

, for example,

‘Oct 02 2000’

.

Always set to 1

Equals 1 when used for C compiler calls to specify .

IMPORT headers. Replaces

_LANGUAGE_ASM

.

Table 2-2. SHARC Feature Preprocessor Macros

Macro

__ADSP21000__

Definition

Always 1 for SHARC processor tools

__ADSP21020__

Present easmts -proc ADSP-21020 with ADSP-21020 processor

__ADSP21060__


__ADSP21061__


__ADSP21062__


__ADSP21065L__ with ADSP-21065L processor

__ADSP21160__



Preprocessor

Table 2-2. SHARC Feature Preprocessor Macros (Cont’d)

Macro

__ADSP21161__


__ADSP2106x__

Definition

__ADSP2116x__

Present when running easmts -proc ADSP-2106x with ADSP-2106x processor

Present when running easmts -proc ADSP-2116x with ADSP-2116x processor

__ADSP21261__

__ADSP21262__

__ADSP21266__

__ADSP21267__

Present when running easmts -proc ADSP-21261 with ADSP-21261 processor




__ADSP21363__

__ADSP21364__

__ADSP21365__

__ADSP21366__

__ADSP21367__

__ADSP21368__

__ADSP21369__










Table 2-3. TigerSHARC Feature Preprocessor Macros

Macro

__ADSPTS__

__ADSPTS101__

__ADSPTS201__

__ADSPTS202__

__ADSPTS203__

Definition

Always 1 for TigerSHARC processor tools

Equal 1 when used with ASDP-TS101 processor




Table 2-4. Blackfin Feature Preprocessor Macros

Macro

__ADSPBLACKFIN__

__ADSPBF522__

__ADSPBF525__

__ADSPBF527__

__ADSPBF532__

__ADSP21532__=1

__ADSPBF533__

__ADSP21533__=1

__ADSPBF534__

__ADSP21534__=1

__ADSPBF535__

__ADSP21535__=1

__ADSPBF536__

__ADSPBF537__

__ADSPBF538__

Definition

Always 1 for Blackfin processor tools

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






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



Preprocessor

Table 2-4. Blackfin Feature Preprocessor Macros (Cont’d)

Macro

__ADSPBF539__

__ADSPBF542__

__ADSPBF544__

__ADSPBF548__

__ADSPBF549__

__ADSPBF561__

Definition







-D__VISUALDSPVERSION____ Predefined Macro (Preprocessor)

The -D__VISUALDSPVERSION__ predefined macro provides VisualDSP++ product version information. The macro allows a pre-processing check to be placed within code. It can be used to differentiate between

VisualDSP++ releases and updates. This macro applies to all Analog

Devices processors. The assemblers and linker predefine

-D__VISUALDSPVERSION__ in calls to the preprocessor.

For further information on the product version encoding (including parameters and examples), see the following:

•

“-D__VISUALDSPVERSION__ Predefined Macro (Assembler)” on page 1-29


Preprocessor Command Reference

Specifying Preprocessor Options

When developing a DSP project, it may be useful to modify the preprocessor’s default options. Because the assembler, compiler, and linker automatically run the preprocessor as your program is built (unless you skip processing entirely), these project development tools can receive input for the preprocessor program and direct its operation. The way the preprocessor options are set depends on the environment used to run the project development software.

You can specify preprocessor options from the preprocessor’s command line or via the VisualDSP++ environment:

• From the operating system command line, select the preprocessor’s command-line switches. For more information on these switches, see

“Preprocessor Command-Line Switches” on page 2-45

.

• In the VisualDSP++ environment, select the preprocessor’s options in the Assemble or Link pages of the Project Options dialog box, accessible from the Project menu. Refer to

“Specifying Assembler

Options in VisualDSP++” on page 1-167 for the Assemble page.

For more information, see the VisualDSP++ 5.0 User’s Guide and

VisualDSP++ online Help.


This section provides reference information about the processor’s preprocessor commands and operators used in source code, including their syntax and usage examples. It provides the summary and descriptions of all preprocessor commands and operators.


Preprocessor

The preprocessor reads code from a source file (

.asm

or

.ldf

), modifies it according to preprocessor commands, and generates an altered preprocessed source file. The preprocessed source file is an input file for the assembler or linker; it is purged when a binary object file (

.doj

) is created.

Preprocessor command syntax must conform to these rules:

• Must be the first non-whitespace character on its line

• Cannot be more than one line in length unless the backslash character (

\

) is inserted

• Cannot come from a macro expansion

The preprocessor operators are defined as special operators when used in a

#define

command.

Preprocessor Commands and Operators

Table 2-5

lists preprocessor commands. Table 2-6 lists preprocessor

operators. Sections that begin

on page 2-23

describe each of the preprocessor commands and operators.

Table 2-5. Preprocessor Command Summary

Command/Operator

#define

(

on page 2-23 )

#elif

(

on page 2-26 )

#else

(

on page 2-27 )

#endif

(

on page 2-28 )

#error

(

on page 2-29 )

#if

(

on page 2-30 )

#ifdef

(

on page 2-31 )

Description

Defines a macro

Subdivides an

#if … #endif pair

Identifies alternative instructions within an

#if … #endif

pair

Ends an

#if … #endif pair

Reports an error message

Begins an

#if … #endif pair

Begins an

#ifdef … #endif

pair and tests if macro is defined



Table 2-5. Preprocessor Command Summary


#ifndef

(

on page 2-32 )

Description

Begins an

#ifndef … #endif

pair and tests if macro is not defined

#include

(

on page 2-33 )

Includes contents of a file

#line

(

on page 2-35 )

#pragma

(

on page 2-36 )

Sets a line number during preprocessing

Takes any sequence of tokens

#undef

(

on page 2-37 )

Removes macro definition

#warning

(

on page 2-38 )

Reports a warning message

Table 2-6. Preprocessor Operator Summary


#

( on page 2-39

)

##

(

on page 2-41 )

?

(

on page 2-42 )

... ( on page 2-24 )

Description

Converts a macro argument into a string constant.

By default, this operator is OFF. Use the command-line switch

“-stringize” on page 2-53

to enable it.

Concatenates two tokens

Generates unique labels for repeated macro expansions

Specifies a variable-length argument list


Preprocessor

#define

The

#define

command defines macros.

When defining macros in your source code, the preprocessor substitutes each occurrence of the macro with the defined text. Defining this type of macro has the same effect as using the Find/Replace feature of a text editor, although it does not replace literals in double quotation marks

(

“ “

) and does not replace a match within a larger token.

For macro definitions longer than one line, place a backslash character (

\

) at the end of each line (except the last line) for readability; refer to the macro definition rules in

“Writing Macros” on page 2-7 .

You can add arguments to the macro definition. The arguments are symbols separated by commas that appear within parentheses.

Syntax:

#define

macroSymbol replacementText

#define

macroSymbol[(arg1,arg2,…)] replacementText

where

macroSymbol

– macro identifying symbol

replacementText

– text to substitute each occurrence of

macroSymbol

in your source code



Examples:

#define BUFFER_SIZE 1020

/* Defines a macro named BUFFER_SIZE and sets its value to 1020. */

#define copy(src,dest)xr0=[J31+src ];; \

[J31+dest] = xr0;;

/* define a macro named copy with two arguments.

The definition includes two instructions that copy a word from memory to memory.

For example, copy (0x3F,0xC0); calls the macro, passing parameters to it.

The preprocessor replaces the macro with the code:

[xr0 = [j31+0x3F];;

[j31+0xC0] = xr0;;

*/

Variable-Length Argument Definitions

A macro can also be defined with a variable-length argument list

(by means of the

...

operator).

#define test(a, ...)

<definition>

For example, the code above defines a macro named test

, which takes two or more arguments. It is invoked like any other macro, although the number of arguments can vary.

For example, in the macro definition, the

__VA_ARGS__

identifier is available to take on the value of all of the trailing arguments, including the commas, all of which are merged to form a single item. See Table 2-7 .


Preprocessor

Table 2-7. Sample Variable-Length Argument List

Sample Argument List

test(1) test(1,2) test(1,2,3,4,5)

Description

Error; the macro must have at least one more argument than formal parameters, not counting “...”

Valid entry

Valid entry

For example, the following code

#define test(a, ...) bar(a); testbar(__VA_ARGS__); expands into: test (1,2) -> bar(1); testbar(2); test (1,2,3,4,5) -> bar(1); testbar(2,3,4,5);



#elif

The

#elif

command (else if) is used within an

#if

…

#endif

pair.

The

#elif

includes an alternative condition to test when the initial

#if condition evaluates as

FALSE

. The preprocessor tests each

#elif

condition inside the pair and processes instructions that follow the first true

#elif

.

There can be an unlimited number of

#elif

commands inside one

#if

…

#end pair.

Syntax:

#elif condition where

condition

– expression to evaluate as

TRUE

(nonzero) or

FALSE

(zero)

Example:

#if X == 1

...

#elif X == 2

...

/* The preprocessor includes text within the section

#else and excludes all other text before #else when X=2. */

#endif


Preprocessor

#else

The

#else

command is used within an

#if

…

#endif

pair. It adds an alternative instruction to the

#if

…

#endif

pair. Only one

#else

command can be used inside the pair. The preprocessor executes instructions that follow

#else

after all the preceding conditions are evaluated as

FALSE

(zero). If no

#else

text is specified, and all preceding

#if

and

#elif conditions are

FALSE

, the preprocessor does not include any text inside the

#if

…

#endif

pair.

Syntax:

#else

Example:

#if X == 1

...

#elif X == 2

...

#else

...

/* The preprocessor includes text within the section and excludes all other text before #else when x!=1 and x!=2. */

#endif



#endif

The

#endif

command is required to terminate

#if

…

#endif

,

#ifdef

…

#endif

, and

#ifndef

…

#endif

pairs. Ensure that the number of

#if

commands matches the number of

#endif

commands.

Syntax:

#endif

Example:

#if condition

...

...

#endif

/* The preprocessor includes text within the section only if the test is true */


Preprocessor

#error

The

#error

command causes the preprocessor to raise an error. The preprocessor uses the text following the

#error

command as the error message.

Syntax:

#error messageText where

messageText

– user-defined text

To break a long

messageText

without changing its meaning, place a backslash character (

\

) at the end of each line (except the last line).

Example:

#ifndef __ADSPBF535__

#error \

MyError: \

Expecting a ADSP-BF535. \

Check the Linker Description File!

#endif



#if

The

#if

command begins an

#if

…

#endif

pair. Statements inside an

#if

…

#endif

pair can include other preprocessor commands and conditional expressions. The preprocessor processes instructions inside the

#if

…

#endif pair only when

condition

that follows the

#if

evaluates as

TRUE

. Every

#if

command must terminated with an

#endif

command.

Syntax:

#if condition where

condition

– expression to evaluate as

TRUE

(nonzero) or

FALSE

(zero)

Example:

#if x!=100

…

/* test for TRUE condition */

/* The preprocessor includes text within the section if the test is true. */

#endif

More examples:

#if (x!=100) && (y==20)

#if defined(__ADSPBF535__)


Preprocessor

#ifdef

The

#ifdef

(if defined) command begins an

#ifdef

…

#endif

pair and instructs the preprocessor to test whether the macro is defined. Each

#ifdef

command must have a matching

#endif

command.

Syntax:

#ifdef

macroSymbol

where

macroSymbol


Example:

#ifdef __ADSPBF535__

/* Includes text after #ifdef only when __ADSPBF535__ has been defined */

#endif



#ifndef

The

#ifndef

(if not defined) command begins an

#ifndef

…

#endif pair and directs the preprocessor to test for an undefined macro. The preprocessor considers a macro undefined if it has no defined value.

Each

#ifndef

command must have a matching

#endif

command.

Syntax:

#ifndef

macroSymbol

where

macroSymbol


Example:


#endif

/* Includes text after #ifndef only when __ADSPBF535__ is not defined */


Preprocessor

#include

The

#include

command directs the preprocessor to insert the text from a header file at the command location. There are two types of header files: system and user. However, the

#include

command may be presented in three forms:

•

#include <filename>

– used with system header files

•

#include “filename”

– used with user header files

•

#include

text

– used with a sequence of tokens

The sequence of tokens is subject to macro expansion by the preprocessor. After macro expansion, the text must match one of the header file forms.

The only difference to the preprocessor between the two types of header files is the way the preprocessor searches for them.

• System Header File

<fileName>

– The preprocessor searches for a system header file in this order: (1) the directories you specify, and

(2) the standard list of system directories.

• User Header File “

fileName

” – The preprocessor searches for a user header file in this order:

1. Current directory – the directory where the source file that has the

#include

command(s) lives

2. Directories you specify

3. Standard list of system directories

L

Refer to

“Header Files and the #include Command” on page 2-4 for more information.



Syntax:

#include <fileName>

#include "fileName"

// include a system header file

// include a user header file

#include macroFileNameExpansion

/* Include a file named through macro expansion.

This command directs the preprocessor to expand the macro. The preprocessor processes the expanded text, which must match either <fileName> or "fileName". */

Example:

#ifdef __ADSPBF535__

/* Tests that __ADSPBF535__ has been defined */

#include <stdlib.h>

#endif


Preprocessor

#line

The

#line

command directs the preprocessor to set the internal line counter to the specified value. Use this command for error tracking purposes.

Syntax:

#line lineNumber

“sourceFile”

where

lineNumber

– line number of the source line

sourceFile

– name of the source file included in double quotation marks.

The

sourceFile

entry can include the drive, directory, and file extension as part of the file name.

Example:

#line 7 “myFile.c”

L

All assembly programs have

#line

directives after preprocessing.

They always have a first line with

#line 1 "filename.asm"

and they will also have

#line

directives to establish correct line numbers for text that came from include files as a result of the processed

#include

directives.



#pragma

The

#pragma

command is the implementation-specific command that modifies the preprocessor behavior. The

#pragma

command can take any sequence of tokens. This command is accepted for compatibility with other VisualDSP++ software tools. The pp

preprocessor currently does not support any pragmas; therefore, it ignores any information in the

#pragma command.

Syntax:

#pragma

any_sequence_of_tokens

Example:

#pragma disable_warning 1024


Preprocessor

#undef

The

#undef

command directs the preprocessor to undefine a macro.

Syntax:

#undef

macroSymbol

where

macroSymbol

– macro created with the

#define

command

Example:

#undef BUFFER_SIZE /* undefines a macro named BUFFER_SIZE */



#warning

The

#warning

command causes the preprocessor to issue a warning. The preprocessor uses the text following the

#warning

command as the warning message.

Syntax:

#warning

messageText

where

messageText

– user-defined text

To break a long

messageText

without changing its meaning, place a backslash character (

\

) at the end of each line (except the last line).

Example:


#warning \

MyWarning: \

Expecting a ADSPBF535. \

#endif

Check the Linker Description File!


Preprocessor

# (Argument)

The

#

(argument) “stringization” operator directs the preprocessor to convert a macro argument into a string constant. The preprocessor converts an argument into a string when macro arguments are substituted into the macro definition.

The preprocessor handles white space in string-to-literal conversions by:

• Ignoring leading and trailing white spaces

• Converting white space in the middle of the text to a single space in the resulting string

Syntax:

# toString where

toString

– macro formal parameter to convert into a literal string. The

# operator must precede a macro parameter. The preprocessor includes a converted string within double quotation marks (

“ ”

).

L

This feature is “off” by default. Use the

“-stringize” command-line

switch (

on page 2-53

) to enable it.

C Code Example:

#define WARN_IF(EXP)\ fprintf (stderr,"Warning:"#EXP "/n")

/* Defines a macro that takes an argument and converts the argument to a string */

WARN_IF(current <minimum);

/* Invokes the macro passing the condition. */ fprintf (stderr,"Warning:""current <minimum""/n");



/* Note that the #EXP has been changed to current <minimum and is enclosed in “ ” */


Preprocessor

## (Concatenate)

The

##

(concatenate) operator directs the preprocessor to concatenate two tokens. When you define a macro, you request concatenation with

##

in the macro body. The preprocessor concatenates the syntactic tokens on either side of the concatenation operator.

Syntax:

token1##token2

Example:

#define varstring(name) .VAR var_##name[] = {‘name’, 0}; varstring (error); varstring (warning);

/* The above code results in */

.VAR var_error[] = {‘error’, 0};

.VAR var_warning[] = {‘warning’, 0};



? (Generate a unique label)

The “

?

” operator directs the preprocessor to generate unique labels for iterated macro expansions. Within the definition body of a macro

(

#define

), you can specify one or more identifiers with a trailing question mark (

?

) to ensure that unique label names are generated for each macro invocation.

The preprocessor affixes “

_num

” to a label symbol, where num

is a uniquely generated number for every macro expansion. For example: abcd? ===> abcd_1

If a question mark is a part of the symbol that needs to be preserved, ensure that “

?

” is delimited from the symbol. For example, abcd?

” is a generated label, and “ abcd ?

” is not.

Example:

#define loop(x,y) mylabel?:x =1+1;/ x = 2+2;/ yourlabel?:y =3*3;/ y = 5*5;/

JUMP mylabel?;/

JUMP yourlabel?; loop (bz,kjb) loop (lt,ss) loop (yc,jl)

// Generates the following output: mylabel_1:bz =1+1;bz =2+2;yourlabel_1:kjb =3*3;kjb = 5*5;

JUMP mylabel_1;

JUMP yourlabel_1; mylabel_2:lt =1+1;lt =2+2;yourlabel_2:ss =3*3;ss =5*5;

JUMP mylabel_2;


Preprocessor

JUMP yourlabel_2; mylabel_3:yc =1+1;yc =2+2;yourlabel_3:Jl =3*3;Jl =5*5;

JUMP mylabel_3;

JUMP yourlabel_3;

The last numeric suffix used to generate unique labels is maintained by the preprocessor and is available through a preprocessor predefined macro

__LastSuffix__

(see on page 2-16 ). This value can be used to generate references to labels in the last macro expansion.

The following example assumes the macro “ loop

” from the previous example.

// Some macros for appending a suffix to a label

#define makelab(a, b) a##b

#define Attach(a, b) makelab(a##_, b)

#define LastLabel(foo) Attach( foo, __LastSuffix__)

// jump back to label in the previous expansion

JUMP LastLabel(mylabel);

The above expands to (the last macro expansion had a suffix of 3):

JUMP mylabel_3;


Preprocessor Command-Line Reference


The pp

preprocessor is the first step in the process of building (assembling, compiling, and linking) your programs. The pp

preprocessor is run before the assembler and linker, using the assembler or linker as the commandline tool. You can also run the preprocessor independently from its own command line.

This section contains:

•

“Running the Preprocessor”

•

“Preprocessor Command-Line Switches” on page 2-45

Running the Preprocessor

To run the preprocessor from the command line, type the name of the program followed by arguments in any order.

pp

[-switch1 [-switch2 … ]] [sourceFile]

Table 2-8 summarizes these arguments.

Table 2-8. Preprocessor Command Line Argument Summary

Argument

pp

-switch sourceFile

Description

Name of the preprocessor program

Switch (or switches) to process. The preprocessor offers several switches that are used to select its operation and modes. Some preprocessor switches take a file name as a required parameter.

Name of the source file to process. The preprocessor supports relative path names and absolute path names. The pp.exe

outputs a list of command-line switches when runs without this argument.


Preprocessor

For example, the following command line pp -Dfilter_taps=100 -v -o bin/p1.is p1.asm

runs the preprocessor with:

-Dfilter_taps=100

– defines the macro filter_taps

as equal to

100

-v

– displays verbose information for each phase of the preprocessing

-o bin\p1.is

– specifies the name and directory for the intermediate preprocessed file p1.asm

– specifies the assembly source file to preprocess

L

Most switches without arguments can be negated by prefixing

-no to the switch. For example,

-nowarn

turns off warning messages, and

-nocs!

turns off omitting “

!

” style comments.

Preprocessor Command-Line Switches

The preprocessor is controlled through the switches (or VisualDSP++ options) of other DSP development tools, such as the compiler, assembler, and linker. Note that the preprocessor ( pp.exe

) can operate independently from the command line with its own command-line switches.

Table 2-9 lists pp.exe

switches. A detailed description of each switch appears beginning

on page 2-47 .

Table 2-9. Preprocessor Command-Line Switch Summary

Switch Name

-cstring

on page 2-47

Description

Enables the “stringization” operator and provides C compiler-style preprocessor behavior



Table 2-9. Preprocessor Command-Line Switch Summary (Cont’d)

Treats as a comment all text after “

!

” on a single line

-cs!

on page 2-48

-cs/*

on page 2-48

-cs//

on page 2-49

-cs{

on page 2-49

-csall

on page 2-49

–Dmacro[=definition]

on page 2-49

-h[elp]

on page 2-49

–i

on page 2-50

–i|Idirectory

on page 2-50

–l

on page 2-51

-M

on page 2-52

-MM

on page 2-52

-Mo filename

on page 2-52

-Mt filename

on page 2-53

–o filename

on page 2-53

–stringize

on page 2-53

Treats as a comment all text within

/* */

Treats as a comment all text after

//

Treats as a comment all text within

{ }

Accepts comments in all formats

Defines

macro

Outputs a list of command-line switches

Outputs only makefile dependencies for include

files specified in double quotes

Searches

directory

for included files

Indicates where to start searching for system include files, which are delimited by < >

Makes dependencies only

Makes dependencies and produces preprocessor output

Specifies

filename

for the make dependencies output file

Makes dependencies for the specified source file

Outputs named object file

Enables stringization (includes a string in double quotes)


Preprocessor

Table 2-9. Preprocessor Command-Line Switch Summary (Cont’d)

Treats “.” (dot) as an operator when parsing identifiers

–tokenize-dot

(

on page 2-53

)

–Uname

on page 2-54

–v[erbose]

on page 2-54

–version

on page 2-54

w

on page 2-54

-

Wnumber

on page 2-55

-warn

on page 2-55

Undefines a macro on the command line

Displays information about each preprocessing phase

Displays version information for the preprocessor

Removes all preprocessor-generated warnings

Suppresses any report of the specified warning

Prints warning messages (default)

The following sections describe preprocessor’s command-line switches.

-cstring

The

-cstring

switch directs the preprocessor to produce C compiler style strings in all cases. By default, the preprocessor produces assembler-style strings within single quotes (for example,

‘string’

) unless the

-cstring switch is used.

The

-cstring

switch sets the following C compiler-style behaviors:

• Directs the preprocessor to use double quotation marks rather than the default single quotes as string delimiters for any preprocessor- generated strings. The preprocessor generates strings for predefined



macros that are expressed as string constants, and as a result of the stringize operator in macro definitions (see Table 2-1 on page 2-16 for the predefined macros).

• Enables the stringize operator (

#

) in macro definitions. By default, the stringize operator is disabled to avoid conflicts with constant definitions (see

“-stringize” on page 2-53 ).

• Parses identifiers using C language rules instead of assembler rules.

In C, the character “

.

” is an operator and is not considered part of an identifier. In the assembler, the “

.

” is considered part of a directive or label. With

-cstring

, the preprocessor treats “

.

” as an operator.

The following example shows the difference in effect of the two styles.

#define end last

// what label.end looks like with -cstring label.last

// "end" parsed as ident and macro expanded

// what label.end looks like without -cstring (asm rules) label.end

// "end" not parsed separately

-cs!

The

-cs!

switch directs the preprocessor to treat as a comment all text after “

!

” on a single line.

-cs/*

The

-cs/*

switch directs the preprocessor to treat as a comment all text within

/* */

on multiple lines.


Preprocessor

-cs//

The

-cs//

switch directs the preprocessor to treat as a comment all text after

//

on a single line.

-cs{

The

-cs{

switch directs the preprocessor to treat as a comment all text within

{ }

on multiple lines..

-csall

The

-csall

switch directs the preprocessor to accept comments in all formats.

-Dmacro[=def]

The

-Dmacro

switch directs the preprocessor to define a macro

. If you do not include the optional definition string (

=def

), the preprocessor defines the macro as value 1. Similar to the C compiler, you can use the

-D

switch to define an assembly language constant macro.

Some examples of this switch are:

-Dinput // defines input as 1

–Dsamples=10

–Dpoint="Start"

–D_LANGUAGE_ASM=1

// defines samples as 10

// defines point as “Start”

// defines _LANGUAGE_ASM as 1

-h[elp]

The

-h

(or

-help

) switch directs the preprocessor to send to standard output the list of command-line switches with a syntax summary.



-i

The

-i

(less includes) switch may be used with the

-M

or

-MM

switches to direct the preprocessor to not output dependencies on any system files.

System files are any files that are brought in using

#include < >

. Files included using

#include " "

(double quote characters) are included in the dependency list.

-i

The

-idirectory

(or

-Idirectory

) switch direct the preprocessor to append the specified directory (or a list of directories separated by semicolons) to the search path for included header files

(see

on page 2-33 ).

L

No space is allowed between

-i

and the path name.

The preprocessor searches for included files delimited by double quotation marks (

“ ”

) in this order:

1. The source directory (that is, the directory in which the original source file resides)

2. The directories in the search path supplied by the

-I

switch. If more than one directory is supplied by the

-I

switch, they are searched in the order that they appear on the command line.

3. The system directory (that is, the

.../include

subdirectory of the

VisualDSP++ installation directory)

L

The current directory is the directory where the source file lives, not the directory of the assembler program. Usage of full path names for the

-I

switch on the command line (omitting the disk partition) is recommended.


Preprocessor

The preprocessor searches for included files delimited by

< >

in this order:

1. The directories in the search path supplied by the

-I

switch (subject to modification by the

-I-

switch, as shown in

“-I-” on page 2-51

. If more than one directory is supplied by the

-I

switch, the directories are searched in the order that they appear on the command line.

2. The system directory (that is, the

...\include

subdirectory of the

VisualDSP++ installation directory.

-I-

The

-I-

switch indicates where to start searching for system include files, which are delimited by

< >

. If there are several directories in the search path, the

-I-

switch indicates where in the path the search for system include files begins.

For example: pp -Idir1 -Idir2 -I- -Idir3 -Idir4 myfile.asm

When searching for

#include "inc1.h"

the preprocessor searches in the source directory, then dir1

, dir2

, dir3

, and dir4

in that order.

When searching for

#include <inc2.h>

the preprocessor searches for the file in dir3

and then dir4

. The

-I-

switch marks the point where the system search path starts.



-M

The

-M

switch directs the preprocessor to output a rule (generate make rule only) suitable for the make utility, describing the dependencies of the source file. The output, a make dependencies list, is written to stdout

in the standard command-line format.

“target_file”: “dependency_file.ext” where

dependency_file.ext

may be an assembly source file or a header file included with the

#include

preprocessor command

When the

“-o filename” switch is used with

-M

, the

-o

option is ignored.

To specify an alternate target name for the make dependencies, use the

“-Mt filename”

option. To direct the make dependencies to a file, use the

“-Mo filename”

option.

-MM

The

-MM

switch directs the preprocessor to output a rule (generate make rule and preprocess) suitable for the make utility, describing the dependencies of the source file. The output, a make dependencies list, is written to stdout

in the standard command-line format.

The only difference between

-MM

and

-M

actions is that the preprocessing continues with

-MM

. See

“-M” for more information.

-Mo filename

The

-Mo

switch specifies the name of the make dependencies file (output make rule) that the preprocessor generates when using the

-M

or

-MM switch. The switch overrides default of make dependencies to stdout

.


Preprocessor

-Mt filename

The

-Mt

switch specifies the name of the target file (output make rule for the named source) for which the preprocessor generates the make rule using the

-M

or

-MM

switch. The

-Mt

fileneme

switch overrides the default

filename

.is

file. See

“-M”


-o filename

The

-o

switch directs the preprocessor to use (output) the specified

filename

argument for the preprocessed assembly file. The preprocessor directs the output to stdout

when no

-o

option is specified.

-stringize

The

-stringize

switch enables the preprocessor stringization operator.

By default, this switch is off. When set, this switch turns on the preprocessor stringization functionality (see

“# (Argument)” on page 2-39

) which, by default, is turned off to avoid possible undesired stringization.

For example, there is a conflict between the stringization operator and the assembler’s boolean constant format in the following macro definition:

#define bool_const b#00000001

-tokenize-dot

The

-tokenize-dot

switch parses identifiers using C language rules instead of assembler rules, without the need of other C semantics

(see

“-cstring” on page 2-47

for more information).

When the

-tokenize-dot

switch is used, the preprocessor treats “

.

” as an operator and not as part of an identifier. If the

-notokenize-dot

switch is used, it returns the preprocessor to the default behavior. The only benefit



to the negative version is that if it appears on the command line after the

-cstring

switch, it can turn off the behavior of “

.

” without affecting other C semantics.

-Uname

The

-Uname

switch directs the preprocessor to undefine a macro on the command line. The “undefine macro” switch applies only to macros that were defined on the same command line. The functionality provides a way for users to undefine feature macros specified by the assembler or linker.

-v[erbose]

The

-v[erbose]

switch directs the preprocessor to output the version of the preprocessor program and information for each phase of the preprocessing.

-version

The

-version

switch directs the preprocessor to display version information for the preprocessor program.

L

The

-version

switch on the assembler command line provides version information for both the assembler and preprocessor.

The

-version

switch on the preprocessor command line provides preprocessor version information only.

-w

The

-w

(disable all warnings) switch directs the assembler not to display warning messages generated during assembly. Note that

-w

has the same effect as the

-nowarn

switch.


Preprocessor

-Wnumber

The

-Wnumber

(warning suppression) switch selectively disables warnings specified by one or more message numbers. For example,

-W74

disables warning message pp0074

.

-warn

The

-warn

switch generates (prints) warning messages (this switch is on by default). The

-nowarn

switch option negates this action.




I INDEX

Symbols

? preprocessor operator,

2-42

Numerics

1.0r fract,

1-57

1.15 fract, 1-55 ,

1-56

1.31 fract, 1-56

1.31 fracts, 1-77

32-bit initialization

used with 1.31 fracts, 1-77

A

absolute address,

1-63

address alignment,

1-71

ADDRESS () assembler operator, 1-51

ADI macro, 2-16

__ADSP21000__ macro, 2-16

__ADSP21020__ macro, 2-16

__ADSP21060__ macro, 2-16

__ADSP21061__ macro, 2-16

__ADSP21062__ macro, 2-16

__ADSP21065L__ macro,

2-16

__ADSP2106x__ macro, 2-17

__ADSP21160__ macro, 2-16

__ADSP21161__ macro, 2-17

__ADSP2116x__ macro, 2-17

__ADSP21261__ macro, 2-17

__ADSP21262__ macro, 2-17

__ADSP21266__ macro, 2-17

__ADSP21267__ macro, 2-17


__ADSP21363__ macro,

2-17


2-17


2-17


2-17


2-17


2-17

__ADSPBF522__ macro,

2-18


2-18


2-18


2-18


2-18


2-18


2-18


2-18


2-18


2-18


2-19


2-19

__ADSPBLACKFIN__ macro, 2-18

__ADSPTS101__ macro,

2-18


2-18


2-18


2-18

__ADSPTS__ macro, 2-18

.ALIGN (address alignment) assembler directive,

1-71

-align-branch-lines assembler switch,

1-146

.ALIGN_CODE (code address alignment) assembler directive,

1-73

aligning branch instructions, 1-146

-anomaly-detect assembler switch, 1-147

, 1-159

-anomaly-warn assembler switch, 1-147

I-1

INDEX

anomaly warnings, displaying,

1-147 ,

1-148

,

1-159 ,

1-160

-anomaly-workaround assembler switch,

1-148

archiver, object file input to,

1-5

arithmetic fractional,

1-57

mixed fractional, 1-58

ASCII string directive,

1-75

string initialization,

1-78 ,

1-113

,

1-136

.ASCII assembler directive,

1-66

,

1-75

.asm files, 1-3

assembler

Blackfin feature macros, 1-27

command-line syntax,

1-140

debugging syntax errors, 2-13

directive syntax, 1-6

,

1-66

expressions, constant and address, 1-49

file extensions, 1-141

instruction set,

1-6

keywords, 1-36 ,

1-40

,

1-44

numeric bases,

1-55

operators,

1-50

overview,

1-3

predefined macros, 1-25 ,

1-27

producing code suitable for the specified processor,

1-161

program content, 1-6

running from command line, 1-140

run-time environment,

1-2

SHARC feature macros,

1-25

source files (.ASM),

1-4

assembler

special operators, 1-52

symbols,

1-47

(continued)

TigerSHARC feature macros, 1-27

assembler directives

.ALIGN,

1-71

.ALIGN_CODE,

1-73

.ASCII, 1-75

.BSS,

1-66

.BYTE/.BYTE2/.BYTE4, 1-76

conditional, 1-58

.DATA, 1-67

.EXTERN, 1-80

.EXTERN STRUCT,

1-81

.FILE_ATTR,

1-84

.FILE (override filename),

1-83

.GLOBAL, 1-85

.GLOBL,

1-67

.IMPORT, 1-87

.INCBIN, 1-68

.INC/BINARY,

1-90

.LEFTMARGIN,

1-91

.LIST,

1-92

.LIST_DATA, 1-93

.LIST_DATFILE, 1-94

.LIST_DEFTAB,

1-95

.LIST_LOCTAB,

1-97

.LIST_WRAPDATA,

1-98

.LONG, 1-99

.MESSAGE, 1-100

.NEWPAGE, 1-104

,

1-116

.NOLIST, 1-92

.NOLIST_DATA, 1-93

.NOLIST_DATFILE,

1-94

.NOLIST_WRAPDATA,

1-98

.PAGELENGTH, 1-105

.PAGEWIDTH,

1-106

.PORT,

1-108 ,

1-115

.PRECISION, 1-109

I-2 VisualDSP++ 5.0 Assembler and Preprocessor Manual

INDEX

assembler directives

.PREVIOUS,

1-111

.PRIORITY,

1-112

.ROUND_MINUS, 1-117

.ROUND_NEAREST,

1-117

.ROUND_PLUS, 1-117

.ROUND_ZERO, 1-117

.SECTION,

1-120

(continued)

.SEGMENT/.ENDSEG, 1-126

.SEPARATE_MEM_SEGMENTS,

1-126

,

1-127

.SET,

1-70

.SHORT,

1-127

.SHORT EXPRESSION-LIST, 1-70

.STRUCT, 1-128

.TEXT,

1-70

.TYPE, 1-132

.VAR,

1-133

.WEAK, 1-138

assembler switches

-align-branch-lines,

1-146

-anomaly-detect,

1-147

,

1-159

-anomaly-warn,

1-147

-anomaly-workaround,

1-148

-char-size-32, 1-148

-char-size-8,

1-148

-char-size-any,

1-149

-D (define macro), 1-149

-D (defines) option for the

-flags-compiler switch, 1-152

-default-branch-np,

1-149

-default-branch-p, 1-149

-double-size-32, 1-150

-double-size-64, 1-150

-double-size-any,

1-151

-expand-symbolic-links,

1-151

-expand-windows-shortcuts,

1-151

-flags-compiler, 1-151

-flags-pp, 1-153

-g (generate debug info), 1-154

VisualDSP++ 5.0 Assembler and Preprocessor Manual assembler switches

-h (help), 1-155

(continued)

-i (include directory path), 1-156

-I (include search path) option for the

-flags-compiler switch,

1-153

-li (listing with include),

1-157

-l (named listing file), 1-157

-micaswarn, 1-159

-M (make rule only), 1-157

-MM (generate make rule and assemble),

1-158

-Mo (output make rule),

1-158

-Mt (output make rule for named

object), 1-158

--no-anomaly-workaround,

1-159

-no-expand-symbolic-links, 1-160

-no-expand-windows-shortcuts,

1-160

-no-source-dependency, 1-159

-no-temp-data-file,

1-160

-o (output), 1-161

-pp (proceed with preprocessing),

1-161

-proc processor, 1-161

-save-temps (save intermediate files),

1-162

-si-revision version (silicon revision),

1-162

-sp (skip preprocessing), 1-163

-stallcheck,

1-163

-version (display version),

1-164

-v (verbose),

1-163

-Werror number, 1-164

-Winfo number (informational

messages), 1-164

-Wno-info (no informational messages),

1-165

-Wnumber (warning suppression), 1-165

-w (skip warning messages), 1-164

-Wsuppress number, 1-165

-Wwarn-error, 1-165

-Wwarn number,

1-165

I-3

INDEX

assembly code, embedding (inline) in your

C or C++ program,

1-20

assembly language constant, 2-49

assembly language programs, writing, 1-3

attributes, creating in object files, 1-84

B

backslash character,

2-23

binary files, including, 1-68

BITPOS() assembler operator, 1-51 ,

1-52

block initialization section qualifiers, 1-123

branch

instructions, 1-146

,

1-149 target buffer, 1-149

branch lines default to NP,

1-149

.BSS assembler directive, 1-66

built-in functions

OFFSETOF, 1-60

,

1-62

SIZEOF,

1-60 ,

1-62

.BYTE4/R32 assembler directive, for 32-bit

initialization, 1-77

.BYTE/ .BYTE2/ .BYTE4 assember

directives, 1-76

C

C/C++ run-time library, initializing, 1-124

CHAR32 section qualifier,

1-122

CHAR8 section qualifier, 1-122

CHARANY section qualifier, 1-122

-char-size-32 assembler switch,

1-148

-char-size-8 assembler switch, 1-148

-char-size-any assembler switch, 1-149

circular buffers, setting, 1-53

,

1-54

comma-separated options, 1-153

## (concatenate) preprocessor operator,

2-41

concatenate (##) preprocessor operator,

2-41

I-4 conditional assembly directives

.ELIF, 1-58

.ELSE, 1-59

.ENDIF, 1-59

.IF, 1-58

constant expressions,

1-49

conventions comment strings,

1-58

file extensions, 1-141 file names, 1-141

numeric formats,

1-55

user-defined symbols,

1-47

-cpredef (C-style definitions) preprocessor

switch, 2-48

C programs

interfacing assembly, 1-20

C++ programs

interfacing assembly, 1-20

-csall (all comment styles) preprocessor

switch, 2-49

-cs! (! comment style) preprocessor switch,

2-48

-cs/* (/* */ comment style) preprocessor

switch, 2-48

-cs// (// comment style) preprocessor

switch, 2-49

-cs{ ({ } comment style) preprocessor

switch, 2-49

-cstring (C style) preprocessor switch, 2-47

C structs, in assembly source, 1-20

custom processors, 1-162

D

-D__2102x__ macro,

1-25

-D__2106x__ macro,

1-25

-D__2116x__ macro,

1-25

-D__2126x__ macro,

1-25 ,

1-26

-D__2136x__ macro,

1-26

-D__2636x__ macro,

1-26

-D__ADSP21000__ macro, 1-25


INDEX

-D__ADSP21020__ macro,

1-25

-D__ADSP2116x__ macro,

1-25


1-26


1-26


1-26


1-26

-D__ADSPBF531__ macro, 1-28



,

1-28







-D__ADSPBLACKFIN__ macro,

1-27

-D__ADSPTS101__ macro, 1-27




-D__ADSPTS20x__ macro,

1-27

-D__ADSPTS__ macro,

1-27

DATA64 (64-bit word section) qualifier,

1-123

.DATA assembler directive,

1-67

__DATE__ macro, 2-16

.dat files,

1-3 ,

1-141

-D (define macro) assembler switch,

1-149

-D (define macro) preprocessor switch,

2-49

-D (defines) command-line option,

see-flags-compiler switch debugging

assembler syntax errors, 2-13

information, generating,

1-154

tips for macros, 2-14

-default-branch-np assembler switch, 1-149

-default-branch-p assembler switch,

1-149

#define (macro) preprocessor command,

2-9 ,

2-23

defines (-D) options, 1-152

defining macros,

2-9

,

2-23

dependencies, from buffer initializations,

1-31

directives, assembler,

1-66

-D_LANGUAGE_ASM macro,

1-25 ,

1-27

,

2-16

-D_LANGUAGE_C macro,

1-29 ,

2-16

.dlb files,

1-5

DMAONLY section qualifier,

1-123

DM (data), 40-bit word section qualifier,

1-123

.doj files,

1-3

,

1-5

DOUBLE32 section qualifier, 1-121

DOUBLE64 section qualifier, 1-121

DOUBLEANY section qualifier,

1-121

-double-size-32 assembler switch, 1-150

-double-size-64 assembler switch, 1-150

-double-size-any assembler switch,

1-151

DWARF2 function information, 1-154

E

easm21k assembler driver,

1-2

easmblkfn assembler driver,

1-2

easmts assembler driver,

1-2

ELF.h header file,

1-121

ELF section types, 1-121

.ELIF conditional assembly directive, 1-58

#elif (else if) preprocessor command, 2-26

#else (alternate instruction) preprocessor command,

2-27

.ELSE conditional assembly directive, 1-59

.ENDIF conditional assembly directive,

1-59

#endif (termination) preprocessor command,

2-28

end labels marking ending function boundaries,

1-33

missing, 1-154

VisualDSP++ 5.0 Assembler and Preprocessor Manual I-5

INDEX

end of a function, 1-154

.ENDSEG assembler directive,

1-126

#error (error message) preprocessor command,

2-29

-expand-symbolic-links assembler switch,

1-151

-expand-windows-shortucts assembler

switch, 1-151

expressions address,

1-50

constant, 1-49

.EXTERN (global label) assembler

directive, 1-80

.EXTERN STRUCT assembler directive,

1-81

F

feature assembler macros

-D__ADSP21000__,

1-25

-D__ADSP21020__,

1-25

-D__ADSP21060__,

1-25

-D__ADSP21061__,

1-25

-D__ADSP21062__,

1-25

-D__ADSP21065L__,

1-25

-D__ADSP21160__,

1-25

-D__ADSP21161__,

1-25

-D__ADSP21261__,

1-25

-D__ADSP21262__,

1-25

-D__ADSP21266__,

1-26

-D__ADSP21267__,

1-26

-D__ADSP21363__,

1-26

-D__ADSP21364__,

1-26

-D__ADSP21365__,

1-26

-D__ADSP21366__,

1-26

-D__ADSP21367__,

1-26

-D__ADSP21368__,

1-26

-D__ADSP21369__,

1-26

-D__ADSP21371__,

1-26

-D__ADSP21375__,

1-26

-D__ADSP2137x__, 1-26

I-6 feature assembler macros

-D__ADSPBF531__,

1-28

(continued)

-D__ADSPBF532__,

1-28

-D__ADSPBF533__,

1-27

,

1-28

-D__ADSPBF535__,

1-28

-D__ADSPBF536__,

1-28

-D__ADSPBF537__,

1-28

-D__ADSPBF538__,

1-28

-D__ADSPBF539__,

1-28

-D__ADSPBF561__,

1-28

-D__ADSPBLACKFIN__, 1-27

-D__ADSPTS__,

1-27

-D__ADSPTS101__,

1-27

-D__ADSPTS201__,

1-27

-D__ADSPTS202__,

1-27

-D__ADSPTS203__,

1-27

-D__ADSPTS20x__, 1-27

-D_LANGUAGE_ASM, 1-25

,

1-27

feature preprocessor macros

__ADSP21000__, 2-16

__ADSP21020__, 2-16

__ADSP21060__, 2-16

__ADSP21061__, 2-16

__ADSP21062__, 2-16

__ADSP21065L__,

2-16

__ADSP2106x__, 2-17

__ADSP21160__, 2-16

__ADSP21161__, 2-17

__ADSP2116x__, 2-17

__ADSP21261__, 2-17

__ADSP21262__, 2-17

__ADSP21266__, 2-17

__ADSP21267__, 2-17

__ADSP21363__, 2-17

__ADSP21364__, 2-17

__ADSP21365__, 2-17

__ADSP21367__, 2-17

__ADSP21368__, 2-17

__ADSP21369__, 2-17

__ADSPBF522__, 2-18


INDEX

feature preprocessor macros

(continued)

__ADSPBF525__, 2-18

__ADSPBF527__, 2-18

__ADSPBF532__, 2-18

__ADSPBF533__, 2-18

__ADSPBF534__, 2-18

__ADSPBF535__, 2-18

__ADSPBF536__, 2-18

__ADSPBF537__, 2-18

__ADSPBF538__, 2-18

__ADSPBF539__, 2-19

__ADSPBF561__, 2-19

__ADSPBLACKFIN__,

2-18

__ADSPTS__,

2-18

__ADSPTS101__, 2-18

__ADSPTS201__, 2-18

__ADSPTS202__, 2-18

__ADSPTS203__, 2-18

-D_LANGUAGE_ASM,

2-16

-D_LANGUAGE_C, 2-16

.FILE_ATTR assembler directive, 1-84

-file-attr (file attribute) assembler switch,

1-151

file format, ELF (Executable and Linkable

Format),

1-3

__FILE__ macro,

2-16

.FILE (override filename) assembler

directive, 1-83

files

.asm (assembly source), 1-3

.dat (data),

1-3

.dlb (library),

1-5

.doj (object),

1-3

.h (header), 1-3

.is (preprocessed assembly), 1-161

,

2-13

list of extensions,

1-141

naming conventions,

1-141

-flags-compiler assembler switch,

1-151 ,

1-152

-flags-pp assembler switch, 1-153

floating-point precision,

1-109

rounding, 1-117

formats, numeric, 1-55

four-byte data initializer lists,

1-68

fractional arithmetic,

1-57 constants, 1-57

fracts

1.0r special case, 1-57

1.15 format, 1-56

1.31 format, 1-56

constants, 1-55

mixed type arithmetic,

1-58

signed values,

1-55

G

-g (generate debug info) assembler switch,

1-154

.GLOBAL (global symbol) assembler directive,

1-85

global substitutions, 2-4

global symbols, 1-85

.GLOBL assembler directive,

1-67

H

hardware anomalies, warnings displaying,

1-147 ,

1-148 ,

1-159

,

1-160

header files system,

2-5

tokens,

2-6

user,

2-5

hex value, decoding,

1-29

.h files,

1-3

-h (help) assembler switch,

1-155

,

2-49

HI () assembler operator,

1-51


INDEX

I

-I assembler switch, see -flags-compiler

switch

.IF conditional assembly directive, 1-58

#ifdef (test if defined) preprocessor command,

2-31

#ifndef (test if not defined) preprocessor command,

2-32

#if (test if true) preprocessor command,

2-30

-i (include directory path) assembler switch,

1-156

-i (include directory) preprocessor switch,

2-50

-I (include search-path)) assembler option,

1-153

-i (less includes) preprocessor switch,

2-50

.IMPORT assembler directive,

1-87

.IMPORT header files, 1-88

make dependencies from, 1-31

.INC/BINARY assembler directive, 1-90

.INCBIN assembler directive,

1-68

include files system header files,

2-5

user header files,

2-5

#include (insert a file) preprocessor command,

2-33

include path search, 2-7

#include preprocessor command,

2-5

initialization section qualifiers,

1-123

INPUT_SECTION_ALIGN() LDF command,

1-71 input section alignment instruction, 1-71

intermediate source file (.is), 1-5

-I- (search system include files)

preprocessor switch, 2-51

.is (preprocessed assembly) files, 1-161

,

2-13

K

keywords, assembler, 1-36

,

1-44

L

__LASTSUFFIX__ macro,

2-16

,

2-43

.ldf files,

1-7

,

1-8

.LEFTMARGIN assembler directive,

1-91

legacy directives

.PORT,

1-108 ,

1-115

.SEGMENT/.ENDSEG,

1-126

LENGTH () assembler operator,

1-51

-li (listing with include) assembler switch,

1-157

__LINE__ macro, 2-16

#line (output line number) preprocessor command,

2-35

linker, object file input to, 1-5

Linker Description Files (.ldf), 1-8

.LIST assembler directive, 1-92

.LIST_DATA assembler directive, 1-93

.LIST_DATFILE assembler directive,

1-94

.LIST_DEFTAB assembler directive,

1-95

listing files

address, 1-32

assembly process information, 1-5

assembly source code,

1-32

C data structure information, 1-5

data initialization, 1-94

data opcodes,

1-93

large opcodes,

1-98

line number, 1-32

.lst extension,

1-5

,

1-32

named,

1-157

opcode,

1-32

producing,

1-5

.LIST_LOCTAB assembler directive,

1-97

.LIST_WRAPDATA assembler directive,

1-98


INDEX

-l (named listing file) assembler switch,

1-157

LO () assembler operator,

1-51

local symbols,

1-85

local tab width,

1-95 ,

1-97

.LONG assember directives,

1-99

long-form initialization,

1-129

.lst files,

1-5

M

macro argument, converting into string

constant, 2-39

macros assembler feature,

1-25

Blackfin feature assembler,

1-27

debugging,

2-13

defining,

2-9 ,

2-23

defining with variable length argument

list, 2-24

definition rules,

2-9

-D__VISUALDSPVERSION__,

1-29 ,

2-19

expansion, tokens, 2-6

feature assembler,

1-27

predefined preprocessor,

2-15

preprocessor feature,

2-15

SHARC assembler feature, 1-25

TigerSHARC assembler feature,

1-27

writing,

2-7

make dependencies, 1-31 ,

1-88

-meminit linker switch, 1-124

memory

initializer, 1-124

RAM (random access memory), 1-123

sections, declaring, 1-120

type, PM (code and data),

1-123

types,

1-7

.MESSAGE assembler directive,

1-100

-micaswarn assembler switch,

1-159

-M (make rule only) assembler switch,

1-157

-M (make rule only) preprocessor switch,

2-52

-MM (make rule and assemble) assembler

switch, 1-158

-MM (make rule and assemble)

preprocessor switch, 2-51 ,

2-52

-Mo (output make rule) assembler switch,

1-158

-Mo (output make rule) preprocessor

switch, 2-52

-Mt (output make rule for named file) assembler switch,

1-158

-Mt preprocessor switch, 2-53

multi-issue conflict warnings,

1-159

N

N boundary alignment,

1-136

nested struct references,

1-64

.NEWPAGE assembler directive, 1-104

,

1-116

--no-anomaly-workaround assembler

switch, 1-159

-no-expand-symbolic-links assembler

switch, 1-160

-no-expand-windows-shortucts assembler

switch, 1-160

NO_INIT memory section,

1-125

section qualifier, 1-124

.NOLIST assembler directive, 1-92

.NOLIST_DATA assembler directive,

1-93

.NOLIST_DATFILE assembler directive,

1-94

.NOLIST_WRAPDATA assembler directive,

1-98

-no-source-dependency assembler switch,

1-159


INDEX

-no-temp-data-file assembler switch,

1-160

-nowarn preprocessor switch,

2-55

numeric formats, 1-55

O

object files

.DOJ extension,

1-5

producing,

1-5

OFFSETOF() built-in function,

1-62

-o (output) assembler switch, 1-161

-o (output) preprocessor switch, 2-53

opcodes, large,

1-98

P

.PAGELENGTH assembler directive,

1-105

.PAGEWIDTH assembly directive,

1-106

PM (48-bit word section) qualifier,

1-123

.PORT (declare port) assembler legacy

directive, 1-108

,

1-115

-pp (proceed with preprocessing) assembler

switch, 1-161

#pragma preprocessor command, 2-36

.PRECISION assembler directive,

1-109 ,

1-112

predefined preprocessor macros

ADI, 2-16

__DATE__,

2-16

__FILE__, 2-16

__LASTSUFFIX__, 2-16

__LINE__,

2-16

__TIME__, 2-16

preprocessor assembly files,

2-21

command-line syntax, 2-44

commands, 1-7

commands, list of, 2-21

command syntax,

2-3 ,

2-21

compiler, 2-2

-csall (all comment styles) switch,

2-49

-cs/* (/* */ comment style) switch,

2-48

-cs// (// comment style) switch,

2-49

-cs{ ({ } comment style) switch, 2-49

-cs! switch,

2-48

-cstring (C style) switch,

2-47

-D (define macro) switch, 2-49

feature macros, 2-15

global substitutions, 2-4

guide, 2-2

-h (help) switch,

2-49

-i (include path) switch, 2-50

-i (less includes) switch,

2-50

-I- (search system include files) switch,

2-51

-M (make rule only) switch, 2-52

-MM (make rule and assemble) switch,

2-52

-Mo (output make rule) switch, 2-52

-Mt (output make rule for named file)

switch, 2-53

-notokenize-dot switch,

2-53

-nowarn switch,

2-55

-o (output) switch,

2-53

option settings,

2-20

output file (.IS extenstion),

1-5

overview, 2-1

predefined macros,

2-15

running from command line,

2-44

source files, 2-21

-stringize switch,

2-53

system header files, 2-33


INDEX

preprocessor

-tokenize-dot switch,

2-53

-Uname switch, 2-54

user header files,

2-33

(continued)

-version (display version) switch, 2-54

-v (verbose) switch, 2-54

-warn (print warnings) switch, 2-55

-Wnumber (warning suppression)

switch, 2-55

-w (skip warning messages) switch,

2-54

preprocessor commands

#define, 2-23

#elif, 2-26

#else,

2-27

#endif, 2-28

#error,

2-29

#if,

2-30

#ifdef,

2-31

#ifndef, 2-32

#include, 2-33

#line (counter),

2-35

#pragma,

2-36

#undef,

2-37

#warning,

2-38

... preprocessor operator, 2-24

preprocessor operators,

2-24

? (generate unique label),

2-42

## (concatenate),

2-41

# (stringization),

2-39

.PREVIOUS assembler directive,

1-111 ,

1-112

-proc (target processor) assembler switch,

1-161

programs

assembling, 1-4

content, 1-6

listing files,

1-32

preprocessing, 1-23

structure, 1-7

writing assembly,

1-3

VisualDSP++ 5.0 Assembler and Preprocessor Manual project settings assembler,

1-166

preprocessor, 1-23 ,

2-20

Q

qualifier,

1-100

question mark (?) preprosessor operator,

2-42

R

R32 qualifier,

1-56

relational expressions,

1-60

operators,

1-50

RESOLVE() command (in LDF), 1-133

rounding modes,

1-117

.ROUND_MINUS (rounding mode) assembler directive,

1-117

.ROUND_NEAREST (rounding mode) assembler directive,

1-117

.ROUND_PLUS (rounding mode) assembler directive,

1-117

.ROUND_ZERO (rounding mode) assembler directive,

1-117

RUNTIME_INIT section qualifier,

1-124

S

-save-temps (save intermediate files) assembler switch,

1-162

searching, system include files,

2-51

section

name symbol, 1-120

qualifier, DM (data memory),

1-123 qualifier, PM (code and data), 1-123

qualifier, RAM (random access memory),

1-123

type identifier,

1-121

I-11

INDEX

.SECTION (start or embed a section) assembler directive,

1-120

initialization qualifiers, 1-123

.SEGMENT (legacy directive) assembler

directive, 1-126

.SEPARATE_MEM_SEGMENTS assembler directive,

1-126 ,

1-127

.SET assembler directive,

1-70

settings assembler options, from command line,

1-139

assembler options, from VisualDSP++

IDDE, 1-166

default tab width, 1-95

local tab width, 1-97

preprocessor options, build tools,

2-20

preprocessor options, command line,

2-20

preprocessor options, VisualDSP++,

2-20

SHF_ALLOC flag, 1-125

SHF_INIT flag,

1-125

SHORT assember directives,

1-127

.SHORT EXPRESSION-LIST assembler

directive, 1-70

short-form initialization,

1-129

SHT_DEBUGINFO section type,

1-121

SHT_NULL section type, 1-121

SHT_PROGBITS identifier,

1-121

memory section, 1-125

SHT_PROGBITS section type, 1-121

__SILICON_REVISION__ macro, 1-163

-si-revision (silicon revision) assembler

switch, 1-162

SIZEOF() built-in function,

1-62

source files (.ASM),

1-4

special characters, dot, 1-47

special operators, assembler,

1-51

I-12

-sp (skip preprocessing) assembler switch,

1-163

-stallcheck assembler switch, 1-163 stall information, 1-163

statistical profiling, enabling in assembler

source, 1-33

string initialization, 1-78 ,

1-136

# (stringization) preprocessor operator,

2-39

-stringize (double quotes) preprocessor struct

switch, 2-53

layout, 1-88

,

1-128

member initializers,

1-128

references,

1-63

,

1-64

variable,

1-128

struct references, nested, 1-64

.STRUCT (struct variable) assembler directive,

1-128

STT_OBJECT symbol type,

1-132

STT_* symbol type, 1-132

switches, see assembler command-line

switches

switches, see preprocessor command-line

switches symbol

assembler operator, 1-51

conventions, 1-47

types,

1-132

symbolic alias, setting, 1-70

symbolic expressions,

1-50

symbols, see assembler symbols

symbol type,changing default, 1-132

syntax assembler command line,

1-140

assembler directives,

1-66

constants, 1-49

instruction set,

1-6

macro, 2-7

preprocessor command,

2-21


INDEX

system header files, 2-5

searching,

2-51

T

tab characters source files,

1-95

,

1-97

tab width changing,

1-95

default,

1-97

temporary data file, not written to a

memory (disk), 1-160

.TEXT assembler directive,

1-70

__TIME__ macro,

2-16

-tokenize-dot (identifier parsing)


tokens, macro expansion, 2-6

trailing zero character,

1-79

two-byte data initializer lists, 1-70

.TYPE (change default type) assembler

directive, 1-132

U

-Uname preprocessor switch,

2-54

#undef (undefine) preprocessor command,

2-37

unique labels, generating, 2-42

user header files, 2-5

V

__VA_ARGS__ identifier,

2-24 ,

2-25

.VAR and .VAR/INIT24 (declare variable) assembler directives,

1-76

.VAR (data variable) assembler directive,

1-133

... (variable-length argument list), 2-24 variable length argument list, 2-24

-version (display version) assembler switch,

1-164

-version (display version) preprocessor

switch, 2-54

VisualDSP++

Assemble page, 1-33 ,

1-166 ,

1-167 ,

2-20

assembler settings,

1-166

assembling from,

1-3

preprocessor settings, 2-20

Project Options dialog box,

1-33

,

1-35 ,

1-166 ,

1-167 ,

2-20

setting assembler options, 1-33

,

1-166 ,

1-167

setting preprocessor options,

2-20

-v (verbose) assembler switch, 1-163

-v (verbose) preprocessor switch, 2-54

W

WARNING ea1121, missing end labels,

1-154

warnings

multi-issue conflicts, 1-159

printing,

2-55 suppressing, see -Wnumber (warning

suppression) preprocessor switch

#warning (warning message) preprocessor command,

2-38

-warn (print warnings) preprocessor switch,

2-55

.WEAK assembler directive, 1-138 weak symbol binding, 1-138

-Werror number assembler switch,

1-164

-Winfo number (informational messages) assembler switch,

1-164

-Wno-info (no informational messages) assembler switch,

1-165

-Wnumber (warning suppression) assembler switch,

1-165

-Wnumber (warning suppression)


wrapping, opcode listings,

1-98

writing assembly programs, 1-3


INDEX

-w (skip warning messages) assembler

switch, 1-164

-w (skip warning messages) preprocessor

switch, 2-54

-Wsuppress number assembler switch,

1-165

-Wwarn-error assembler switch, 1-165

-Wwarn number assembler switch, 1-165

Z

ZERO_INIT memory section,

1-125

section qualifier, 1-124


Analog Devices assembler, preprocessor Assembler and Preprocessor Manual

Assistant Bot

Assembler and Preprocessor Manual

Copyright Information

Disclaimer

Trademark and Service Mark Notice

CONTENTS

PREFACE

ASSEMBLER

PREPROCESSOR

INDEX

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

Printed Manuals

Notation Conventions

1 ASSEMBLER

Assembler Guide

Assembler Overview

Writing Assembly Programs

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

Comment Conventions

Conditional Assembly Directives

C Struct Support in Assembly Built-In Functions

Struct References

Assembler Directives

Assembler Command-Line Reference

Running the Assembler

Assembler Command-Line Switch Descriptions

Specifying Assembler Options in VisualDSP++

2 PREPROCESSOR

Preprocessor Guide

Writing Preprocessor Commands

Header Files and the #include Command

Writing Macros

Using Predefined Preprocessor Macros

Specifying Preprocessor Options

Preprocessor Command Reference

Preprocessor Commands and Operators

Preprocessor Command-Line Reference

Running the Preprocessor

Preprocessor Command-Line Switches

I INDEX

Key Features

Questions & Answers

S S V

what does asm("ssync; ") do

what are the supported assembly instructions

Frequently Answers and Questions

What is the purpose of the VisualDSP++ 5.0 Assembler and Preprocessor Manual?

What processor families are supported by the VisualDSP++ 5.0 assembler?

What information does the manual provide?

Related manuals

Analog Devices

preprocessor

Analog Devices

Utilities

Analog Devices

Blackfin

Analog Devices

Blackfin