Analog Devices ee-130 Application Notes

a

a Engineer To Engineer Note EE-130

aa

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

The syntax for the ELF assembler directives is

Making a Fast Transition from
ADSP-21xx to ADSP-219x

common across ADI ELF assemblers. The IDE
provides a common environment and options.
The VisualDSP debugger is based on the robust

Contributed by Barbara Zino

and complete DWARF-2 format.

Version 1.2

See also: App Note "A Quick Primer on ELF
and DWARF-2".

Introduction

Whether you are upgrading existing 21xx code
or writing new code, you will want to be aware
of what is new and different with the ADSP­219x instruction set and tools.

This application note was written for anyone
who is coming on-board with ADSP-219x and
would like detailed information on the
assembler tools. It is intended to assist in:

1) Upgrading existing 21xx assembly code to
ADSP-219x

2) Writing new assembly code for the ADSP­219x

For a complete description of the ADSP-219x,
please see the ADSP-219x DSP Instruction Set
Reference (Part 82-00390-02).

ELF and DWARF-2

The ADSP-219x assembler and linker are part
of the new family of ADI ELF assemblers and
linkers that operate within the VisualDSP IDE
environment.

The tools produce industry standard formats:

• ELF Object File Format

• DWARF-2 Debugging Format

Getting Started

To assist in the upgrade of existing 21xx
applications, the assembler can optionally
process legacy syntax.

If you are using the command line version of the
new assembler or the IDE, the default is the new
ELF assembler directives:

easm219x myNew.asm

Specify the -legacy option to have the 5.x/6.x
syntax accepted by the new assembler: In
addition, you will likely want to specify the -c
option. This makes the 21xx -legacy case
sensitive:

easm219x -legacy -c myLegacy.dsp

The -legacy assembler option processes the
21xx directives and syntax that pre-date the new
family of ELF assemblers. The assembler
legacy option allows you to focus on core issues
and ignore syntax differences.

To enable assemble legacy code within the IDE
build environment:

Project Options

Assemble

Additional Options

Add "-legacy -c"

Copyright 2000, Analog Devices, Inc. All rights reserved. Analog Devices assumes no responsibility for customer product design or the use or application of customers’ products or
for any infringements of patents or rights of others which may result from Analog Devices assistance. All trademarks and logos are property of their respective holders. Information
furnished by Analog Devices Applications and Development Tools Engineers is believed to be accurate and reliable, however no responsibility is as sumed by Analog Devices
regarding the technical accuracy of the content provided in all Analog Devices’ Engineer-to-Engineer Notes.

When Upgrading Existing Code

• Assemble with -legacy

• Review instruction diagnostics (if any)

and revise to ADSP-219x

When Writing New Code

• Code with new ELF directives

• Do not use the -legacy option

Please note that you cannot mix "old and new"
syntax in the same assembly source file. You
can combine "old and new" in the same
application by assembling distinct source files
that are then linked together.

Resulting error with 9x assembler:

[Error E24] "MYSQRT.DSP":61
Assembler Error: 218x to 219x incompatibility:
No More POS or NEG.
Must use CCODE register.

Solution:
Use CCODE register.

"SE" IS NO LONGER D-REGISTER

218x code:
AX0=SE, SR=NORM MR1 (HI);

Resulting error with 9x assembler:

[Error E22] "MYSQRT.DSP":32

Illegal Multi Instruction Formation
Instruction Component: register move
Instruction Component: shift

Upgrading Existing Code

Some existing 21xx assembly applications will
require no source code changes. Others may
need changes for the ADSP-219x core
instruction set. Here is a sampling of 21xx
legacy code with invalid ADSP-219x
instructions and the assembler messages that are
reported after passing the code through the
ADSP-219x assembler. These are the places in
the code that you need to change.

The following diagnostics are reported whether
or not the -legacy option is in effect. The -legacy
option in the 9x assembler is for 21xx syntax
compatibility only, not instruction compatibility.
For 8x processing, use the -legacy option with
the 8x assembler.

easm218x -legacy -c myApp.dsp

No NEG or POS CONDITION

