- Computers & electronics
- Software
- Computer utilities
- Development software
- Analog Devices
- preprocessor
- Manual
- 264 Pages
Analog Devices assembler, preprocessor Assembler and Preprocessor Manual
The VisualDSP++ 5.0 Assembler and Preprocessor Manual 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. It includes information on new and legacy syntax, assembler and preprocessor directives and comments, as well as command-line switches.
advertisement
Assistant Bot
Need help? Our chatbot has already read the manual and is ready to assist you. Feel free to ask any questions about the device, but providing details will make the conversation more productive.
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
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual
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)
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,
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,
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
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
Product Information
Registration
Visit www.myanalog.com
to sign up. Click Register to use
MyAnalog.com.
Registration takes about five minutes and serves as a means to select the information you want to receive.
If you are already a registered user, just log on. Your user name is your e-mail address.
Processor Product Information
For information on embedded processors and DSPs, visit our Web site at www.analog.com/processors
, which provides access to technical 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
Product Information
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
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
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
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
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
Product Information
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:
•
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-3
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
1-4 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Assemble your source files from the VisualDSP++ environment or using any mechanism, such as a batch file or makefile, that will support invoking an appropriate assembler driver with a specified command-line command. By default, the assembler processes an 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
.) 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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-5
Assembler Guide
Program Content
Assembly source file statements include assembly instructions, assembler directives, and preprocessor commands.
Assembly Instructions
Instructions adhere to the processor’s instruction set syntax documented in the processor’s 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.
1-6 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
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
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-7
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual
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-
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-9
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.
1-10 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Listing 1-1. LDF Example for SHARC Processors
ARCHITECTURE(ADSP-21062)
SEARCH_DIR( $ADI_DSP\21k\lib )
$LIBRARIES = lib060.dlb, libc.dlb;
$OBJECTS = $COMMAND_LINE_OBJECTS, 060_hdr.doj;
MEMORY { seg_rth {TYPE(PM RAM) START(0x20000) END(0x20fff) WIDTH(48)} seg_init{TYPE(PM RAM) START(0x21000) END(0x2100f) WIDTH(48)} seg_pmco{TYPE(PM RAM) START(0x21010) END(0x24fff) WIDTH(48)} seg_pmda{TYPE(DM RAM) START(0x28000) END(0x28fff) WIDTH(32)} seg_dmda{TYPE(DM RAM) START(0x29000) END(0x29fff) WIDTH(32)} seg_stak{TYPE(DM RAM) START(0x2e000) END(0x2ffff) WIDTH(32)}
/* memory declarations for default heap */ seg_heap{TYPE(DM RAM) START(0x2a000) END(0x2bfff) WIDTH(32)}
/* memory declarations for custom heap */ seg_heaq{TYPE(DM RAM) START(0x2c000) END(0x2dfff) WIDTH(32)}
} // End MEMORY
PROCESSOR p0 {
LINK_AGAINST( $COMMAND_LINE_LINK_AGAINST)
OUTPUT( $COMMAND_LINE_OUTPUT_FILE )
SECTIONS {
.seg_rth {
INPUT_SECTIONS( $OBJECTS(seg_rth) $LIBRARIES(seg_rth))
} > seg_rth
.seg_init {
INPUT_SECTIONS( $OBJECTS(seg_init) $LIBRARIES(seg_init))
} > seg_init
.seg_pmco {
INPUT_SECTIONS( $OBJECTS(seg_pmco) $LIBRARIES(seg_pmco))
} > seg_pmco
.seg_pmda {
INPUT_SECTIONS( $OBJECTS(seg_pmda) $LIBRARIES(seg_pmda))
} > seg_pmda
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-11
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
1-12 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
Assembly Instructions
.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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-13
Assembler Guide
LDF for TigerSHARC Processors
Listing 1-2 shows a sample user-defined LDF for TigerSHARC 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.
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 *
/
1-14 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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(ctor1) )
INPUT_SECTIONS( $OBJECTS(ctor2) )
INPUT_SECTIONS( $OBJECTS(ctor3) )
INPUT_SECTIONS( $OBJECTS(ctor) )
} >M1Data
// Table containing heap segment descriptors heaptab
{
INPUT_SECTIONS( $OBJECTS(heaptab) )
} >M1Data
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-15
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{}
command, notice that the
INPUT_SECTION
commands map to sections program
, data1
, and constdata
.
1-16 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Data Section
Assembler Directive
Data Section
Assembler Directive
Preprocessor Commands for Conditional Assembly
Code (program) Section
Assembler Label
Assembly Instructions
.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;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-17
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_SECTION_ALIGN(2)
INPUT_SECTIONS( $OBJECTS(program) $LIBRARIES(program))
INPUT_SECTION_ALIGN(1)
INPUT_SECTIONS( $OBJECTS(data1) $LIBRARIES(data1))
INPUT_SECTION_ALIGN(1)
INPUT_SECTIONS(
$OBJECTS(constdata)$LIBRARIES(constdata))
INPUT_SECTION_ALIGN(1)
INPUT_SECTIONS( $OBJECTS(ctor) $LIBRARIES(ctor))
INPUT_SECTION_ALIGN(2)
INPUT_SECTIONS( $OBJECTS(seg_rth))
} >MEM_PROGRAM stack
1-18 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
}
}
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-19
Assembler Guide
Program Interfacing Requirements
You can interface your assembly program with a C or C++ program.
The C/C++ compiler supports two methods for mixing C/C++ and assembly language:
• Embedding assembly code in C or C++ programs
• Linking together C or C++ and assembly routines
To embed (inline) assembly code in your C or C++ program, use the asm()
construct. To link together programs that contain C/C++ and assembly routines, use assembly interface macros. These macros facilitate the assembly of mixed routines. For more information about these methods, see the VisualDSP++ 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.
1-20 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.
Data Directives:
IMPORT
(see
)
.
EXTERN STRUCT
(see
)
.
STRUCT
(see
C Struct in Assembly Built-Ins:
OFFSETOF(struct/typedef,field)
SIZEOF(struct/typedef)
(see
(see
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
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-21
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;
1-22 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-23
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
1-24 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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-21060 with ADSP-21060 processors
Present when running easm21K -proc ADSP-21061 with ADSP-21061 processors
Present when running easm21K -proc ADSP-21062 with ADSP-21062 processors
Present when running easm21K -proc ADSP-21065L with ADSP-21065L processors
Present when running easm21K -proc ADSP-21160 with ADSP-21160 processors
Present when running easm21K -proc ADSP-21161 with ADSP-21161 processors
Present when running easm21K -proc ADSP-21261 with ADSP-21261 processors
Present when running easm21K -proc ADSP-21262 with ADSP-21262 processors
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-25
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-21266 with ADSP-21266 processors
Present when running easm21K -proc ADSP-21267 with ADSP-21267 processors
Present when running easm21K -proc ADSP-21362 with ADSP-21362 processors
Present when running easm21K -proc ADSP-21363 with ADSP-21363 processors
Present when running easm21K -proc ADSP-21364 with ADSP-21364 processors
Present when running easm21K -proc ADSP-21365 with ADSP-21365 processors
Present when running easm21K -proc ADSP-21366 with ADSP-21366 processors
Present when running easm21K -proc ADSP-21367 with ADSP-21367 processors
Present when running easm21K -proc ADSP-21368 with ADSP-21368 processors
Present when running easm21K -proc ADSP-21369 with ADSP-21369 processors
Present when running easm21K -proc ADSP-2137x with ADSP-2137x processors
Present when running easm21K -proc ADSP-21371 with ADSP-21371 processors
Present when running easm21K -proc ADSP-21375 with ADSP-21375 processors
1-26 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
Present when running easmts -proc ADSP-TS202 with ADSP-TS202 processor
Present when running easmts -proc ADSP-TS203 with ADSP-TS203 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
Present when running easmblkfn -proc ADSP-BF525 with ADSP-BF525 processor
Present when running easmblkfn -proc ADSP-BF527 with ADSP-BF527 processor
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-27
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
Present when running easmblkfn -proc ADSP-BF531 with ADSP-BF531 processor
Present when running easmblkfn -proc ADSP-BF532 with ADSP-BF532 processor
Present when running easmblkfn -proc ADSP-BF533 with ADSP-BF533 processor
Present when running easmblkfn -proc ADSP-BF534 with ADSP-BF534 processor
Present when running easmblkfn -proc ADSP-BF535 with ADSP-BF535 processor
Present when running easmblkfn -proc ADSP-BF536 with ADSP-BF536 processor
Present when running easmblkfn -proc ADSP-BF537 with ADSP-BF537 processor
Present when running easmblkfn -proc ADSP-BF538 with ADSP-BF538 processor
Present when running easmblkfn -proc ADSP-BF539 with ADSP-BF539 processor
Present when running easmblkfn -proc ADSP-BF542 with ADSP-BF542 processor
Present when running easmblkfn -proc ADSP-BF544 with ADSP-BF544 processor
Present when running easmblkfn -proc ADSP-BF548 with ADSP-BF548 processor
Present when running easmblkfn -proc ADSP-BF549 with ADSP-BF549 processor
Present when running easmblkfn -proc ADSP-BF561 with ADSP-BF561 processor
1-28 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-29
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
1-30 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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"
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-31
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
1-32 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
offset for the members. The information appears at the end of the listing.
You must specify the
-l
filename option (as shown
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:
.GLOBAL funk2; funk2:
...
RTS; funk2.end:
If you have global functions without ending labels, the assembler provides warnings when debug information is generated.
.GLOBAL funk3; funk3:
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-33
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.
1-34 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Assembler Syntax Reference
When you develop a source program in assembly language, include preprocessor commands and assembler directives to control the program’s processing and assembly. You must follow the assembler rules and 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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-35
Assembler Syntax Reference
Assembler Keywords and Symbols
The assembler supports predefined keywords that include register and bitfield names, assembly instructions, and assembler directives. The following tables list 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
1-36 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-37
Assembler Syntax Reference
Table 1-9. SHARC Processor Assembler Keywords (Cont’d)
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
1-38 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-9. SHARC Processor Assembler Keywords (Cont’d)
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-39
Assembler Syntax Reference
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
1-40 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-41
Assembler Syntax Reference
Table 1-10. TigerSHARC Processor Assembler Keywords (Cont’d)
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
1-42 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-10. TigerSHARC Processor Assembler Keywords (Cont’d)
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-43
Assembler Syntax Reference
Table 1-10. TigerSHARC Processor Assembler Keywords (Cont’d)
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
1-44 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-45
Assembler Syntax Reference
Table 1-11. Blackfin Processor Assembler Keywords (Cont’d)
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
1-46 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-11. Blackfin Processor Assembler Keywords (Cont’d)
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).
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-47
Assembler Syntax Reference
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.
1-48 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-49
Assembler Syntax Reference
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
1-50 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
&
|
^
+
-
<<
>>
Operator
*
/
%
Table 1-12. Operator Precedence (Cont’d)
Usage Description
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
Usage Description
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-51
Assembler Syntax Reference
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));
1-52 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-53
Assembler Syntax Reference
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
@
.
1-54 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
, the preprocessor’s
“-stringize” command-line switch ( on page 2-53
),
and the assembler’s “-flags-pp -opt1 [,-opt2...]” command-line
switch (
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-55
Assembler Syntax Reference
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
// sign bit + 31 bits
1-56 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
// sign bit + 31 bits
// 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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-57
Assembler Syntax Reference
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;
1-58 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-59
Assembler Syntax Reference
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
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
).
• 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;
1-60 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-61
Assembler Syntax Reference
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.
1-62 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 “
->
”.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-63
Assembler Syntax Reference
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 {
VisualDSP++ 5.0 Assembler and Preprocessor Manual
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)];
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-65
Assembler Syntax Reference
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
.ALIGN_CODE
(see
.ASCII
(see
.BSS
.BYTE
.BYTE2
.BYTE4
(see
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.
NOTE: Blackfin processors ONLY.
Defines and initializes one-, two-, and four-byte data objects, respectively.
NOTE: Blackfin processors ONLY.
1-66 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-17. Assembler Directive Summary (Cont’d)
Directive Description
.DATA
to
Refer to
“.SECTION, Declare a Memory Section” on page 1-120
for more information.
NOTE: Blackfin processors ONLY.
Conditional assembly directive
.ELSE
(see
.ENDIF
(see
Conditional assembly directive
.ENDSEG
(see
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
.EXTERN STRUCT
(see
.FILE
(see
.FILE_ATTR
(see
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
.GLOBL
.IF
(see
Equivalent to
.GLOBAL
.
Refer to
“.GLOBAL, Make a Symbol Available Globally” on page 1-85
for more information.
NOTE: Blackfin processors ONLY.
Conditional assembly directive
.IMPORT
(see
.INC/BINARY
(see
Provides the assembler with the structure layout (C struct) information
Includes the content of file at the current location.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-67
Assembler Syntax Reference
Table 1-17. Assembler Directive Summary (Cont’d)
Directive
.INCBIN
Description
Equivalent to
.INC/BINARY
Refer to
“.INC/BINARY, Include Contents of a File” on page 1-90
for more information.
NOTE: Blackfin processors ONLY.
Defines the width of the left margin of a listing
.LEFTMARGIN
(see
.LIST/.NOLIST
(see
.LIST_DATA
(
)
.LIST_DATFILE
(see
.LIST_DEFTAB
(see
.LIST_LOCTAB
(see
.LIST_WRAPDATA
(see
.LONG
(see
.MESSAGE
(see
.NEWPAGE
(see
.NOLIST
(see
.NOLIST_DATA
(see
.NOLIST_DATFILE
(see
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.
NOTE: Blackfin processors ONLY.
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
1-68 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-17. Assembler Directive Summary (Cont’d)
Directive
.NOLIST_WRAPDATA
(see
.PAGELENGTH
(see
.PAGEWIDTH
(see
.PORT
(see
.PRECISION
(see
.PREVIOUS
(see
.PRIORITY
(see
.REFERENCE
(see
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.
NOTE: SHARC processors ONLY.
Defines the number of significant bits in a floating-point value.
NOTE: SHARC processors ONLY.
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.
NOTE: Blackfin processors ONLY.
Stops the linker from eliminating a symbol.
.RETAIN_NAME
(see
.ROUND_NEAREST
(see
.ROUND_MINUS
(see
.ROUND_PLUS
(see
.ROUND_ZERO
(see
.SECTION
(see
Specifies the Round-to-Nearest mode.
NOTE: SHARC processors ONLY.
Specifies the Round-to-Negative Infinity mode.
NOTE: SHARC processors ONLY.
Specifies the Round-to-Positive Infinity mode.
NOTE: SHARC processors ONLY.
Specifies the Round-to-Zero mode.
NOTE: SHARC processors ONLY.
Marks the beginning of a section
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-69
Assembler Syntax Reference
Table 1-17. Assembler Directive Summary (Cont’d)
Directive
.SEGMENT
(see
.SEPARATE_MEM_SEGMENTS
(see
.SET
(see
.SHORT
(see
.STRUCT
(see
.TEXT
Description
Legacy directive. Replaced with the
.SECTION
directive.
NOTE: SHARC processors ONLY.
Specifies that two buffers should be placed into different memory segments by the linker.
NOTE: TigerSHARC processors ONLY.
Sets symbolic aliases
Supports two-byte data initializer lists for GNU compatibility.
NOTE: Blackfin processors ONLY.
Defines and initializes data objects based on C typedefs
from
.
IMPORT
C header files
Equivalent to
.SECTION program;
Refer to
“.SECTION, Declare a Memory Section” on page 1-120
for more information.
NOTE: Blackfin processors ONLY.
Changes the default data type of a symbol; used by C compiler
.TYPE
(see
.VAR
(see
.WEAK
(see
Defines and initializes 32-bit data objects
Creates a weak definition or reference
1-70 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-71
Assembler Syntax Reference
.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
.
1-72 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 */
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-73
Assembler Syntax Reference
JUMP LABEL;;
/* Jump instruction aligned to four word boundary.
If necessary, padding will be done with NOPs */
1-74 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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:
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-75
Assembler Syntax Reference
.BYTE, Declare a Byte Data Variable or Buffer
L
Used with Blackfin processors ONLY.
The
.BYTE
,
.BYTE2
, and
.BYTE4
directives declare and optionally initialize one-, two-, or four-byte data objects. Note that the
.BYTE4
directive performs the same function as the
.VAR
directive.
Syntax:
When declaring and/or initializing memory variables or buffer elements, use one of these forms:
.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.
1-76 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
).
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-77
Assembler Syntax Reference
// 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
.
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).
1-78 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-79
Assembler Syntax Reference
.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
.
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.
1-80 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-81
Assembler Syntax Reference
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);
1-82 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-83
Assembler Syntax Reference
.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
“Assembler Keywords and Symbols” on page 1-36
).
Examples:
.FILE_ATTR at1;
.FILE_ATTR at10=a123;
.FILE_ATTR at101=a123, at102,at103="999";
1-84 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
. 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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-85
Assembler Syntax Reference
.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
1-86 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-87
Assembler Syntax Reference
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
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 (
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
and the
.STRUCT
directive
1-88 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-89
Assembler Syntax Reference
.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
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";
1-90 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-91
Assembler Syntax Reference
.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.
1-92 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
directives do not take any qualifiers or arguments.
Syntax:
.LIST_DATA;
.NOLIST_DATA;
These directives can appear multiple times anywhere in a source file, and their effect depends on their location in the source file.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-93
Assembler Syntax Reference
.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
directives do not take any qualifiers or arguments.
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.
1-94 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
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;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-95
Assembler Syntax Reference
// Tabs here are still expanded to 2 columns
// But tabs in "include_2.h" will be expanded to 4 columns
#include "include_2.h"
1-96 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
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
.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-97
Assembler Syntax Reference
.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
directives do not take any qualifiers or arguments.
Syntax:
.LIST_WRAPDATA;
.NOLIST_WRAPDATA;
These directives can appear multiple times anywhere in a source file, and their effect depends on their location in the source file.
1-98 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.LONG, Defines and initializes 4-byte data objects
L
Used with Blackfin processors ONLY.
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
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
The following lines of code demonstrate
.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;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-99
Assembler Syntax Reference
.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,…]
;
.MESSAGE/qualifier
warnid1 [,warnid2,…]
UNTIL sym;
.MESSAGE/qualifier
warnid1 [,warnid2,…]
FOR
n
LINES;
.MESSAGE/DEFAULT/qualifier
warnid1 [,warnid2,…]
; 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
1-100 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-101
Assembler Syntax Reference
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;
// generates a warning
// generates an error
// generates a warning
// generates an error
// generates a warning
The
POP
qualifier changes the severity of the messages back to previous severities.
Example (for TigerSHARC Processors):
.MESSAGE/INFO 3012;
.SECTION program;
RETI;;
.MESSAGE/ERROR 3012;
RETI;;
.MESSAGE/INFO 3012;
RETI;;
.MESSAGE/POP 3012;
RETI;;
.MESSAGE/POP 3012;
// generates an informational
// generates an error
// generates an informational
// generates an error - 2nd directive
1-102 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
Example (for TigerSHARC Processors):
.MESSAGE/DEFAULT/ERROR 1177;
.MESSAGE/DEFAULT/INFO 1177;
.SECTION program;
.VAR one=1.0r;
.MESSAGE/ERROR 1177;
.VAR two=1.0r;
.MESSAGE/RESTORE 1177;
.VAR three=1.0r;
.MESSAGE/RESTORE_CL 1177;
.VAR four=1.0r;
// generates an informational
// generates an error
// generates an informational
// generates a warning
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-103
Assembler Syntax Reference
.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
(
). 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.
1-104 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 (
)
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-105
Assembler Syntax Reference
.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.
1-106 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-107
Assembler Syntax Reference
.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.
1-108 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.PRECISION, Select Floating-Point Precision
L
Used with SHARC processors ONLY.
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-109
Assembler Syntax Reference
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 (
precision.
1-110 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-111
Assembler Syntax Reference
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’
.
1-112 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-113
Assembler Syntax Reference
.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.
1-114 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.REFERENCE, Provide Better Info in an X-REF File
L
Used with Blackfin processors ONLY.
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
directive uses the following syntax:
.REFERENCE symbol; where:
symbol
– is a symbol
Example:
.REFERENCE P1;
.REFERENCE P2;
//
//
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-115
Assembler Syntax Reference
.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
directive uses the following syntax:
.RETAIN_NAME symbol; where:
symbol
– is a user-defined symbol
For information on KEEP(), refer to the VisualDSP++ 5.0 Linker and
Utilities manual.
1-116 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
.ROUND_, Select Floating-Point Rounding
L
Used with SHARC processors ONLY.
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-117
Assembler Syntax Reference
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
*/
1-118 VisualDSP++ 5.0 Assembler and Preprocessor Manual
.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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-119
Assembler Syntax Reference
.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
.
1-120 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-121
Assembler Syntax Reference
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
are represented as 16-bit types.
CHARs
are represented as
32-bit types.
Shorts
are represented as 32-bit types.
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.
1-122 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 .
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-123
Assembler Syntax Reference
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.
1-124 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-125
Assembler Syntax Reference
.SEGMENT and .ENDSEG, Legacy Directives
L
Used with SHARC processors ONLY.
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.
1-126 VisualDSP++ 5.0 Assembler and Preprocessor 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
Used with Blackfin processors ONLY.
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
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-127
Assembler Syntax Reference
constExpressions
parameters – contain a comma-separated list of constant values
The following lines of code demonstrate
.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
[ ,struct-member-initializers... ] }; where
typedef
– the type definition for a struct
VARstructName
– a struct
name
struct-member-initializers
– per struct member initializers
1-128 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-129
Assembler Syntax Reference
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
};
1-130 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 }
};
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-131
Assembler Syntax Reference
.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.
1-132 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-133
Assembler Syntax Reference
.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.
1-134 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
).
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-135
Assembler Syntax Reference
// 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.
1-136 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-137
Assembler Syntax Reference
.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.
1-138 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
•
“Assembler Command-Line Switch Descriptions” on page 1-142
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
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-139
Assembler Command-Line Reference
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
[ -switch1 [ -switch2 … ] ] sourceFile
easmblkfn
[ -switch1 [ -switch2 … ] ] sourceFile
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]
).
1-140 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-141
Assembler Command-Line Reference
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
.
Table 1-25. Assembler Command-Line Switch Summary
Switch Name
-align-branch-lines
(
)
Purpose
Aligns branch lines to avoid ADSP-TS101 processor sequencer anomaly.
NOTE: TigerSHARC processors ONLY.
Issues a warning or an error for an anomaly id.
-anomaly-detect id1[,id2...]
(
)
-anomaly-warn
{id1[,id2]|all|none}
(
)
-anomaly-workaround id1[,id2...]
(
)
Checks assembly instructions against hardware anomalies.
NOTE: Blackfin processors ONLY.
Implements a workaround for an anomaly id.
1-142 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-25. Assembler Command-Line Switch Summary (Cont’d)
Switch Name
-char-size-8
(
)
-char-size-32
(
)
-char-size-any
(
)
-default-branch-np
(
)
-default-branch-p
(
)
Purpose
Adds
/CHAR8
to
.SECTION
s in the source file.
NOTE: TigerSHARC processors ONLY.
Adds
/CHAR32
to
.SECTION
s in the source file.
NOTE: TigerSHARC processors ONLY.
Adds
/CHARANY
to
.SECTION
s in the source file.
NOTE: TigerSHARC processors ONLY.
Makes branch lines default to NP to avoid ADSP-TS101 processor sequencer anomaly.
NOTE: TigerSHARC processors ONLY.
Make branch lines default to the Branch Target Buffer
(BTB).
NOTE: TigerSHARC processors ONLY.
Passes macro definition to the preprocessor.
-Dmacro[=definition]
(
)
-double-size-32
(
)
-double-size-64
(
)
-double-size-any
(
)
-expand-symbolic-links
(
)
-expand-windows-shortcuts
(
)
-file-attr attr [=value]
(
)
-flags-compiler
-opt1...
(
)
-flags-pp
...
-opt1...
(
)
Adds
/DOUBLE32
to the
.SECTION
s in the source file.
Adds
/DOUBLE64
to the
.SECTION
s in the source file.
Adds
/DOUBLEANY
to the
.SECTION
s in the source file.
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-143
Assembler Command-Line Reference
Table 1-25. Assembler Command-Line Switch Summary (Cont’d)
Switch Name
-g
(
)
–h[elp]
(
)
-i|-I
directory pathname
(
)
–l filename
(
)
–li filename
(
)
-M
(
)
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
(
)
–Mo filename
(
)
–Mt filename
(
)
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.
NOTE: Blackfin processors ONLY.
Do not issue a warning or an error for an anomaly id.
-micaswarn
(
)
-no-anomaly-detect id1[,id2...]
(
)
-no-anomaly-workaround id1[,id2...]
(
)
-no-expand-symbolic-links
(
)
Do not implement a workaround for an anomaly id.
Disables support for Cygwin style paths.
1-144 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
Table 1-25. Assembler Command-Line Switch Summary (Cont’d)
Switch Name
-no-expand-windows-shortcuts
(
)
-no-temp-data-file
(
)
-no-source-dependency
(
)
Purpose
Disables support for Windows shortcuts.
Suppresses writing temporary data to a disk file.
NOTE: Blackfin processors ONLY.
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
(
)
-pp
(
)
-proc
processor
(
)
-save-temps
(
)
–si-revision version
(
)
-sp
(
)
-stallcheck={none|cond|all}
(
)
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
NOTE: Blackfin processors ONLY.
Displays information on each assembly phase.
-v
or
-verbose
(
)
–version
(
)
-w
(
)
Displays version information for the assembler and preprocessor programs.
Disables all assembler-generated warnings.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-145
Assembler Command-Line Reference
Table 1-25. Assembler Command-Line Switch Summary (Cont’d)
Switch Name
-Werror
number[,number ...]
(
)
-Winfo
number[,number ...]
(
)
-Wno-info
(
)
-Wnumber[,number ...]
(
)
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...]
(
)
-Wwarn
number[,number ...]
(
)
Selectively turns off assembler messages.
Selectively turns assembler messages into warnings.
-Wwarn-error
(
)
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.
1-146 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-147
Assembler Command-Line Reference
-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
Anomaly identifier (for example, 05-00-0245 or 05000245)
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
This switch is used with TigerSHARC processors ONLY.
-char-size-32
The
-char-size-32
switch directs the assembler to add
/CHAR32
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
This switch is used with TigerSHARC processors ONLY.
1-148 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
-char-size-any
The
-char-size-any
switch directs the assembler to add
/CHARANY
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
This switch is used with TigerSHARC processors ONLY.
-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
This switch is used with TigerSHARC processors ONLY.
-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
This switch is used with TigerSHARC processors ONLY.
-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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-149
Assembler Command-Line Reference
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
switch directs the assembler to add
/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
size qualifier, this option is ignored and a warning is produced. For more information, see
“.SECTION, Declare a Memory Section” on page 1-120 .
-double-size-64
The
-double-size-64
switch directs the assembler to add
/DOUBLE64
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
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
“.SECTION, Declare a Memory Section” on page 1-120
.
1-150 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
-double-size-any
The
-double-size-any
switch directs the assembler to add
/DOUBLEANY
to
.SECTION
s in the source file that do not have double
size qualifiers, making
SECTION
contents independent of size of double
type. For .
SECTION s in the source file that already have a double
size qualifier, this option is ignored and a warning is produced. For more information, see
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
“Assembler Keywords and Symbols” on page 1-36
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-151
Assembler Command-Line Reference
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.
1-152 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-153
Assembler Command-Line Reference
-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
).
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.
1-154 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-155
Assembler Command-Line Reference
-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
1-156 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-157
Assembler Command-Line Reference
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
-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
for more information.
1-158 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Assembler
-micaswarn
The
-micaswarn
switch treats multi-issue conflicts as warnings.
L
This switch is used with Blackfin processors ONLY.
-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
Anomaly identifier (for example, 05-00-0245 or 05000245)
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-159
Assembler Command-Line Reference
The switch parameter is: id
Anomaly identifier (for example, 05-00-0245 or 05000245)
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.
1-160 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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”
.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-161
Assembler Command-Line Reference
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
(
).
For example, easmblkfn -proc ADSP- BF533 -si-revision 0.1
1-162 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
__SILICON_REVISION__
macro is set to
0xffff
. If the
-si-revision
switch is set to “ none
”, the assembler will not set the
__SILICON_REVISION__
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-163
Assembler Command-Line Reference
-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
This switch is used with Blackfin processors ONLY.
-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.
1-164 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
Many error messages cannot be altered in severity as the assembler behavior is unknown.
-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
Many error messages cannot be altered in severity as the assembler behavior is unknown.
-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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-165
Assembler Command-Line Reference
-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
Many error messages cannot be altered in severity as the assembler behavior is unknown.
-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
Many error messages cannot be altered in severity as the assembler behavior is unknown.
-Wwarn-error
The
-Wwarn-error
switch displays all the assembler warning messages as errors.
1-166 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-167
Assembler Command-Line Reference
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
“Assembler Command-Line Switch Descriptions” on page 1-142
.
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.
1-168 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 1-169
Assembler Command-Line Reference
1-170 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-1
Preprocessor Guide
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
•
•
“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
) 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
2-2 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 .
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-3
Preprocessor Guide
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.
2-4 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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"
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-5
Preprocessor Guide
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>
2-6 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
.
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).
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-7
Preprocessor Guide
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:
•
•
“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
2-8 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-9
Preprocessor Guide
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
\
\
\
\
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-11
Preprocessor Guide
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
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];
\
\
\
\
2-12 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-13
Preprocessor Guide
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
#include "defBF534.h"
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.
#include "defBF534.h"
#define FALSE 0
#define TRUE 1
.SECTION data1;
.VAR ALARM = FALSE;
[Error ea5004] "alarm.asm":7 Syntax Error in :
2-14 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-15
Preprocessor Guide
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__
Present easmts -proc ADSP-21060 with ADSP-21060 processor
__ADSP21061__
Present easmts -proc ADSP-21061 with ADSP-21061 processor
__ADSP21062__
Present easmts -proc ADSP-21062 with ADSP-21062 processor
__ADSP21065L__ with ADSP-21065L processor
__ADSP21160__
Present easmts -proc ADSP-21160 with ADSP-21160 processor
2-16 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Preprocessor
Table 2-2. SHARC Feature Preprocessor Macros (Cont’d)
Macro
__ADSP21161__
Present easmts -proc ADSP-21161 with ADSP-21161 processor
__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
Present when running easmts -proc ADSP-21262 with ADSP-21262 processor
Present when running easmts -proc ADSP-21266 with ADSP-21266 processor
Present when running easmts -proc ADSP-21267 with ADSP-21267 processor
__ADSP21363__
__ADSP21364__
__ADSP21365__
__ADSP21366__
__ADSP21367__
__ADSP21368__
__ADSP21369__
Present when running easmts -proc ADSP-21363 with ADSP-21363 processor
Present when running easmts -proc ADSP-21364 with ADSP-21364 processor
Present when running easmts -proc ADSP-21365 with ADSP-21365 processor
Present when running easmts -proc ADSP-21366 with ADSP-21366 processor
Present when running easmts -proc ADSP-21367 with ADSP-21367 processor
Present when running easmts -proc ADSP-21368 with ADSP-21368 processor
Present when running easmts -proc ADSP-21369 with ADSP-21369 processor
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-17
Preprocessor Guide
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
Equal 1 when used with ASDP-TS201 processor
Equal 1 when used with ASDP-TS202 processor
Equal 1 when used with ASDP-TS203 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-BF525 with ADSP-BF525 processor.
Present when running easmblkfn -proc ADSP-BF527 with ADSP-BF527 processor.
Present when running easmblkfn -proc ADSP-BF532 with ADSP-BF532 processor.
Present when running easmblkfn -proc ADSP-BF533 with ADSP-BF533 processor.
Present when running easmblkfn -proc ADSP-BF534 with ADSP-BF534 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.
Present when running easmblkfn -proc ADSP-BF538 with ADSP-BF538 processor.
2-18 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Preprocessor
Table 2-4. Blackfin Feature Preprocessor Macros (Cont’d)
Macro
__ADSPBF539__
__ADSPBF542__
__ADSPBF544__
__ADSPBF548__
__ADSPBF549__
__ADSPBF561__
Definition
Present when running easmblkfn -proc ADSP-BF539 with ADSP-BF539 processor.
Present when running easmblkfn -proc ADSP-BF542 with ADSP-BF542 processor.
Present when running easmblkfn -proc ADSP-BF544 with ADSP-BF544 processor.
Present when running easmblkfn -proc ADSP-BF548 with ADSP-BF548 processor.
Present when running easmblkfn -proc ADSP-BF549 with ADSP-BF549 processor.
Present when running easmblkfn -proc ADSP-BF561 with ADSP-BF561 processor.
-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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-19
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
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.
Preprocessor Command Reference
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.
2-20 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
lists preprocessor commands. Table 2-6 lists preprocessor
operators. Sections that begin
describe each of the preprocessor commands and operators.
Table 2-5. Preprocessor Command Summary
Command/Operator
#define
(
#elif
(
#else
(
#endif
(
#error
(
#if
(
#ifdef
(
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-21
Preprocessor Command Reference
Table 2-5. Preprocessor Command Summary
Command/Operator
#ifndef
(
Description
Begins an
#ifndef … #endif
pair and tests if macro is not defined
#include
(
Includes contents of a file
#line
(
#pragma
(
Sets a line number during preprocessing
Takes any sequence of tokens
#undef
(
Removes macro definition
#warning
(
Reports a warning message
Table 2-6. Preprocessor Operator Summary
Command/Operator
#
)
##
(
?
(
... ( on page 2-24 )
Description
Converts a macro argument into a string constant.
By default, this operator is OFF. Use the command-line switch
to enable it.
Concatenates two tokens
Generates unique labels for repeated macro expansions
Specifies a variable-length argument list
2-22 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-23
Preprocessor Command Reference
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 .
2-24 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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);
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-25
Preprocessor Command Reference
#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
2-26 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-27
Preprocessor Command Reference
#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 */
2-28 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-29
Preprocessor Command Reference
#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__)
2-30 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
– macro identifying symbol
Example:
#ifdef __ADSPBF535__
/* Includes text after #ifdef only when __ADSPBF535__ has been defined */
#endif
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-31
Preprocessor Command Reference
#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
– macro identifying symbol
Example:
#ifndef __ADSPBF535__
#endif
/* Includes text after #ifndef only when __ADSPBF535__ is not defined */
2-32 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-33
Preprocessor Command Reference
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
2-34 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-35
Preprocessor Command Reference
#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
2-36 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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 */
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-37
Preprocessor Command Reference
#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:
#ifndef __ADSPBF535__
#warning \
MyWarning: \
Expecting a ADSPBF535. \
#endif
Check the Linker Description File!
2-38 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
switch (
) 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");
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-39
Preprocessor Command Reference
/* Note that the #EXP has been changed to current <minimum and is enclosed in “ ” */
2-40 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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};
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-41
Preprocessor Command Reference
? (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;
2-42 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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;
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-43
Preprocessor Command-Line Reference
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:
•
•
“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.
2-44 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
Table 2-9. Preprocessor Command-Line Switch Summary
Switch Name
-cstring
Description
Enables the “stringization” operator and provides C compiler-style preprocessor behavior
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-45
Preprocessor Command-Line Reference
Table 2-9. Preprocessor Command-Line Switch Summary (Cont’d)
Treats as a comment all text after “
!
” on a single line
-cs!
-cs/*
-cs//
-cs{
-csall
–Dmacro[=definition]
-h[elp]
–i
–i|Idirectory
–l
-M
-MM
-Mo filename
-Mt filename
–o filename
–stringize
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)
2-46 VisualDSP++ 5.0 Assembler and Preprocessor Manual
Preprocessor
Table 2-9. Preprocessor Command-Line Switch Summary (Cont’d)
Treats “.” (dot) as an operator when parsing identifiers
–tokenize-dot
(
)
–Uname
–v[erbose]
–version
w
-
Wnumber
-warn
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-47
Preprocessor Command-Line Reference
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
• 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.
2-48 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-49
Preprocessor Command-Line Reference
-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
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.
2-50 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
. 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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-51
Preprocessor Command-Line Reference
-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
option. To direct the make dependencies to a file, use the
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
-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
.
2-52 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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
for more information.
-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
) 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
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
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-53
Preprocessor Command-Line Reference
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.
2-54 VisualDSP++ 5.0 Assembler and Preprocessor Manual
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.
VisualDSP++ 5.0 Assembler and Preprocessor Manual 2-55
Preprocessor Command-Line Reference
2-56 VisualDSP++ 5.0 Assembler and Preprocessor Manual
I INDEX
Symbols
? preprocessor operator,
Numerics
1.0r fract,
32-bit initialization
A
absolute address,
address alignment,
ADDRESS () assembler operator, 1-51
__ADSP21065L__ macro,
VisualDSP++ 5.0 Assembler and Preprocessor Manual
__ADSP21363__ macro,
__ADSP21364__ macro,
__ADSP21365__ macro,
__ADSP21367__ macro,
__ADSP21368__ macro,
__ADSP21369__ macro,
__ADSPBF522__ macro,
__ADSPBF525__ macro,
__ADSPBF527__ macro,
__ADSPBF532__ macro,
__ADSPBF533__ macro,
__ADSPBF534__ macro,
__ADSPBF535__ macro,
__ADSPBF536__ macro,
__ADSPBF537__ macro,
__ADSPBF538__ macro,
__ADSPBF539__ macro,
__ADSPBF561__ macro,
__ADSPTS101__ macro,
__ADSPTS201__ macro,
__ADSPTS202__ macro,
__ADSPTS203__ macro,
.ALIGN (address alignment) assembler directive,
-align-branch-lines assembler switch,
.ALIGN_CODE (code address alignment) assembler directive,
aligning branch instructions, 1-146
-anomaly-detect assembler switch, 1-147
-anomaly-warn assembler switch, 1-147
I-1
INDEX
anomaly warnings, displaying,
,
-anomaly-workaround assembler switch,
archiver, object file input to,
arithmetic fractional,
ASCII string directive,
string initialization,
,
.ASCII assembler directive,
,
assembler
command-line syntax,
,
expressions, constant and address, 1-49
instruction set,
,
numeric bases,
operators,
overview,
producing code suitable for the specified processor,
running from command line, 1-140
run-time environment,
SHARC feature macros,
source files (.ASM),
assembler
symbols,
(continued)
TigerSHARC feature macros, 1-27
assembler directives
.ALIGN,
.ALIGN_CODE,
.BSS,
.EXTERN STRUCT,
.FILE_ATTR,
.FILE (override filename),
.GLOBL,
.INC/BINARY,
.LEFTMARGIN,
.LIST,
.LIST_DEFTAB,
.LIST_LOCTAB,
.LIST_WRAPDATA,
,
.NOLIST_DATFILE,
.NOLIST_WRAPDATA,
.PAGEWIDTH,
.PORT,
I-2 VisualDSP++ 5.0 Assembler and Preprocessor Manual
INDEX
assembler directives
.PREVIOUS,
.PRIORITY,
.ROUND_NEAREST,
.SECTION,
(continued)
.SEPARATE_MEM_SEGMENTS,
,
.SET,
.SHORT,
.TEXT,
.VAR,
assembler switches
-align-branch-lines,
-anomaly-detect,
,
-anomaly-warn,
-anomaly-workaround,
-char-size-8,
-char-size-any,
-D (defines) option for the
-default-branch-np,
-double-size-any,
-expand-symbolic-links,
-expand-windows-shortcuts,
-g (generate debug info), 1-154
VisualDSP++ 5.0 Assembler and Preprocessor Manual assembler switches
(continued)
-i (include directory path), 1-156
-I (include search path) option for the
-flags-compiler switch,
-li (listing with include),
-l (named listing file), 1-157
-MM (generate make rule and assemble),
-Mo (output make rule),
-Mt (output make rule for named
--no-anomaly-workaround,
-no-expand-symbolic-links, 1-160
-no-expand-windows-shortcuts,
-no-temp-data-file,
-pp (proceed with preprocessing),
-save-temps (save intermediate files),
-si-revision version (silicon revision),
-sp (skip preprocessing), 1-163
-stallcheck,
-version (display version),
-v (verbose),
-Winfo number (informational
-Wno-info (no informational messages),
-Wnumber (warning suppression), 1-165
-w (skip warning messages), 1-164
-Wwarn number,
I-3
INDEX
assembly code, embedding (inline) in your
C or C++ program,
assembly language constant, 2-49
assembly language programs, writing, 1-3
attributes, creating in object files, 1-84
B
backslash character,
BITPOS() assembler operator, 1-51 ,
block initialization section qualifiers, 1-123
branch
,
branch lines default to NP,
.BSS assembler directive, 1-66
built-in functions
,
SIZEOF,
.BYTE4/R32 assembler directive, for 32-bit
.BYTE/ .BYTE2/ .BYTE4 assember
C
C/C++ run-time library, initializing, 1-124
CHAR32 section qualifier,
CHAR8 section qualifier, 1-122
CHARANY section qualifier, 1-122
-char-size-32 assembler switch,
-char-size-8 assembler switch, 1-148
-char-size-any assembler switch, 1-149
circular buffers, setting, 1-53
,
comma-separated options, 1-153
## (concatenate) preprocessor operator,
concatenate (##) preprocessor operator,
I-4 conditional assembly directives
constant expressions,
conventions comment strings,
file extensions, 1-141 file names, 1-141
numeric formats,
user-defined symbols,
-cpredef (C-style definitions) preprocessor
C programs
C++ programs
-csall (all comment styles) preprocessor
-cs! (! comment style) preprocessor switch,
-cs/* (/* */ comment style) preprocessor
-cs// (// comment style) preprocessor
-cs{ ({ } comment style) preprocessor
-cstring (C style) preprocessor switch, 2-47
C structs, in assembly source, 1-20
D
-D__2102x__ macro,
-D__2106x__ macro,
-D__2116x__ macro,
-D__2126x__ macro,
-D__2136x__ macro,
-D__2636x__ macro,
VisualDSP++ 5.0 Assembler and Preprocessor Manual
INDEX
-D__ADSP21020__ macro,
-D__ADSP2116x__ macro,
-D__ADSP2126x__ macro,
-D__ADSP21371__ macro,
-D__ADSP21375__ macro,
-D__ADSP2137x__ macro,
,
-D__ADSPBLACKFIN__ macro,
-D__ADSPTS20x__ macro,
-D__ADSPTS__ macro,
DATA64 (64-bit word section) qualifier,
.DATA assembler directive,
.dat files,
-D (define macro) assembler switch,
-D (define macro) preprocessor switch,
-D (defines) command-line option,
see-flags-compiler switch debugging
information, generating,
-default-branch-np assembler switch, 1-149
-default-branch-p assembler switch,
#define (macro) preprocessor command,
defining macros,
,
dependencies, from buffer initializations,
directives, assembler,
-D_LANGUAGE_ASM macro,
,
-D_LANGUAGE_C macro,
.dlb files,
DMAONLY section qualifier,
DM (data), 40-bit word section qualifier,
.doj files,
,
DOUBLE32 section qualifier, 1-121
DOUBLE64 section qualifier, 1-121
DOUBLEANY section qualifier,
-double-size-32 assembler switch, 1-150
-double-size-64 assembler switch, 1-150
-double-size-any assembler switch,
DWARF2 function information, 1-154
E
easm21k assembler driver,
easmblkfn assembler driver,
easmts assembler driver,
ELF.h header file,
.ELIF conditional assembly directive, 1-58
#elif (else if) preprocessor command, 2-26
#else (alternate instruction) preprocessor command,
.ELSE conditional assembly directive, 1-59
.ENDIF conditional assembly directive,
#endif (termination) preprocessor command,
end labels marking ending function boundaries,
VisualDSP++ 5.0 Assembler and Preprocessor Manual I-5
INDEX
.ENDSEG assembler directive,
#error (error message) preprocessor command,
-expand-symbolic-links assembler switch,
-expand-windows-shortucts assembler
expressions address,
.EXTERN (global label) assembler
.EXTERN STRUCT assembler directive,
F
feature assembler macros
-D__ADSP21000__,
-D__ADSP21020__,
-D__ADSP21060__,
-D__ADSP21061__,
-D__ADSP21062__,
-D__ADSP21065L__,
-D__ADSP21160__,
-D__ADSP21161__,
-D__ADSP21261__,
-D__ADSP21262__,
-D__ADSP21266__,
-D__ADSP21267__,
-D__ADSP21363__,
-D__ADSP21364__,
-D__ADSP21365__,
-D__ADSP21366__,
-D__ADSP21367__,
-D__ADSP21368__,
-D__ADSP21369__,
-D__ADSP21371__,
-D__ADSP21375__,
I-6 feature assembler macros
-D__ADSPBF531__,
(continued)
-D__ADSPBF532__,
-D__ADSPBF533__,
,
-D__ADSPBF535__,
-D__ADSPBF536__,
-D__ADSPBF537__,
-D__ADSPBF538__,
-D__ADSPBF539__,
-D__ADSPBF561__,
-D__ADSPTS__,
-D__ADSPTS101__,
-D__ADSPTS201__,
-D__ADSPTS202__,
-D__ADSPTS203__,
,
feature preprocessor macros
__ADSP21065L__,
VisualDSP++ 5.0 Assembler and Preprocessor Manual
INDEX
feature preprocessor macros
(continued)
__ADSPBLACKFIN__,
__ADSPTS__,
-D_LANGUAGE_ASM,
.FILE_ATTR assembler directive, 1-84
-file-attr (file attribute) assembler switch,
file format, ELF (Executable and Linkable
Format),
__FILE__ macro,
.FILE (override filename) assembler
files
.dat (data),
.dlb (library),
.doj (object),
.is (preprocessed assembly), 1-161
,
list of extensions,
naming conventions,
-flags-compiler assembler switch,
-flags-pp assembler switch, 1-153
floating-point precision,
four-byte data initializer lists,
fractional arithmetic,
fracts
mixed type arithmetic,
signed values,
G
-g (generate debug info) assembler switch,
.GLOBAL (global symbol) assembler directive,
.GLOBL assembler directive,
H
hardware anomalies, warnings displaying,
,
header files system,
tokens,
user,
hex value, decoding,
.h files,
-h (help) assembler switch,
,
HI () assembler operator,
VisualDSP++ 5.0 Assembler and Preprocessor Manual I-7
INDEX
I
-I assembler switch, see -flags-compiler
switch
.IF conditional assembly directive, 1-58
#ifdef (test if defined) preprocessor command,
#ifndef (test if not defined) preprocessor command,
#if (test if true) preprocessor command,
-i (include directory path) assembler switch,
-i (include directory) preprocessor switch,
-I (include search-path)) assembler option,
-i (less includes) preprocessor switch,
.IMPORT assembler directive,
.INC/BINARY assembler directive, 1-90
.INCBIN assembler directive,
include files system header files,
user header files,
#include (insert a file) preprocessor command,
#include preprocessor command,
initialization section qualifiers,
INPUT_SECTION_ALIGN() LDF command,
1-71 input section alignment instruction, 1-71
intermediate source file (.is), 1-5
-I- (search system include files)
.is (preprocessed assembly) files, 1-161
,
K
,
L
__LASTSUFFIX__ macro,
,
.ldf files,
,
.LEFTMARGIN assembler directive,
legacy directives
.PORT,
.SEGMENT/.ENDSEG,
LENGTH () assembler operator,
-li (listing with include) assembler switch,
#line (output line number) preprocessor command,
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,
.LIST_DEFTAB assembler directive,
listing files
assembly process information, 1-5
assembly source code,
C data structure information, 1-5
data opcodes,
large opcodes,
.lst extension,
,
named,
opcode,
producing,
.LIST_LOCTAB assembler directive,
.LIST_WRAPDATA assembler directive,
I-8 VisualDSP++ 5.0 Assembler and Preprocessor Manual
INDEX
-l (named listing file) assembler switch,
LO () assembler operator,
local symbols,
local tab width,
.LONG assember directives,
long-form initialization,
.lst files,
M
macro argument, converting into string
macros assembler feature,
Blackfin feature assembler,
debugging,
defining,
defining with variable length argument
definition rules,
-D__VISUALDSPVERSION__,
feature assembler,
predefined preprocessor,
preprocessor feature,
TigerSHARC assembler feature,
writing,
memory
RAM (random access memory), 1-123
type, PM (code and data),
types,
.MESSAGE assembler directive,
-micaswarn assembler switch,
-M (make rule only) assembler switch,
-M (make rule only) preprocessor switch,
-MM (make rule and assemble) assembler
-MM (make rule and assemble)
-Mo (output make rule) assembler switch,
-Mo (output make rule) preprocessor
-Mt (output make rule for named file) assembler switch,
multi-issue conflict warnings,
N
N boundary alignment,
nested struct references,
.NEWPAGE assembler directive, 1-104
,
--no-anomaly-workaround assembler
-no-expand-symbolic-links assembler
-no-expand-windows-shortucts assembler
NO_INIT memory section,
.NOLIST assembler directive, 1-92
.NOLIST_DATA assembler directive,
.NOLIST_DATFILE assembler directive,
.NOLIST_WRAPDATA assembler directive,
-no-source-dependency assembler switch,
VisualDSP++ 5.0 Assembler and Preprocessor Manual I-9
INDEX
-no-temp-data-file assembler switch,
-nowarn preprocessor switch,
O
object files
.DOJ extension,
producing,
OFFSETOF() built-in function,
-o (output) assembler switch, 1-161
-o (output) preprocessor switch, 2-53
opcodes, large,
P
.PAGELENGTH assembler directive,
.PAGEWIDTH assembly directive,
PM (48-bit word section) qualifier,
.PORT (declare port) assembler legacy
,
-pp (proceed with preprocessing) assembler
#pragma preprocessor command, 2-36
.PRECISION assembler directive,
predefined preprocessor macros
__DATE__,
__LINE__,
preprocessor assembly files,
command syntax,
-csall (all comment styles) switch,
-cs/* (/* */ comment style) switch,
-cs// (// comment style) switch,
-cs{ ({ } comment style) switch, 2-49
-cs! switch,
-cstring (C style) switch,
-D (define macro) switch, 2-49
-h (help) switch,
-i (include path) switch, 2-50
-i (less includes) switch,
-I- (search system include files) switch,
-M (make rule only) switch, 2-52
-MM (make rule and assemble) switch,
-Mo (output make rule) switch, 2-52
-Mt (output make rule for named file)
-notokenize-dot switch,
-nowarn switch,
-o (output) switch,
option settings,
output file (.IS extenstion),
predefined macros,
running from command line,
-stringize switch,
I-10 VisualDSP++ 5.0 Assembler and Preprocessor Manual
INDEX
preprocessor
-tokenize-dot switch,
user header files,
(continued)
-version (display version) switch, 2-54
-warn (print warnings) switch, 2-55
-Wnumber (warning suppression)
-w (skip warning messages) switch,
preprocessor commands
#else,
#error,
#if,
#ifdef,
#line (counter),
#pragma,
#undef,
#warning,
... preprocessor operator, 2-24
preprocessor operators,
? (generate unique label),
## (concatenate),
# (stringization),
.PREVIOUS assembler directive,
-proc (target processor) assembler switch,
programs
listing files,
writing assembly,
VisualDSP++ 5.0 Assembler and Preprocessor Manual project settings assembler,
Q
qualifier,
question mark (?) preprosessor operator,
R
R32 qualifier,
relational expressions,
operators,
RESOLVE() command (in LDF), 1-133
rounding modes,
.ROUND_MINUS (rounding mode) assembler directive,
.ROUND_NEAREST (rounding mode) assembler directive,
.ROUND_PLUS (rounding mode) assembler directive,
.ROUND_ZERO (rounding mode) assembler directive,
RUNTIME_INIT section qualifier,
S
-save-temps (save intermediate files) assembler switch,
searching, system include files,
section
qualifier, DM (data memory),
1-123 qualifier, PM (code and data), 1-123
qualifier, RAM (random access memory),
type identifier,
I-11
INDEX
.SECTION (start or embed a section) assembler directive,
initialization qualifiers, 1-123
.SEGMENT (legacy directive) assembler
.SEPARATE_MEM_SEGMENTS assembler directive,
.SET assembler directive,
settings assembler options, from command line,
assembler options, from VisualDSP++
preprocessor options, build tools,
preprocessor options, command line,
preprocessor options, VisualDSP++,
SHF_INIT flag,
SHORT assember directives,
.SHORT EXPRESSION-LIST assembler
short-form initialization,
SHT_DEBUGINFO section type,
SHT_PROGBITS identifier,
SHT_PROGBITS section type, 1-121
__SILICON_REVISION__ macro, 1-163
-si-revision (silicon revision) assembler
SIZEOF() built-in function,
source files (.ASM),
special operators, assembler,
I-12
-sp (skip preprocessing) assembler switch,
-stallcheck assembler switch, 1-163 stall information, 1-163
statistical profiling, enabling in assembler
# (stringization) preprocessor operator,
-stringize (double quotes) preprocessor struct
,
member initializers,
references,
,
variable,
struct references, nested, 1-64
.STRUCT (struct variable) assembler directive,
STT_OBJECT symbol type,
switches, see assembler command-line
switches
switches, see preprocessor command-line
switches symbol
types,
symbolic expressions,
symbols, see assembler symbols
symbol type,changing default, 1-132
syntax assembler command line,
assembler directives,
instruction set,
preprocessor command,
VisualDSP++ 5.0 Assembler and Preprocessor Manual
INDEX
searching,
T
tab characters source files,
,
tab width changing,
default,
temporary data file, not written to a
.TEXT assembler directive,
__TIME__ macro,
-tokenize-dot (identifier parsing)
trailing zero character,
two-byte data initializer lists, 1-70
.TYPE (change default type) assembler
U
-Uname preprocessor switch,
#undef (undefine) preprocessor command,
unique labels, generating, 2-42
V
__VA_ARGS__ identifier,
.VAR and .VAR/INIT24 (declare variable) assembler directives,
.VAR (data variable) assembler directive,
... (variable-length argument list), 2-24 variable length argument list, 2-24
-version (display version) assembler switch,
-version (display version) preprocessor
VisualDSP++
assembler settings,
assembling from,
Project Options dialog box,
,
setting assembler options, 1-33
,
setting preprocessor options,
-v (verbose) assembler switch, 1-163
-v (verbose) preprocessor switch, 2-54
W
WARNING ea1121, missing end labels,
warnings
printing,
2-55 suppressing, see -Wnumber (warning
suppression) preprocessor switch
#warning (warning message) preprocessor command,
-warn (print warnings) preprocessor switch,
.WEAK assembler directive, 1-138 weak symbol binding, 1-138
-Werror number assembler switch,
-Winfo number (informational messages) assembler switch,
-Wno-info (no informational messages) assembler switch,
-Wnumber (warning suppression) assembler switch,
-Wnumber (warning suppression)
wrapping, opcode listings,
writing assembly programs, 1-3
VisualDSP++ 5.0 Assembler and Preprocessor Manual I-13
INDEX
-w (skip warning messages) assembler
-w (skip warning messages) preprocessor
-Wsuppress number assembler switch,
-Wwarn-error assembler switch, 1-165
-Wwarn number assembler switch, 1-165
Z
ZERO_INIT memory section,
I-14 VisualDSP++ 5.0 Assembler and Preprocessor Manual
advertisement
Key Features
- Assembler and Preprocessor Manual
- SHARC (ADSP-21xxx) processors
- TigerSHARC (ADSP-TSxxx) processors
- Blackfin (ADSP-BFxxx) processors
- Legacy syntax
- Assembler and preprocessor directives
- Command-line switches
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
advertisement
Table of contents
- 17 MyAnalog.com
- 18 Processor Product Information
- 19 Related Documents
- 20 Online Technical Documentation
- 21 Accessing Documentation From VisualDSP++
- 21 Accessing Documentation From Windows
- 22 Accessing Documentation From the Web
- 22 Printed Manuals
- 22 Hardware Tools Manuals
- 22 Processor Manuals
- 23 Data Sheets
- 27 Assembler Overview
- 27 Writing Assembly Programs
- 30 Program Content
- 31 Program Structure
- 44 Program Interfacing Requirements
- 44 Using Assembler Support for C Structs
- 47 Preprocessing a Program
- 49 Using Assembler Feature Macros
- 53 -D__VISUALDSPVERSION__ Predefined Macro (Assembler)
- 55 Make Dependencies
- 56 Reading a Listing File
- 57 Statistical Profiling for Assembly Functions
- 60 Assembler Keywords and Symbols
- 73 Assembler Expressions
- 74 Assembler Operators
- 79 Numeric Formats
- 79 Fractional Type Support
- 82 Comment Conventions
- 82 Conditional Assembly Directives
- 86 C Struct Support in Assembly Built-In Functions
- 86 OFFSETOF Built-In Function
- 86 SIZEOF Built-In Function
- 87 Struct References
- 90 Assembler Directives
- 95 .ALIGN, Specify an Address Alignment
- 97 .ALIGN_CODE, Specify an Address Alignment
- 99 .ASCII
- 100 .BYTE, Declare a Byte Data Variable or Buffer
- 104 .EXTERN, Refer to a Globally Available Symbol
- 105 .EXTERN STRUCT, Refer to a Struct Defined Elsewhere
- 107 .FILE, Override the Name of a Source File
- 108 .FILE_ATTR, Create an Attribute in the Object File
- 109 .GLOBAL, Make a Symbol Available Globally
- 111 .IMPORT, Provide Structure Layout Information
- 114 .INC/BINARY, Include Contents of a File
- 115 .LEFTMARGIN, Set the Margin Width of a Listing File
- 116 .LIST/.NOLIST, Listing Source Lines and Opcodes
- 117 .LIST_DATA/.NOLIST_DATA, Listing Data Opcodes
- 118 .LIST_DATFILE/.NOLIST_DATFILE, Listing Data Initialization Files
- 119 .LIST_DEFTAB, Set the Default Tab Width for Listings
- 121 .LIST_LOCTAB, Set the Local Tab Width for Listings
- 122 .LIST_WRAPDATA/.NOLIST_WRAPDATA
- 123 .LONG, Defines and initializes 4-byte data objects
- 124 .MESSAGE, Alter the Severity of an Assembler Message
- 128 .NEWPAGE, Insert a Page Break in a Listing File
- 129 .PAGELENGTH, Set the Page Length of a Listing File
- 130 .PAGEWIDTH, Set the Page Width of a Listing File
- 132 .PORT, Legacy Directive
- 133 .PRECISION, Select Floating-Point Precision
- 135 .PREVIOUS, Revert to the Previously Defined Section
- 136 .PRIORITY, Allow Prioritized Symbol Mapping in Linker
- 139 .REFERENCE, Provide Better Info in an X-REF File
- 140 .RETAIN_NAME, Stop Linker from Eliminating Symbol
- 141 .ROUND_, Select Floating-Point Rounding
- 144 .SECTION, Declare a Memory Section
- 150 .SEGMENT and .ENDSEG, Legacy Directives
- 150 .SEPARATE_MEM_SEGMENTS
- 151 .SET, Set a Symbolic Alias
- 151 .SHORT, Defines and initializes 2-byte data objects
- 152 .STRUCT, Create a Struct Variable
- 156 .TYPE, Change Default Symbol Type
- 157 .VAR, Declare a Data Variable or Buffer
- 162 .WEAK, Support Weak Symbol Definition and Reference
- 164 Running the Assembler
- 166 Assembler Command-Line Switch Descriptions
- 170 -align-branch-lines
- 171 -anomaly-detect [id1[,id2...]]
- 171 -anomaly-warn {id1[,id2]|all|none}
- 172 -anomaly-workaround [id]
- 172 -char-size-8
- 172 -char-size-32
- 173 -char-size-any
- 173 -default-branch-np
- 173 -default-branch-p
- 173 -Dmacro[=definition]
- 174 -double-size-32
- 174 -double-size-64
- 175 -double-size-any
- 175 -expand-symbolic-links
- 175 -expand-windows-shortcuts
- 175 -file-attr attr[=val]
- 175 -flags-compiler
- 177 -flags-pp -opt1 [,-opt2...]
- 178 -g
- 179 -h[elp]
- 180 -i
- 181 -l filename
- 181 -li filename
- 181 -M
- 182 -MM
- 182 -Mo filename
- 182 -Mt filename
- 183 -micaswarn
- 183 -no-source-dependency
- 183 -no-anomaly-detect [id1[,id2...]]
- 183 -no-anomaly-workaround [id1[,id2...]]
- 184 -no-expand-symbolic-links
- 184 -no-expand-windows-shortcuts
- 184 -no-temp-data-file
- 185 -o filename
- 185 -pp
- 185 -proc processor
- 186 -save-temps
- 186 -si-revision version
- 187 -sp
- 188 -stallcheck
- 188 -v[erbose]
- 188 -version
- 188 -w
- 189 -Werror number[,number]
- 189 -Winfo number[,number]
- 189 -Wno-info
- 189 -Wnumber[,number]
- 190 -Wsuppress number[,number]
- 190 -Wwarn number[,number]
- 190 -Wwarn-error
- 191 Specifying Assembler Options in VisualDSP++
- 197 Writing Preprocessor Commands
- 198 Header Files and the #include Command
- 199 System Header Files
- 199 User Header Files
- 200 Sequence of Tokens
- 201 Include Path Search
- 201 Writing Macros
- 203 Macro Definition and Usage Guidelines
- 206 Examples of Multi-Line Code Macros with Arguments
- 207 Debugging Macros
- 209 Using Predefined Preprocessor Macros
- 213 -D__VISUALDSPVERSION____ Predefined Macro (Preprocessor)
- 214 Specifying Preprocessor Options
- 215 Preprocessor Commands and Operators
- 217 #define
- 220 #elif
- 221 #else
- 222 #endif
- 223 #error
- 224 #if
- 225 #ifdef
- 226 #ifndef
- 227 #include
- 229 #line
- 230 #pragma
- 231 #undef
- 232 #warning
- 233 # (Argument)
- 235 ## (Concatenate)
- 236 ? (Generate a unique label)
- 238 Running the Preprocessor
- 239 Preprocessor Command-Line Switches
- 241 -cstring
- 242 -cs!
- 242 -cs/*
- 243 -cs//
- 243 -cs{
- 243 -csall
- 243 -Dmacro[=def]
- 243 -h[elp]
- 244 -i
- 244 -i
- 245 -I-
- 246 -M
- 246 -MM
- 246 -Mo filename
- 247 -Mt filename
- 247 -o filename
- 247 -stringize
- 247 -tokenize-dot
- 248 -Uname
- 248 -v[erbose]
- 248 -version
- 248 -w
- 249 -Wnumber
- 249 -warn