218x code:
pwr_ok: IF NEG JUMP frac;

Solution:
Since SE is no longer a DREG (group 0
register), its use in a multi function move is
illegal. Select one of the ADSP-219x DREG.

“MF" REGISTER REPLACED

218x code:

MF=AR*MY0 (RND), MX0=DM(I3,M3);
MR=MR+MX0*MF (SS), MX0=DM(I3,M3);
approx: MF=AR*MF (RND);

Resulting error with 9x assembler:

"MYSQRT.DSP":38 Invalid Register 'MF':
Illegal destination register for MACC instruction

Solution:
The 21xx MF register has been replaced
by the 219x SR2-SR0 dual accumulator

CCODE LATENCY

218x code:

ccode=0x03;
if not swcond ar = mr0 and 8192;

EE-130 Page 2

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

Resulting warning with 9x assembler:

[Warning W35] “CcodeLatency.asm":26
Assembler Warning: Detected a CCODE latency
problem. The CCODE write is immediately followed
by a CCODE conditional check. There is a 1-cycle
latency between writing to the CCODE register and
testing the condition. There is no stall in the
sequencer. If you don't add an instruction after the
CCODE write, your conditional check will be based
on the old CCODE!

Solution:

// CCODE latency accounted for
ccode=0x03;
i0=1;
if not swcond ar = abs ax0;

WRITING NEW CODE

When you write new code, use the ELF
directives that are common across the ADI ELF
assemblers. There are three ELF directives that
are the building blocks of any ELF assembly
program. Think of them as "The Three
Musketeers":

.SECTION DIRECTIVE

Sections are named contiguous locations of
program or data memory.

.section ( sectionQualifiers )+
sectionName sectionType? ;

One or more section qualifiers indicate the
section properties. Section qualifiers begin with
"/". For example "/dm" or "/pm".

The section type is optional and the default is
SHT_PROGBITS. It is unlikely you will ever
need to override the section type for sections in
ELF binary object file for your application so
you can just ignore this paragraph altogether ☺.

.SECTION Examples

.section/pm program;

.section/dm data1;

1) .SECTION

2) .VAR

3) .GLOBAL

NOTATION

The notation used to describe the syntax in this
document:

* 0 or more

+ 1 or more

? Optional item (0 or 1 may appear)

There are some advantages to using .section
directives:

• Permits multiple code sections

• Gives you more control over data placement

• Readable displays via the ElfDump utility

Multiple /pm (/code) .sections are allowed in
219x. In 21xx there was only a single .module
(code section).

In 219x, you determine placement of data
buffers in the assembler source by locating them
within the desired section. This differs from
21xx where the linker placed the data buffers at
locations of its own choosing.

EE-130 Page 3

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

You specify section placement in memory in the
LDF (Linker-Description-File) for your
application. For more info on LDF files, see the
Linker Guide "LDF Programming Examples",
"Linker Description File Reference" and the
Overlay Example for the 2192-12.

ELFDUMP

The ElfDump utility shows the contents of
object and executable files in a readable format.
It has many options. Total section size and
variable placement within each section are
easily viewed via ElfDump section displays.

.VAR INITIALIZATION

The -legacy directives separated the .VAR/DM
and .VAR/PM declarations from the .INIT or
.INIT24 initializations. The new style is an "all
in one" declare and initialize.

The default is to treat the .VAR initializers as 16
bit constants. 24 bit constants are supported via
the /INIT24 qualifier on the .VAR directive.

The default for the .VAR directive initialization
is to treat the initializers as 16 bit constants.

DM Data Variable 16 Bit Initialization

For example, if you want to see a code
disassembly (mnemonic display) of section
"program" in the object file file9x:

elfdump -ni program file9x.doj

Please run ElfDump -help for the complete list
of options.

.VAR DIRECTIVE

The .VAR directive defines and initializes data
objects.

.var ( /init24 )? variableName

( '[' expression ']' )?

( '=' initializerList )? ;

.var ( /init24 )? variableName

(, variableName )* ;

.var ( /init24 )? '=' expression ','

( ',' expression)* ;

.section/dm data1;
.var buffer[2] = 0x1234, 0x4321;

16 bit PM data is correctly padded by the
assembler:

PM Data Variable 16 Bit Initialization

.section/pm program;
.var buffer[3] =

0x1234, 0x3210, 0x2130;

// 16 bit initialization in 24 bit
// memory with padding:

123400
321000
213000

To get a 24 bit constant initialization, specify
.var/init24.

PM Data Variable 24 Bit Initialization

.VAR directives must be within a section.

EE-130 Page 4

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

.section/pm program;
.var/init24 GiveMe24 = 0x123456;

Recommendation:

MEMORY REFERENCE SYNTAX

Use the .VAR form with explicit sizing for
initialization. For example:

#define bufferSize 5
.section/data data1;
.var bufferOk[bufferSize]= 1,2,3,4,5;
.var bufferTooFew[bufferSize]= 1,2,3;

The assembler provides error diagnostics for an
incorrect # of initializers if you use the form of
the syntax with an explicit declarator followed
by its initializers. In the example above, the
bufferTooFew .VAR directive is explicitly
declared with 5 elements. Only 3 elements are
initialized and the assembler reports the
discrepancy.

[Warning W41] "test.asm":4 'bufferTooFew':
Too few initializers specified.
Expected 5 but found 3. The remaining 2
elements were initialized to zero.

.GLOBAL DIRECTIVE

Symbols declared as global are program scope
and are thus visible outside the local file. By
default, symbols are file scope (local). The
.global directive must be used to export a
symbol.

The ELF directives were designed with the
syntax and semantics of C in mind. Memory
reference notation has been extended to the
more familiar C-style. You may find this
notation self-documenting and less prone to
error or you may prefer to keep coding in the
style you are already accustomed to.

Note: The -legacy option is not needed to
process old memory reference syntax where the
ordering of the operands determined the action
taken. The new assembler always accepts both
the old and new memory reference syntax styles.

" SEE APPENDIX A:

MEMORY REFERENCE SYNTAX

The following examples are identified by
description and the instruction type number as
defined in the 219x Instruction Set Guide.

// Type 4 :
// Multifunction ALU or MACC with memory
// read or write using DAG post-modify
//
AF=AF+1,AX0=DM(I0,M1); ! legacy
AF=AF+1,AX0=DM(I0+=M1); // new syntax

// Type 21 : DAG Modify
//
MODIFY(I4,M5); ! legacy
MODIFY(I4+=M5); // new syntax

If another file needs to access the symbol,
specify .global in the file that declares it and
.extern in the file(s) that references it.

.global symbol (, symbol )* ;

.GLOBAL Example

.global Function1, Function2;

Function1:

ax1 = dm(1, i4);

Function2:

EE-130 Page 5

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

// Type 21a : DAG Immediate Modify
//
MODIFY(I4,3); ! legacy
MODIFY(I4+=3); // new syntax

// Type 29: DAG Memory Read/Write
// with Immediate Modify (Post-modify with
// update or offset without update)
//
DM(2,I1)=MR1; ! offset
DM(I1+2)=MR1; // offset, new syntax

// Type 32:
// Pre-modify offset/
// Post-modify Update
// DAG memory read/write
//
DM(M5,I4)=m3; ! pre-modify offset
DM(I4+M5)=m3; // new syntax

PRE-PROCESSOR

Here are the pre-processor basics:

EASM219x -legacy

Pre-Processing Flow of Control

• The pre-processor for the 219x assembler
and linker is the C style pre-processor
pp.exe. This is the same pre-processor used
by the other ELF assemblers and linkers,
including 21k, 2116x, and TigerSharc.

• The pre-processor for 21xx is asmpp.exe. To
preserve legacy code pre-processing, specify
the -legacy option and the 219x assembler
will call asmpp.exe as an additional pre­processing step after the pp.exe pre­processor.

• Specify the -sp (skip preprocessor) option
and neither pre-processor will be called.

Pre-Processor Flow Of Control

The 219x pre-processor produces "*.is" output
files. The naming convention for ADSP-219x
assembly source suffixes is .ASM.

EXAMPLE.DSP

#

PP.EXE

#

EXAMPLE.IS

#

ASMPP.EXE

#

EXAMPLE.APP

By default, the pre-processor files are written to
the temporary directory as specified by the
environment variable TMP on the PC (or
TMPDIR on Unix). The temporary files are
deleted upon completion of the assembly.

To obtain permanent copies of the pre-processor
temporary files, run the assembler with the pre­processor only option:

easm219x -pp -o example.tmp example.asm

EASM219x Default Pre-Processing

Flow of Control

EXAMPLE.ASM

#

PP.EXE

#

EXAMPLE.IS

When the -legacy option is specified, an
additional pre-processing pass is added after the
*.is is produced. It calls the legacy pre­processor asmpp.exe which processes the
.macro, .const, .include, and .local directives.
The legacy suffix convention for assembly
source was .DSP.

This runs the pre-processor on example.asm and
writes the temporary file example.is to the
current directory. It is not deleted.

easm219x -pp -legacy example.dsp

This runs the pre-processor on example.dsp and
leaves the temporary files example.is and
example.app in the current directory.

.CONST UPGRADE EXAMPLE

The .const directive is replaced by the C-style
#define macro and H# with 0x hex constant
syntax

21xx asmpp.exe

.CONST base=H#0D49,sqrt2=H#5A82;

EE-130 Page 6

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

219x pp.exe

#define base 0x0D49
#define sqrt2 0x5A82

uniqueLabel_2:
M5=1;I6=1;MODIFY(I6,M4);MR1=DM(I6,M5);
uniqueLabel_3:
M5=1;I6=1;MODIFY(I6,M4);MR1=DM(I6,M5);

PRE-PROCESSOR SYNTAX

.MACRO UPGRADE EXAMPLE

The .macro directive is replaced by the C-style
#define macro. The % arguments are replaced
by named arguments.

21xx asmpp.exe
.MACRO getsfirst(%1);
M5=1;I6=1;MODIFY(I6,M4);%1=DM(I6,M5)
.ENDMACRO;

getsfirst(MR1);

219x pp.exe
#define getsfirst(Rg) \
M5=1;I6=1;MODIFY(I6,M4);Rg=DM(I6,M5)

getsfirst(MR1);

PRE-PROCESSOR "?" EXAMPLE

The question mark "?" can be used to replace
the .local directive to avoid creating duplicate
labels when a macro is expanded multiple times.

219x pp.exe

If you are using the -legacy option, the legacy
pre-processor directives will be processed in
addition to the C pre-processor directives.
Without -legacy, rely solely on the C pre­processor directives.

" SEE APPENDIX B:

PRE_PROCESOR REFERENCE

EXPRESSIONS

There are places in the source where the
assembler processes symbols and literal
constants that may form expressions. We lump
these all under the category of "expressions".

SET POINTER

The "^" set point operator legacy syntax is
recognized when assembled with the -legacy
option. The "^" set point operator is no longer
required. Simply omit it when writing new code
for ADSP-219x.

-legacy Set Pointer

start: I2=^x_input;

#define getsfirst(Rg) \ uniqueLabel?: \ M5=1;I6=1;MODIFY(I6,M4);Rg=DM(I6,M5);

// MACRO-INVOCATIONS
//
getsfirst(MR1)
getsfirst(MR1)
getsfirst(MR1)

219x Set Pointer

start: I2=x_input;

DATA INITIALIZATION FILES

The .VAR directive accepts a list of one or more
initializers from an external data file that by
convention is a file ending in ".dat" and referred
to as "dat" files. The legacy behavior for

// POST-EXPANSIONS
// Each label is unique
//

uniqueLabel_1:
M5=1;I6=1;MODIFY(I6,M4);MR1=DM(I6,M5);

EE-130 Page 7

Technical Notes on using Analog Devices’ DSP components and development tools

Phone: (800) ANALOG-D, FAX: [phone], EMAIL: [e-mail], FTP: ftp.analog.com, WEB: www.analog.com/dsp

initializers in the dat files was quirky. It treated
initializers explicitly typed in.INIT and INIT24
differently than those read in from *.dat files.